> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/data-export-conversation-object/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/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 | | | ✔ | ✔ | ✔ | ✔ |
| `changeset_id` | The unique ID of the change set the conversation ran against (for example, `66f1a0c063a5bf2b1efb7c12`). Returns `baseline` when the conversation ran against your live AI Agent. | String | | | | | | ✔ |
| `chatter_id` | The unique chatter ID. | String | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `classifications` | The Topic and Intent classifications for the conversation. Each entry includes a `topic_id`, `topic_name`, and a list of `intents` (each with `intent_id`, `intent_name`, and `status`). Returns an empty array when the conversation has no classifications. | Array | | | | | | ✔ |
| `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 | | | ✔ | ✔ | ✔ | ✔ |
| `last_agent_id` | The unique ID of the Agent who most recently handled the conversation (latest activity timestamp). Returns `null` when no Agent was assigned. Populated only for clients on the generative export path. | String | | | | | | ✔ |
| `last_agent_name` | The name of the Agent who most recently handled the conversation, corresponding to `last_agent_id`. Returns `null` when no Agent was assigned. Populated only for clients on the generative export path. | 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 | | | | | ✔ | ✔ |
| `used_articles` | A list of knowledge articles that were referenced during the conversation. Each entry includes the article `id`, `name`, `url`, and `source`. Returns an empty array when no articles were referenced. | Array | | | | | | ✔ |
| `used_coaching` | A list of Coaching events that were applied during the conversation. Each entry includes the coaching event `id`, `entity_name`, `coaching_type`, `coaching_instructions`, and `coaching_intent`. Returns an empty array when no Coaching was applied. | Array | | | | | | ✔ |
| `used_mcp` | A list of MCP tools that were invoked during the conversation. Each entry includes the invocation event `id`, `tool_id`, `connection_id`, `connection_name`, `tool_name`, and `outcome_status`. `tool_id` is `null` for invocations recorded before that field was captured. Returns an empty array when no MCP tools were invoked. | Array | | | | | | ✔ |
| `used_playbooks` | A list of Playbooks that were invoked during the conversation. Each entry includes the playbook `id`, `name`, `playbook_execution_id`, and `outcome_status`. Returns an empty array when no Playbooks were invoked. | Array | | | | | | ✔ |
| `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",
"changeset_id": "66f1a0c063a5bf2b1efb7c12",
"chatter_id": "6232257fb197d1ff65ea92fe",
"classifications": [
{
"topic_id": "654952d3e90767ff49713fb1",
"topic_name": "Billing",
"intents": [
{
"intent_id": "654952d3e90767ff49713fc2",
"intent_name": "Dispute a charge",
"status": "active"
}
]
}
],
"csat": {
"survey_type": "answer_flow",
"score": 5,
"style": "NUMERIC",
"is_positive": true,
"feedback": null,
"resolved": null,
"comment": null,
"customer_effort_score": 4,
"ces_max": 5,
"net_promoter_score": 8
},
"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",
"last_agent_id": "619d95c0c063a5bf2b1efb7c",
"last_agent_name": "Abby L",
"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,
"used_articles": [
{
"id": "6a4187126913c06e47dfb904",
"name": "How to cancel a reservation in Mews Operations",
"url": "https://help.mews.com/s/article/cancel-a-reservation",
"source": "Mews · Help Center"
}
],
"used_coaching": [
{
"id": "6612a0b9d8f4a1f3e2b7c8d9",
"entity_name": null,
"coaching_type": "reply",
"coaching_instructions": "First clarify the product in question.",
"coaching_intent": "Inquiries about our return policy."
},
{
"id": "69fb88bec1ef54f7798777eb",
"entity_name": "Missing Gift card",
"coaching_type": "playbook",
"coaching_instructions": null,
"coaching_intent": "Inquiries about the status of a missing gift card order."
}
],
"used_playbooks": [
{
"id": "6a40534826c6f79b57fe1462",
"name": "Mews — Cancellation Intervention (#7421) v2",
"playbook_execution_id": "2c34f985-a3b8-4aee-b85a-b38fdf6925f5",
"outcome_status": "succeeded"
}
],
"used_mcp": [
{
"id": "6c1a2c3d4e5f60718293a4b5",
"tool_id": "6a4f0c2e9b7d13a5c8e60419",
"connection_id": "6a4e1b3d8c9f02a4b7d51628",
"connection_name": "Mews Reservations",
"tool_name": "get_reservation",
"outcome_status": "succeeded"
}
],
"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
- Conversations [Return conversations matching the parameters](https://docs.ada.cx/data-export-conversation-object/get-conversations.md)
## OpenAPI Specification
The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.ada.cx/data-export-conversation-object/openapi.json)
- [OpenAPI YAML](https://docs.ada.cx/data-export-conversation-object/openapi.yaml)