Export conversation and message data

Overview

The Data Export API provides authenticated access to your bot's conversation and message data. You can then export this information to your data warehouse for your own intelligence tool to ingest.

note

This feature may not be included with your organization's subscription package. For more information, see Ada's Pricing page, or contact your Ada team.

The following are the primary use cases for the Data Export API:

• Analytics – Perform data analysis in your own business intelligence tool.

• Compliance – Save conversations permanently in your own system.

• Accessibility – Easily retrieve conversation data when requested by your customer.

The Data Export API is built according to REST principles, a style of software architecture for network applications. Request bodies, the instructions you send to the API, should be composed using JSON. The API responds with either a Conversation or a Message object, depending on which endpoint you're querying. These objects contain the information you've requested.

Data Export API usage limitations

To ensure a smooth experience and to minimize the potential for any downtime, you should be aware of limitations with the ingestion time, the rate limit, the page size and the date range.

Data ingestion time

It takes at least two hours to ingest conversation data into the Data API database. This means that queries won't return data from conversations created within the previous two hours.

There are occasional delays when ingesting conversation data; if you did not receive the data you are expecting, please contact your Ada team.

Refer to the data export overview in our developer documentation for complete details about setting up requests to the Data Export API.

Rate limit

The Data Export API is subject to a rate limit of 3 requests/second per endpoint. If you exceed the rate limit, you may receive a 429 Too Many Requests response status code. We employ rate limits to ensure the stability of our infrastructure for you and for all our clients.

Page size and date range limitations

In addition to rate limits, we’ve implemented page size and date range limitations.

• Maximum 10,000 records per page

• Exports are limited to records from the previous year

The Data Export API access token

To keep your bot data safe, all requests to the Data Export API must be authenticated. The way we authenticate your request is through the use of an access token. An API access token is to applications what a password is to humans; but API tokens are a lot more complex than a typical human password, which makes them a lot more secure.

Generate the Data API access token

You generate your Data Export API access token right from the Ada dashboard. Only one access token can exist at a time. If an access token already exists, generating a new one will invalidate it and access to the Data Export API will be denied. In this case, restoring access requires you to replace all instances of the old token with the new token you've just generated.

1. Go to Settings > Integrations > API Integrations.

2. Beside Data Export API, click Configure.

   

3. In the Data Export API dialog box, click Generate a new Access Token to generate a unique API access token.

   

4. Click the Copy button to the right of the API Access Token field to copy the access token.

   important

   Save the access token in a temporary but secure location before closing the Data Export API dialog box. You cannot access the token again via the dashboard once you've closed the dialog box.

Use the Data API access token

For security purposes, only one access token can be active at a time. Activating a second token revokes the first token. You'll then have to update all instances of that first token to restore access to the Data Export API.

note

Ada does not store Data API access tokens, and therefore can't reinstate invalidated tokens.

Place the Data Export API access token in the value field of the Bearer authentication header in your HTTP request tool, as indicated:

Header Key	Header Value
Authorization	Bearer <your_api_token>

Use the Data Export API

This section covers some basic information for using the Data Export API. Refer to our developer documentation for a more detailed guide to creating Data Export API requests.

Available endpoints

There are two endpoints available through the Data Export API—the Conversations endpoint, and the Messages endpoint. Each provides specific details related to the objects about which they report.

The following two sections list the data returned from each endpoint. The actual variable name from the response body appears in parenthesis.

Conversations endpoint

The Conversations endpoint returns data about the Conversations your bot has with your chatters. Conversation data includes information such as the chatter ID, whether the chatter was escalated, the platform where the Conversation took place, etc.

Data	Description
Conversation ID (_id)	The conversation's unique ID.
Conversation date (date_created)	The conversation's creation date.
Last conversation update (date_updated)	The date of last conversation update.
Chatter ID (chatter_id)	The chatter's unique ID.
Platform (platform)	The platform where the conversation took place.
Engaged? (is_engaged)	Was the conversation engaged or not.
Escalated? (is_escalated)	Was the chatter escalated during the conversation.
CSAT (csat)	The CSAT rating the chatter gave the conversation.
Variables (variables)	List of the variables captured or created in the conversation.
Metavariables (metavariables)	List of the stored metavariables and their values.

Messages endpoint

The Messages endpoint returns data about individual messages within a Conversation. This includes information like the sender and receiver, the time the message was sent, what Conversation it came from, etc.

Data	Description
Message ID (_id)	The message's unique ID.
Message date (date_created)	The date the message was sent.
Conversation ID (conversation_id)	The unique ID of the conversation the message belongs to.
Message content (message_data)	The details and content of the message.
Message sender (sender)	The sender of the message. The chatter ID if sent by the chatter, agent, or bot.
Message recipient (recipient)	The recipient of the message. The chatter ID if received by the chatter, agent, or bot.
Reviewed? (review)	Did the chatter give the Answer either a thumbs up or thumbs down?
Title of Answer served (answer_title)	The title of the Answer the bot served to the chatter in response to the message.

---

Have any questions? Contact your Ada team—or email us at [email protected].