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 / ISO 8601 format is used for query timestamps 
  • All fields and properties in the Dixa CSV export feature are available via this endpoint too 
  • The 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. 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_apiKey

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 <username:password in base64>. Thus the following two requests are equivalent:

curl -u "bearer:<token>" "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, for the time of creation and closing of conversations.

All of them expect "yyyy-MM-dd"/ ISO 8601 formats.

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

Parameters can be mixed and matches as clients see fit.

Examples using curl

Get metadata for all conversations created on August 1, 2019

curl -u "bearer:<token>" "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:<token>" "https://exports.dixa.io/v1/conversation_export?created_before=2019-09-01&created_after=2019-08-01"

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 conversation0
    "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
//NOTE: Conversations theoretically can have more than one rating, this gives the first value found, which allows to keep the BI tools friendly flat structure
    "rating_score": null, //[Int] Rating score coming from chat widgets
    "rating_message": null, //[String] Rating message associated with the rating score
    "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] Provisioned phone number id, which is the phone number itself
    "to_provisioned_phone_number_name": null, //[String] Name of the provisioned 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
  }
]

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 to whom 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).
Ratings_score - the rating given by end user for a conversation (only available for chats currently. 1 = good rating and 0 = bad rating, blank means no rating by end user).
Ratings_feedback - a comment the customer gives to a conversation along with a rating.
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.