> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/data-export/data-export-v1-4/conversations/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.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/return-messages-matching-the-parameters).
## Attributes
| Attribute | Description | Type | v1.0 | v1.1 | v1.2 | v1.3 | v1.4 |
| :------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :--- | :--- | :--- | :--- | :--- |
| `_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` (v1.2)
`GET /api/data_api/v1.2/conversations?created_since=2022-03-16T17:59:28.201000&page_size=100`
```
{
"data": [
{
"_id": "62322580b151ff975f1eb495",
"agent_id": [
"60cb3ef9b72ebfacb39408da",
"619d95c0c063a5bf2b1efb7c",
],
"agent_name": [
"Hanif J",
"Abby L"
],
"browser": "chrome",
"browser_version": "98.0.4758.102",
"chatter_id": "6232257fb197d1ff65ea92fe",
"csat": {},
"date_created": "2022-03-16T17:59:28.201000+00:00",
"date_updated": "2022-03-16T18:11:46.988000+00:00",
"device": "macos",
"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",
"variables": {
"chat_transcript": "BOT: picture message\r\nBOT: 👋 Welcome to Ada Interact! \r\nBOT: If you're curious about any of the reports that Mike mentions, click \"Read the reports\" or just type in 'get the reports'. \r\nBOT: picture message\r\nBOT: 👋 Welcome to Ada Interact! \r\nBOT: If you're curious about any of the reports that Mike mentions, click \"Read the reports\" or just type in 'get the reports'. \r\n\r\nUSER: my manager cant get into the event\r\n\r\n\r\nSUMMARY: my manager cant get into the event."
}
}
],
"message": "OK",
"next_page_uri": "/data_api/v1.2/conversations?created_since=2022-03-16T18%3A05%3A27.536000&created_to=2022-03-23T17%3A59%3A28.201000&page_size=100"
}
```
### Get all conversations created within 1 week of `created_since` (v1.1)
`GET /data_api/v1.1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100`
**`JSON`**
```json JSON
{
"data": [
{
"_id": "",
"chatter_id": "",
"csat": {
"comment": null,
"feedback": [
"(helpful_resolution)"
],
"is_positive": true,
"resolved": true,
"score": 5,
"style": "EMOJI",
"survey_type": "end_chat"
},
"date_created": "2020-09-21T04:30:22.681000+00:00",
"date_updated": "2020-09-21T04:33:57.614000+00:00",
"is_engaged": true,
"is_escalated": false,
"metavariables": {
"browser": "chrome",
"browser_version": "85.0.4183.102",
"device": "macos",
"introshown": "False",
"language": "en",
"last_answer_id": "",
"last_question_asked": "Ada",
"test_user": "1",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
},
"platform": "chat",
"variables": {
"name": "Ada"
}
}
],
"message": "OK",
"next_page_uri": "/data_api/v1.1/conversations?created_since=2020-09-25T15%3A00%3A26.906000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}
```
### Get all conversations created within 1 week of `created_since` (v1)
`GET /data_api/v1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100`
**`JSON`**
```json JSON
{
"data": [
{
"_id": "",
"chatter_id": "",
"csat": {
"comment": null,
"feedback": [
"(helpful_resolution)"
],
"is_positive": true,
"resolved": true,
"score": 5,
"style": "EMOJI",
"survey_type": "end_chat"
},
"date_created": "2020-09-21T04:30:22.681000+00:00",
"date_updated": "2020-09-21T04:33:57.614000+00:00",
"is_engaged": true,
"is_escalated": false,
"metavariables": {
"browser": "chrome",
"browser_version": "85.0.4183.102",
"device": "macos",
"introshown": "False",
"language": "en",
"last_answer_id": "",
"last_question_asked": "Ada",
"test_user": "1",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
},
"platform": "chat",
"variables": {
"name": "Ada"
}
}
],
"message": "OK",
"next_page_uri": "/data_api/v1/conversations?created_since=2020-09-25T15%3A00%3A26.906000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}
```
## API Docs
- Conversations [Return conversations matching the parameters](https://docs.ada.cx/reference/data-export/data-export-v1-4/conversations/return-conversations-matching-the-parameters.md)
## OpenAPI Specification
The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.ada.cx/reference/data-export/data-export-v1-4/conversations/openapi.json)
- [OpenAPI YAML](https://docs.ada.cx/reference/data-export/data-export-v1-4/conversations/openapi.yaml)