> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/generative/data-export-conversation-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.
# Conversation object
A `conversation` object is created any time a new chatter engages with Ada, or a returning chatter starts a new conversation in accordance with your persistence settings in Ada. A conversation is a higher-order object that contains messages, which you can access via the [Messages endpoint](/data-export-message-object/get-messages).
## Attributes
| Attribute | Description | Type | v1.0 | v1.1 | v1.2 | v1.3 | v1.4 | v2 |
| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :--- | :--- | :--- | :--- | :--- | :- |
| `_id` | The unique ID of the conversation. | String | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `agent_handle_time` | The amount of time it took for a human agent to resolve the conversation, in seconds. | String | | | | | ✔ | ✔ |
| `agent_id` | The list of unique IDs for agents involved in the conversation (for example, `619d95c0c063a5bf2b1efb7c`). | Array | | | ✔ | ✔ | ✔ | ✔ |
| `agent_name` | A list of names of the agents involved the conversation, corresponding to the agent IDs. | Array | | | ✔ | ✔ | ✔ | ✔ |
| `automated_resolution` `_classification` | Classification of either Resolved or Not Resolved for the conversation. Example: Resolved | String | | | | ✔ | ✔ | ✔ |
| `automated_resolution`, `_classification_reason` | Explanation of the reason for the assigned `automated_resolution_classification`. Example: The bot provided a detailed step-by-step guide on how to disable auto deposits, both on the mobile app and the web version. | String | | | | ✔ | ✔ | ✔ |
| `bot_handle_time` | The amount of time it took for the bot to resolve the conversation, in seconds. | String | | | | | ✔ | ✔ |
| `browser` | The type of browser the chatter was using (for example, `chrome`). | String | | | ✔ | ✔ | ✔ | ✔ |
| `browser_version` | The specific version number of the chatter's browser. | String | | | ✔ | ✔ | ✔ | ✔ |
| `chatter_id` | The unique chatter ID. | String | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `csat` | The CSAT score for the conversation. Note that only CSAT 2.0 data is available in the conversations endpoint. | JSON Dictionary | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `date_created` | The timestamp indicating when the conversation was created. | UTC Timestamp | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `date_updated` | The timestamp indicating when the conversation was last updated. | UTC Timestamp | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `device` | The device type or operating system (for example, `macos`). | String | | | ✔ | ✔ | ✔ | ✔ |
| `end_user_id` | The End User ID used to identify the chatter profile in the conversation (for example, `619d95c0c063a5bf2b1efb64e`). | String | | | | | ✔ | ✔ |
| `generated_topic_id` | The unique ID Ada associated with the generated conversation topic (for example, `654952d3e90767ff49713fbf`). This field uses an old version of Ada's conversation topics feature. It exists so you can still view data for conversations that happened before May 2024. | String | | | | | ✔ | ✔ |
| `generated_topic_label` | The title of the generated conversation topic (for example, `Billing Inquiries`). This field uses an old version of Ada's conversation topics feature. It exists so you can still view data for conversations that happened before May 2024. | String | | | | | ✔ | ✔ |
| `generated_topic_v2_desc` | The description of the generated conversation topic using Topics V2 (for example, `All conversations regarding resetting passwords`). This field uses the current version of Ada's conversation topics feature, released in May 2024. It is empty for older conversations. | String | | | | | ✔ | ✔ |
| `generated_topic_v2_id` | The unique ID Ada associated with the generated conversation topic using Topics V2 (e.g., `654952d3e90767ff49713fb1`). This field uses the current version of Ada's conversation topics feature, released in May 2024. It is empty for older conversations. | String | | | | | ✔ | ✔ |
| `generated_topic_v2_parent_id` | The unique ID Ada associated with the generated conversation topic's parent category topic (for example, `654952d3e90767ff49713fb2`, or `null` if the topic has no parent category topic). This field uses the current version of Ada's conversation topics feature, released in May 2024. It is empty for older conversations. | String | | | | | ✔ | ✔ |
| `generated_topic_v2_title` | The title of the generated conversation topic using Topics V2 (for example, `Password Reset Inquiries`). This field uses the current version of Ada's conversation topics feature, released in May 2024. It is empty for older conversations. | String | | | | | ✔ | ✔ |
| `inquiry_summary` | Automatically generated summary of the customer's inquiry (for example, `The customer wanted to know how to temporarily disable auto deposits`). | String | | | | ✔ | ✔ | ✔ |
| `is_engaged` | Indicates whether the chatter sent at least one message to start the conversation after Ada served a greeting. | Boolean | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `is_escalated` | Indicates if the chatter was handed off to an integrated CX platform, an email ticket, or escalated to an agent. | Boolean | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `is_test_user` | Whether or not the conversation involved a test user (indicated by `true` or `false`). | Boolean | | | ✔ | ✔ | ✔ | ✔ |
| `language` | The language of the conversation, represented by a language code in [ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (for example, `fr`). | String | | | ✔ | ✔ | ✔ | ✔ |
| `metavariables` | The metavariables stored by Ada. | JSON Dictionary | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `oauth_channel` | If the client has been authenticated using OAuth 2.0, this field indicates the channel on which the authenticated conversation took place (for example, `chat` or `sms`). *Values*
chat email http messagingapi messenger sms sunshine sunshine_android sunshine_api sunshine_apple sunshine_instagram sunshine_ios sunshine_line sunshine_messagebird sunshine_messenger sunshine_slack sunshine_slackconnect sunshine_switchboard sunshine_telegram sunshine_twilio sunshine_twitter sunshine_viber sunshine_web sunshine_whatsapp test voice | String | | | ✔ | ✔ | ✔ | ✔ |
| `platform` | The Ada platform on which this conversation occurred (for example, `chat`, `sms`, `instagram`, or `twilio`). *Values*
apple chat email http instagram kik line messagingapi messenger smooch sms sunshine_android sunshine_api sunshine_apple sunshine_instagram sunshine_ios sunshine_line sunshine_messagebird sunshine_messenger sunshine_slack sunshine_slackconnect sunshine_switchboard sunshine_telegram sunshine_twilio sunshine_twitter sunshine_viber sunshine_web sunshine_whatsapp twilio twitter voice web whatsapp | String | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `record_last_updated` | The timestamp indicating when the record was uploaded to the API. | UTC Timestamp | | | | | ✔ | ✔ |
| `variables` | The unique variable values for the conversation. The maximum length is 1000 characters in versions 1.2 and earlier. | JSON Dictionary | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
## Responses
Below are some examples of the data returned in a `conversation`. A conversation can be created, and then later updated, with values changing based on the latest message within it.
> **Note**
>
> Only CSAT v2 data is supported in responses from the Conversations endpoint.
### Get all conversations created within 1 week of `created_since` (v2)
`GET /api/v2/export/conversations?created_since=2024-03-16T17:59:28.201000&page_size=100`
```
{
"data": [
{
"_id": "62322580b151ff975f1eb495",
"agent_handle_time": null,
"agent_id": [
"60cb3ef9b72ebfacb39408da",
"619d95c0c063a5bf2b1efb7c",
],
"agent_name": [
"Hanif J",
"Abby L"
],
"automated_resolution_classification": "Unclear",
"automated_resolution_classification_reason": "The customer's intent was not clear in the conversation.",
"bot_handle_time": 2.0,
"browser": "chrome",
"browser_version": "98.0.4758.102",
"chatter_id": "6232257fb197d1ff65ea92fe",
"csat": {
"survey_type": "answer_flow",
"score": 5,
"style": "NUMERIC",
"is_positive": true,
"feedback": null,
"resolved": null,
"comment": null
},
"date_created": "2022-03-16T17:59:28.201000+00:00",
"date_updated": "2022-03-16T18:11:46.988000+00:00",
"device": "macos",
"end_user_id": null,
"generated_topic_id": "6232257fb197d1ff65ea92fe",
"generated_topic_label": "Customer Satisfaction Inquiry",
"generated_topic_v2_id": null,
"generated_topic_v2_title": null,
"generated_topic_v2_desc": null,
"generated_topic_v2_parent_id": null,
"inquiry_summary": "The customer's inquiry is unclear as they only mentioned 'satisfaction'.",
"is_engaged": true,
"is_escalated": true,
"is_test_user": false,
"language": "en",
"metavariables": {
"browser": "chrome",
"browser_version": "98.0.4758.102",
"device": "macos",
"followupresponseid": "6216a263c0c9f28ed7a16c1d",
"introshown": "False",
"ip_address": "184.146.191.63",
"language": "en",
"last_answer_id": "622bacf18d48fea09fe32fc8",
"last_question_asked": "thanks!",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102 Safari/537.36"
},
"oauth_channel": "chat",
"platform": "chat",
"record_last_updated": null,
"variables": {
"my_custom_variable": "custom variable value"
}
}
],
"meta": {
"next_page_uri": "https://.ada.support/api/v2/export/conversations?created_since=2024-03-15T14%3A01%3A01.563000%2B00%3A00&created_to=2024-09-22T00%3A00%3A00%2B00%3A00&page_size=100"
}
}
```
## API Docs
- [Return conversations matching the parameters](https://developers.ada.cx/generative/data-export-conversation-object/get-conversations.md): Conversations
## OpenAPI Specification
- [OpenAPI JSON](https://developers.ada.cx/openapi.json): raw OpenAPI 3.1 specification for this API, JSON format
- [OpenAPI YAML](https://developers.ada.cx/openapi.yaml): raw OpenAPI 3.1 specification for this API, YAML format