App Directory

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.4
_idThe unique ID of the conversation.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 _classificationClassification of either Resolved or Not Resolved for the conversation.
Example: Resolved		✔✔
automated_resolution _classification_reasonExplanation 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.		✔✔
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).String✔
generated_topic_labelThe title of the generated conversation topic (for example, Billing Inquiries).String✔
inquiry_summaryAutomatically generated summary of the customer's inquiry.
Example: The customer wanted to know how to temporarily disable auto deposits.		✔✔
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
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
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✔✔✔✔✔
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 (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

{
  "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)

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"
}