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

Work with Ada API keys

To keep your data safe, all requests to the Data Export API must be authenticated. The way we authenticate your requests to any of Ada's APIs is through a key. An API key is like a password, but API keys are a lot more complex than a typical human password, which makes them a lot more secure.

You can use an existing API key that someone in your organization generated for your bot, if it was either specifically generated for the Data Export API, or if it's a newer, general key that works for all of Ada's APIs:

• If a key was generated for a specific API, that key will still only work for that API. The names for API-specific keys indicate which APIs they're associated with, followed by "(Legacy)".

• If a key was generated for all of Ada's APIs, you can use that key again, or you can create a new one by following the steps below. Your bot can have multiple active general API keys; creating a new one doesn't invalidate any existing keys.

Regardless of which type of key you have, they don't expire, and provide read and write access to all Ada APIs available to your organization.

Generate an Ada API key

You can generate a new Ada API key from the Ada dashboard, which works for all APIs your organization has access to.

1. On the Ada dashboard, go to Settings > Integrations > APIs. The API keys page opens.

2. Create a new API key:

   • If your bot doesn't have any API keys, click Get started.
   • If your bot has existing API keys, click New API key.

   The New API key window opens.

3. In the New API key window, enter a Name for the key, then click Generate key.

   You won't be able to change the key's name in the future.

4. Click Copy to copy your API key, then save it in a secure place immediately.

   important

   For security reasons, the Ada dashboard only displays your API key once. If you lose this key, you'll need to create a new one.

5. Click Done to close the New API Key window and protect your new API key.

Use the Data API access token

Place your Ada API key in the value field of the Bearer authentication header in your HTTP request tool, as indicated:

Header Key	Header Value
Authorization	Bearer <your_api_key>

Use the Data Export API

You can use our developer documentation for a detailed guide to creating Data Export API requests. The Data Export API has two endpoints:

• Conversations
• Messages

With these endpoints, you can export information about conversations or individual messages.

---

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