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.

Attributes

AttributeDescriptionTypev1.0v1.1v1.2v1.3v1.4v2
_idThe unique ID of the conversation.String✔✔✔✔✔✔
agent_handle_timeThe amount of time it took for a human agent to resolve the conversation, in seconds.String✔✔
agent_idThe list of unique IDs for agents involved in the conversation (for example, 619d95c0c063a5bf2b1efb7c).Array✔✔✔✔
agent_nameA 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_timeThe amount of time it took for the bot to resolve the conversation, in seconds.String✔✔
browserThe type of browser the chatter was using (for example, chrome).String✔✔✔✔
browser_versionThe specific version number of the chatter’s browser.String✔✔✔✔
chatter_idThe unique chatter ID.String✔✔✔✔✔✔
csatThe CSAT score for the conversation. Note that only CSAT 2.0 data is available in the conversations endpoint.JSON Dictionary✔✔✔✔✔✔
date_createdThe timestamp indicating when the conversation was created.UTC Timestamp✔✔✔✔✔✔
date_updatedThe timestamp indicating when the conversation was last updated.UTC Timestamp✔✔✔✔✔✔
deviceThe device type or operating system (for example, macos).String✔✔✔✔
end_user_idThe End User ID used to identify the chatter profile in the conversation (for example, 619d95c0c063a5bf2b1efb64e).String✔✔
generated_topic_idThe 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_labelThe 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_descThe 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_idThe 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_idThe 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_titleThe 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_summaryAutomatically generated summary of the customer’s inquiry (for example, The customer wanted to know how to temporarily disable auto deposits).String✔✔✔
is_engagedIndicates whether the chatter sent at least one message to start the conversation after Ada served a greeting.Boolean✔✔✔✔✔✔
is_escalatedIndicates if the chatter was handed off to an integrated CX platform, an email ticket, or escalated to an agent.Boolean✔✔✔✔✔✔
is_test_userWhether or not the conversation involved a test user (indicated by true or false).Boolean✔✔✔✔
languageThe language of the conversation, represented by a language code in ISO 639-1 format (for example, fr).String✔✔✔✔
metavariablesThe metavariables stored by Ada.JSON Dictionary✔✔✔✔✔✔
oauth_channelIf 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✔✔✔✔
platformThe 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_updatedThe timestamp indicating when the record was uploaded to the API.UTC Timestamp✔✔
variablesThe 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 (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": {
                "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."
            }
        }
    ],
    "meta": {
        "next_page_uri": "https://<bot-handle>.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"
    }
}