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 |
---|---|---|---|---|---|---|
_id | The unique ID of the conversation. | 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 | ✔ | ✔ | ||
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 | ✔ | ✔ | ||
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 ).Valueschat 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 ).Valuesapple chat http 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 voice web | String | ✔ | ✔ | ✔ | ✔ |
variables | The unique variable values for the conversation. The maximum length is 1000 characters. | JSON Dictionary | ✔ | ✔ | ✔ | ✔ |
automated_resolution _classification | Classification of either Resolved or Not Resolved for the conversation. Example: Resolved | ✔ | ||||
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. | ✔ | ||||
inquiry_summary | Automatically generated summary of the customer's inquiry. Example: The customer wanted to know how to temporarily disable auto deposits. | ✔ |
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)
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)
created_since
(v1.1)GET /data_api/v1.1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100
{
"data": [
{
"_id": "<mongodb_12_byte_object_id>",
"chatter_id": "<mongodb_12_byte_object_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": "<mongodb_12_byte_object_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)
created_since
(v1)GET /data_api/v1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100
{
"data": [
{
"_id": "<mongodb_12_byte_object_id>",
"chatter_id": "<mongodb_12_byte_object_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": "<mongodb_12_byte_object_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"
}