Conversation object — Ada

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.

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<br />_classification`	Classification of either Resolved or Not Resolved for the conversation. Example: Resolved	String				✔	✔
`automated_resolution<br />_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 (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.

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

1 {
2   "data": [
3     {
4       "_id": "<mongodb_12_byte_object_id>",
5       "chatter_id": "<mongodb_12_byte_object_id>",
6       "csat": {
7         "comment": null,
8         "feedback": [
9           "(helpful_resolution)"
10         ],
11         "is_positive": true,
12         "resolved": true,
13         "score": 5,
14         "style": "EMOJI",
15         "survey_type": "end_chat"
16       },
17       "date_created": "2020-09-21T04:30:22.681000+00:00",
18       "date_updated": "2020-09-21T04:33:57.614000+00:00",
19       "is_engaged": true,
20       "is_escalated": false,
21       "metavariables": {
22         "browser": "chrome",
23         "browser_version": "85.0.4183.102",
24         "device": "macos",
25         "introshown": "False",
26         "language": "en",
27         "last_answer_id": "<mongodb_12_byte_object_id>",
28         "last_question_asked": "Ada",
29         "test_user": "1",
30         "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"
31       },
32       "platform": "chat",
33       "variables": {
34         "name": "Ada"
35       }
36     }
37   ],
38   "message": "OK",
39   "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"
40 }

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