Ada Data Export API
Access conversation and message records for downstream analytics, storage, and reporting.
OpenAPI Specification
openapi: 3.1.0
info:
title: Data Export
version: 1.0.0
paths:
/v2/export/conversations:
get:
operationId: get-conversations
summary: Return conversations matching the parameters
description: Returns a list of `conversation` objects along with a `next_page_uri` if applicable
tags:
- subpackage_conversations
parameters:
- name: created_since
in: query
description: >-
Return records that were created after this date. If `created_to` is not specified, only records within 7
days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Note
that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must
be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API
requests.
required: false
schema:
type: string
format: date-time
- name: updated_since
in: query
description: >-
Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually
exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g.,
`2024-07-01T00:00:00Z`); required for valid API requests.
required: false
schema:
type: string
format: date-time
- name: page_size
in: query
description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
required: false
schema:
type: integer
default: 10000
- name: created_to
in: query
description: >-
Return records that were created earlier than this date. If `created_since` is used and this parameter is
not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending
with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
required: false
schema:
type:
- string
- 'null'
format: date-time
- name: updated_to
in: query
description: >-
Return records that were updated earlier than this date. If `updated_since` is used and this parameter is
not specified, this value defaults to 7 days after `updated_since`. Must be an ISO 8601 UTC timestamp ending
with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
required: false
schema:
type:
- string
- 'null'
format: date-time
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Ada successfully processed the request
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Authorization Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/v2/export/messages:
get:
operationId: get-messages
summary: Return messages matching the parameters
description: Returns a list of `message` objects along with a `next_page_uri` if applicable
tags:
- subpackage_messages
parameters:
- name: created_since
in: query
description: >-
Return records that were created after this date. If `created_to` is not specified, only records within 7
days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Must
be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API
requests.
required: true
schema:
type: string
format: date-time
- name: conversation_id
in: query
description: Return records with a `conversation_id` that matches this id
required: false
schema:
type:
- string
- 'null'
format: id
- name: page_size
in: query
description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
required: false
schema:
type: integer
default: 10000
- name: created_to
in: query
description: >-
Return records that were created earlier than this date. If not specified, this value defaults to 7 days
after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`);
required for valid API requests.
required: false
schema:
type:
- string
- 'null'
format: date-time
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Ada successfully processed the request
content:
application/json:
schema:
$ref: '#/components/schemas/MessagesResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Authorization Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
servers:
- url: https://example.ada.support/api
description: https://example.ada.support/api
components:
schemas:
ConversationCsat:
type: object
properties: {}
description: Object of customer satisfaction survey data for this conversation
title: ConversationCsat
ConversationMetavariables:
type: object
properties: {}
description: Object of metavariables and their values active during this conversations
title: ConversationMetavariables
ConversationVariables:
type: object
properties: {}
description: Object of autocapture and global variables and their values last active during this conversations
title: ConversationVariables
Conversation:
type: object
properties:
_id:
type: string
description: Unique ID for the conversation record
agent_id:
type: array
items:
type: string
description: The list of unique IDs for agents involved in the conversation
agent_handle_time:
type: number
format: double
description: Time taken for a human agent to handle a conversation in seconds
agent_name:
type: array
items:
type: string
description: A list of names of the agents involved the conversation, corresponding to the agent IDs
automated_resolution_classification:
type: string
description: Classification of either Resolved or Not Resolved for the conversation
automated_resolution_classification_reason:
type: string
description: Explanation of the reason for the assigned automated_resolution_classification
bot_handle_time:
type: number
format: double
description: Time taken for the AI agent to handle a conversation in seconds
browser:
type: string
description: The browser used by the chatter
browser_version:
type: string
description: The version of the browser used by the chatter
chatter_id:
type: string
description: Ada ID of the chatter having this conversation
csat:
$ref: '#/components/schemas/ConversationCsat'
description: Object of customer satisfaction survey data for this conversation
date_created:
type: string
format: date-time
description: Date and time the record was created (UTC)
date_updated:
type: string
format: date-time
description: Last date and time the record was updated (UTC)
device:
type: string
description: The device the chatter used, such as iphone, android, etc.
end_user_id:
type:
- string
- 'null'
description: The End User ID used to identify the chatter profile in the conversation
generated_topic_id:
type: string
description: The unique ID Ada associated with the generated conversation topic
generated_topic_label:
type:
- string
- 'null'
description: The title of the generated conversation topic
generated_topic_v2_id:
type:
- string
- 'null'
description: The unique ID Ada associated with the generated conversation topic using Topics V2
generated_topic_v2_title:
type:
- string
- 'null'
description: The title of the generated conversation topic using Topics V2
generated_topic_v2_desc:
type:
- string
- 'null'
description: The descrtiption of the generated conversation topic using Topics V2
generated_topic_v2_parent_id:
type:
- string
- 'null'
description: >-
The unique ID Ada associated with the generated conversation topic's parent category topic. Null if topic
has no parent category topic.
inquiry_summary:
type: string
description: An automatically generated summary of the customer's inquiry
is_engaged:
type: boolean
description: Whether the chatter engaged with the bot during this conversation
is_escalated:
type: boolean
description: Whether the chatter escalated to a live agent during this conversation
is_test_user:
type: boolean
description: Whether the conversation was started by a test user
language:
type: string
description: The language the chatter used
metavariables:
$ref: '#/components/schemas/ConversationMetavariables'
description: Object of metavariables and their values active during this conversations
oauth_channel:
type: string
description: The channel used by Oauth
platform:
type: string
description: Ada platform through which this conversation occurred
record_last_updated:
type:
- string
- 'null'
format: date-time
description: Date and time the record was uploaded to the API
variables:
$ref: '#/components/schemas/ConversationVariables'
description: Object of autocapture and global variables and their values last active during this conversations
title: Conversation
ConversationsResponseMeta:
type: object
properties:
next_page_uri:
type:
- string
- 'null'
description: Link to the next page of results matching the query
title: ConversationsResponseMeta
ConversationsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Conversation'
description: Records returned from the query
meta:
$ref: '#/components/schemas/ConversationsResponseMeta'
title: ConversationsResponse
ErrorsErrorsItems:
type: object
properties:
type:
type: string
description: The error type
message:
type: string
description: The error message
details:
type:
- string
- 'null'
description: Extra information about the error
required:
- type
- message
title: ErrorsErrorsItems
Errors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsErrorsItems'
description: A list of errors
required:
- errors
title: Errors
MessageMessageData:
type: object
properties: {}
description: Data associated with this message
title: MessageMessageData
Message:
type: object
properties:
_id:
type: string
description: Unique ID for the message record
answer_id:
type:
- string
- 'null'
description: >-
Internal ID of the answer (response) that triggered this message. Null if the message was not sent by an Ada
bot, and None if it was sent by a generative bot.
answer_title:
type:
- string
- 'null'
description: >-
Title of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot,
or if it was sent by a generative bot.
chatter_id:
type:
- string
- 'null'
description: Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects.
conversation_id:
type: string
description: >-
Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of
Conversation objects.
date_created:
type: string
format: date-time
description: Time the record was created (UTC)
link_was_clicked:
type:
- boolean
- 'null'
description: Indicates if the link in the answer (response) was clicked
message_data:
$ref: '#/components/schemas/MessageMessageData'
description: Data associated with this message
recipient:
type: string
description: Recipient of this message
record_last_updated:
type: string
format: date-time
description: Date and time the record was uploaded to the API (UTC)
review:
type: integer
description: Rating given to this answer by the chatter
sender:
type: string
description: Sender of this message
in_response_to:
type: string
description: >-
Internal ID of the message that this message is in response to. None if the message is not in response to
another message.
title: Message
MessagesResponseMeta:
type: object
properties:
next_page_uri:
type:
- string
- 'null'
description: Link to the next page of results matching the query
title: MessagesResponseMeta
MessagesResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Message'
description: Records returned from the query
meta:
$ref: '#/components/schemas/MessagesResponseMeta'
title: MessagesResponse
securitySchemes:
bearerAuth:
type: http
scheme: bearer