Dixa is all about breaking down silos - also between systems. Therefore we enable you to export your conversations and use this data in any major data analytics tool of your choice.

  • API access to get a list of conversations. ⬇️
  • Use results for engagement metrics and to drive business processes. 📊💯
  • An elegant and standardized alternative to our CSV export feature. 😎

The Export Conversations API lives on the side of our existing Integrations API, which supports creating a new conversation, creating a new user and getting a list of users, list of tags and a list of queues. With the Export Conversations API, you will also be able to get a list of conversations, so you can feed them into any Business Intelligence or Analytics tool of your choice. In short, the main use case of this particular endpoint is not to support REST-style access to Dixa resources, but rather to enable BI/Analytics tools and workflows to easily access conversations from a specific point in time.




Further information:

  • LocalTime format (yyyy-mm-dd) is used for query timestamps.
  • All fields and properties in the Dixa CSV export feature are available via this endpoint, too. 
  • There are no offset or limit pagination rules for the endpoint, limits on queries are instead defined by time. In other words, no query can span more than 1 month (31 days). Here, the request must have at least one _after and one _before parameter. There are no other query limitations. 
Hostnames, Endpoint Details, and Authentication 

Access the endpoint by pointing curl or similar to https://exports.dixa.io/v1/conversation_export (incl. the parameters for the timeframe you would like to request data for - see examples further below)

In order to access the endpoint you need to use username: bearer and password: your_Dixa_apiToken

Additional information:

  • At this time, only the GET verb is supported. 
  • The endpoint will return a stream of JSON objects in an array. 
  • See the end of this document for a description of the schema.
  • Authentication expects an Api Token to be present in the request headers.

    Authentication is set in requests using Basic Authentication. Please see the examples for more details.  

Authentication token

The token can be generated inside your Dixa organization under Settings -> integrations -> API token

Once you have your token you can test out the request with curl. 

The authentication in the example is provided with the curl -u "username:password", which gets translated to the following HTTP header:
Authorization:Basic . Thus the following two requests are equivalent:

curl -u "bearer:" "https://exports.dixa.io/v1/conversation_export?&created_after=2019-11-01&created_before=2019-11-30"
encoded_credentials=$(echo "bearer:token" | base64) curl -H "Authorization:Basic ${encoded_credentials}" "https://exports.dixa.io/v1/conversation_export?created_after=2019-11-01&created_before=2019-11-030"

Thus, any downstream application must be configured accordingly. Most of the HTTP libraries provide an abstraction layer for dealing with basic HTTP credentials. In the future, we are planning to allow the authentication with both plain token values, as well as encoded.

Status codes: 
  • 5xx - Sorry, an error has occurred 
  • 401 - Invalid or missing credentials 
  • 400 - Invalid query parameters
  • 200 - Query OK, data will follow  
Query parameters:

Currently, all query parameters act like filters.

All of the date parameters expect "yyyy-MM-dd"/ ISO 8601 formats.

csids expect a comma separated list of integer Ids.

Available parameters are:

  • closed_after - All returned conversations must be closed after the closed_after timestamp
  • closed_before - All returned conversations must be closed before the closed_before timestamp
  • created_after - All returned conversations must be created after the created_after timestamp
  • created_before - All returned conversations must be created before the created_before timestamp
  • updated_after - All returned conversations must be updated after the updated_after timestamp
  • updated_before - All returned conversations must be updated before the updated_before timestamp
  • last_message_created_before - All returned conversations must have the last associated message created before the last_message_created_before timestamp
  • last_message_created_after - All returned conversations must have the last associated message created after the last_message_created_after timestamp

Date parameters can be mixed and matched as clients see fit.

  • csids - All returned conversations must match Id with one of the specified in csids set. Note: This parameter cannot be mixed with other date parameters specified above. The parameter also expects a comma separated list of integer Ids. Example: csids=2345,123,876 or csids=98 for single conversation.


Examples using curl

Get metadata for all conversations created on August 1, 2019

curl -u "bearer:" "https://exports.dixa.io/v1/conversation_export?created_before=2019-08-02&created_after=2019-08-01"

Get metadata for all conversations created during August 2019 

curl -u "bearer:" "https://exports.dixa.io/v1/conversation_export?created_before=2019-09-01&created_after=2019-08-01"

Get conversations with ids 45, 99, 173 :

curl -u "bearer:" "https://exports.dixa.io/v1/conversation_export?csids=45,99,173"
Schema:
  • [String] - Represents a sequence of characters
  • [UUID] - A fixed-length hexadecimal field representing the id of some entity
  • [Timestamp] - Date field in the format of milliseconds since Unix Epoch
  • [Int] - Represents an integer 
  • [Array[String]] - represents a collection of strings
Example request:
[
  {
    "id": 86893, //[NOT NULL] [Int] Id of the conversation
    "created_at": 1564748503749, //[NOT NULL] [Timestamp] The value of when the conversation was created
    "initial_channel": "email", //[NOT NULL] [String] The value of the channel through which the communication was established
    "requester_id": "7abb0ef7-6ff4-4c36-bcf7-f698b55b0981", //[NOT NULL] [UUID] Id of the requester 
    "requester_name": "Niels Hennning Ørsted Pedersen, //[String] Provides the requester name if exists corresponding to the requester_id
    "requester_email": "nhop@email.com", //[String] Provides the requester email if exists corresponding to the requester_id
    "requester_phone_number": null, //[String] Provides the requester phone number if exists corresponding to the requester_id
    "queued_at": 1564992883045, //[Timestamp] The value of when conversation was queued
    "queue_id": "de520585-c9fa-4963-aa45-6865b78c79aa", //[UUID] Id of the queue
    "queue_name": "Example Queue", //[String] Queue name associated with the queue_id
    "closed_at": 1565677523160, //[Timestamp] The value of when the conversation was closed
    "rating_score": null, //[Int] Rating score (0;1) //NOTE: This field is only relevant if you have set up the thumbs up/down ratings
    "rating_message": null, //[String] Rating message associated with the rating score //NOTE: This field is only relevant if you have set up the thumbs up/down ratings
"ratings": [ {
"rating_score": 1, //[Int] Rating score //NOTE: Score will be 0 or 1 for thumbs up & down ratings or 1-5 for new CSAT ratings "rating_message": "feedback",//[String] Rating message associated with the rating score "rating_type": null,//[String] Rating type associated with the rating score //NOTE: For our current version, this will always be null
"rating_created_timestamp": null,//[Timestamp] The value of when the CSAT was created "rating_offered_timestamp": 1593594380959, //[Timestamp] The value of when the CSAT was offered
"rating_status": "rated", //[String] The status associated with the rating
"rating_language": "en", //[String] The language set for the conversation
"rating_modified_timestamp": 1593594380959, //[Timestamp] The value of when the rating was lastly modified
"rating_rated_timestamp": 1593594380959, //[Timestamp] The value of when the conversation was rated
"rating_scheduled_timestamp": 1593594380959, //[Timestamp] The value of when the CSAT was scheduled
"rating_scheduled_for_timestamp": 1593594380959, //[Timestamp] The value of when the CSAT was scheduled
"rating_unscheduled_timestamp": 1593594380959, //[Timestamp] The value of when the CSAT was unscheduled
"rating_cancelled_timestamp": 1593594380959, //[Timestamp] The value of when the CSAT was cancelled
}
], "direction": "outbound", //[String] Direction of the conversation, at the time of writing, can have values inbound or outbound     "assigned_at": 1565677424029, //[Timestamp] The value of when the conversation was assigned to someone     "assignee_id": "531f6bac-d5a7-41d5-85d3-339bdabc18e9", //[UUID] Id of the user that the conversation was assigned to     "assignee_name": "Mike The Agent", //[String] Name associated with the assignee_id     "assignee_email": "mike@agents.com", //[String] Email associated with the assignee_id     "assignee_phone_number": "+4577337109", //[String] Phone number associated with the assignee_id     "to_provisioned_phone_number_id": null, //[String] Called(for inbound calls) phone number id, which is the phone number itself     "to_provisioned_phone_number_name": null, //[String] Name of the called phone number provided     "total_duration": 929019411, //[Int] The duration of the call in seconds if it exists. This is a derived value closed_at - created_at     "handling_duration": 99131, //[Int] Handling duration in seconds. This is a derived value closed_at - assigned_at     "dixa_email_integration_id": "demo-exports@email.dixa.io",//[String] The id of the email integration, which is the email address itself     "dixa_email_integration_sender_name": null, //[String] The sender name of the email integration, if it exists     "forwarding_email": null, //[String] The forwarding email address     "facebook_page_id": null, //[String] The page id coming from facebook     "facebook_page_name": null, //[String] The page name associated with the id     "widget_id": null, //[UUID] Id of the widget that was used     "widget_name": null, //[String] Name of the widget associated with the id     "tags": null, //[Array[String]] All the tags associated with the conversation     "conversation_wrapup_notes": null, //[Array[String]] The notes associated with the conversation //Transferred to id is currently not present in the exports file, but we can easily add it, if anyone needs it     "transferee_name": "Example Queue", //[String] Target entity name of the transfer, which is either a queue or a user     "transfer_time": 1565677412280, //[Timestamp] Transfer time of the latest transfer     "originating_country": null, //[String] Country the conversation originates from "status": "open", //[String] Status of the conversation, at the time of writing could be "open", "closed", "pending", "awaitingpending" "updated_at": 1565677523160, //[Timestamp] The value of when the conversation was last time updated "last_message_created_at": 1565677511160, //[Timestamp] The value of when the last associated message was created "from_provisioned_phone_number_id": null, //[String] Calling(for outbound calls) phone number id, which is the phone number itself     "from_provisioned_phone_number_name": null, //[String] Name of the calling phone number provided } ]

Information available in the conversations export:

Id - The unique number of the conversation in your Dixa account. You can add a link to the conversation ID for quick access to the conversation from the document.

Channel - Shows you the source channel of the conversation.

Created_at - the timestamp when the conversation was first created in the system.
Requester_name - the end user/customer name.
From_number - the phone number a call was initiated from.
Requester_email - the end user/customer email address (relevant for email conversations). 
Queued_at - the timestamp when the conversation first reached a queue (after having followed the nodes in the flow for that specific channel)
Queue - the name of the queue the conversation was received to.
Assigned_at - the timestamp when the conversation was first assigned to an agent
Closed_at - the timestamp when the conversation was first closed/answered (e.g. when you send an email the conversation is closed automatically).
Direction - the direction of the conversation, can be either inbound or outbound.
Assignee_email - the email address of an agent/admin who accepted/claimed the conversation.
Assignee_name - the name of an agent/admin who accepted/claimed the conversation.
Originating_country - the country code of an outbound phone conversation.
To_number - the phone number a call was aimed for.
Tags - tags used on a conversation. You can use filter to search for particular tags and for tag combinations like Shipping,Delayed.



Notes - notes left on a conversation, here you can search for particular notes with particular content.
Transferee_name - a name of the person or a name of the queue to whom/which the conversation was transferred to (used for internal conversation transfer).
Transferee_number - a phone number of a person to whom the conversation was transferred to (used for assisted/cold transfer to external number).
Rating_score - the rating given by the end user for a conversation; if CSAT is set up the score can be 1 (= bad rating) to 5 (= good rating); if CSAT is not set, the score can be thumbs up (1 = good rating) or thumbs down (0 = bad rating); blank means no rating by end user.
Rating_message - a comment the customer gives to a conversation along with a rating.
Rating_type - the type of rating; for our current CSAT version this is always "null".
Rating_created_timestamp - the time a CSAT was first created by scheduling or cancelling. 
Rating_offered_timestamp - the time a CSAT was offered.
Rating_status - the status of the CSAT, with the options "scheduled, unscheduled, offered, rated, cancelled."
Rating_language - the language a conversation is set in.
Rating_modified_timestamp - the last time the CSAT was updated.
Rating_rated_timestamp - the time a conversation was rated.
Rating_scheduled_timestamp - the time a CSAT was scheduled.
Rating_scheduled_for_timestamp - the time that gets set when scheduling a CSAT rating. If a rating gets cancelled, this field is not longer relevant.
Rating_unscheduled_timestamp - the time a CSAT was unscheduled.
Rating_cancelled_timestamp - the time a CSAT was cancelled.
Total_duration - the time between created_at and closed_at timestamps for a conversation (when a conversation is reopened the duration is recalculated correspondingly). Time is in milliseconds.
Handling_duration - the time between assigned_at and closed at timestamps for a conversation, (when a conversation is reopened the duration is recalculated correspondingly). Time is in milliseconds.
Inbound_forwarding_email - the company email you forward inbound emails from (your personal domain).
Inbound_dixa_email - the Dixa email you forward inbound emails to (with email.dixa.io domain).
Widget_id - the unique Id of your chat widget (can be seen in settings/chat/setup.
Outbound_dixa_email - the email address used for outbound email conversation (with popper SPF setup it will be company domain, without SPF setup - it will be equal to inbound_dixa_email.
Widget_label - a user-friendly name of a chat widget.
organization_phone_number_label.
Facebook_page_name - a user-friendly name of your facebook page in Dixa.
Facebook_page_id - the unique Id of your facebook widget (can be seen in settings/messaging.
Status - a string indicating status of the conversation. At the time of writing may be "open", "closed", "pending", "awaitingpending".
Updated_at - the timestamp when the conversation was updated the last time.
Last_message_created_at - the timestamp when the last associated message was created.