Message object

A message object is created any time either Ada or a chatter sends a message. All messages are associated with a conversation by a conversation_id.

Attributes

AttributeDescriptionTypev1.0v1.1v1.2-1.3v1.4
_idThe unique ID of the message.String✔✔✔✔
answer_idInternal ID of the Answer that triggered the message (for example 627d28a9bd9ca9e5337b9763). Null if the message was not sent by an Ada bot.String✔✔
answer_titleThe title of the answer in the builder interface.String✔✔✔✔
chatter_idA reference to the chatter object to which the message belongs.String✔✔✔
conversation_idA reference to the conversation object to which the message belongs.String✔✔✔✔
date_createdThe timestamp indicating when the message was originally created.UTC Timestamp✔✔✔✔
in_response_toThe message ID of the message that this message was in response to.String✔
link_was_clickedIndicates whether the chatter clicked a link in an Answer. Values are true or false.Boolean✔✔
message_dataAn object containing the message content. The message text is in the body property of the object.JSON Dictionary✔✔✔✔
recipientThe recipient of the message. A unique ID if it is a chatter, otherwise “agent” or “bot”.String✔✔✔✔
record_last_updatedThe timestamp indicating when the record was uploaded to the API.UTC Timestamp✔
reviewIndicates whether the answer was given a thumbs up or thumbs down.Integer✔✔✔✔
senderThe sender of the message. A unique ID if it is a chatter, otherwise “agent” or “bot”.String✔✔✔✔

Message data examples

Below are some examples of the message_data returned in a message object.

Greeting

JSON
1"message_data": {
2  "_type": "greeting",
3  "external_chat_id": "<uuid_v4_id>",
4  "reviewable_message": false
5}

Text

JSON
1"message_data": {
2  "_type": "text",
3  "body": "Hi there 👋 Nice to meet you! I’m Ada the chatbot 🤖",
4  "has_variables": false,
5  "reviewable_message": false
6}

Picture

JSON
1"message_data": {
2  "_type": "picture",
3  "alt_text": "Picture of a Ada art waving \"hello\"",
4  "has_variables": false,
5  "pic_url": "https://static.ada.support/images/4d096cfc-2518-4811-8443-e8c063262082.gif",
6  "reviewable_message": false
7}

Quick Reply

JSON
1"message_data": {
2  "_type": "quick_replies",
3  "has_variables": false,
4  "is_forced": false,
5  "quick_replies": [
6      {
7          "button_type": "suggestion",
8          "label": "Pricing",
9          "target": "<mongodb_12_byte_object_id>"
10      },
11      {
12          "button_type": "suggestion",
13          "label": "Calculate your savings",
14          "target": "<mongodb_12_byte_object_id>"
15      },
16      {
17          "button_type": "suggestion",
18          "label": "Request a Demo",
19          "target": "<mongodb_12_byte_object_id>"
20      },
21      {
22          "button_type": "suggestion",
23          "label": "How can Ada help me? ",
24          "target": "<mongodb_12_byte_object_id>"
25      },
26      {
27          "button_type": "suggestion",
28          "label": "How does Ada work with support teams?",
29          "target": "<mongodb_12_byte_object_id>"
30      },
31      {
32          "button_type": "suggestion",
33          "label": "Download our Forrester Report",
34          "target": "<mongodb_12_byte_object_id>"
35      }
36  ],
37  "reviewable_message": false
38}

Trigger

JSON
1"message_data": {
2  "_type": "trigger",
3  "body": "Ask something else",
4  "button_type": "suggestion",
5  "external_chat_id": "<uuid_v4_id>",
6  "reviewable_message": false
7}

Meta

JSON
1"message_data": {
2  "_type": "meta",
3  "meta_message_data": {
4      "id": "<mongodb_12_byte_object_id>",
5      "name": "last_answer_id",
6      "new_value": "<mongodb_12_byte_object_id>",
7      "old_value": "<mongodb_12_byte_object_id>",
8      "scope": "meta"
9  },
10  "meta_message_type": "variable_change"
11}
JSON
1"message_data": {
2  "_type": "link",
3  "alt_text": "This is a link",
4  "generate_link_preview": true,
5  "has_variables": false,
6  "is_handoff": false,
7  "link_description": "",
8  "link_icon": "",
9  "link_text": "",
10  "new_window": true,
11  "raw_url": "https://www.example.com/",
12  "reviewable_message": false,
13  "title": "",
14  "url": "https://www.example.com"
15}

Web Window

JSON
1"message_data": {
2  "_type": "web_window",
3  "has_forced_quick_replies": true,
4  "has_variables": false,
5  "is_handoff": false,
6  "locked": false,
7  "raw_url": "https://www.example.com",
8  "reviewable_message": true,
9  "window_button_label": "Open me",
10  "window_height": 568,
11  "window_title": "Webwindow",
12  "window_url": "https://www.example.com",
13  "window_width": 320
14}

CSAT Prompt

JSON
1"message_data": {
2  "_type": "csat_shown",
3  "survey_type": "proactive"
4}

CSAT Result

JSON
1"message_data": {
2  "_type": "csat",
3  "is_positive": true,
4  "score": 5,
5  "style": "NUMERIC",
6  "survey_type": "proactive"
7}

Responses

Below are some examples of the data returned in message objects.

Get all messages created within 1 week of created_since (v1.2)

{
    "data": [
        {
            "_id": "623225807973ea81fb74577f",
            "answer_id": "6216a263c0c9f28ed7a16c1d",
            "answer_title": "Ada Interact > Welcome Message",
            "chatter_id": "6232257fb197d1ff65ea92fe",
            "conversation_id": "62322580b151ff975f1eb495",
            "date_created": "2022-03-16T17:59:28.356000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "picture",
                "alt_text": "",
                "has_variables": false,
                "pic_url": "https://static.ada.support/images/a76040d4-f431-4956-8984-b7fc3c6a635b.svg",
                "reviewable_message": false
            },
            "recipient": "6232257fb197d1ff65ea92fe",
            "review": 0,
            "sender": "ada"
        },
        {
            "_id": "623225807973ea81fb745780",
            "answer_id": "6216a263c0c9f28ed7a16c1d",
            "answer_title": "Ada Interact > Welcome Message",
            "chatter_id": "6232257fb197d1ff65ea92fe",
            "conversation_id": "62322580b151ff975f1eb495",
            "date_created": "2022-03-16T17:59:28.393000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "text",
                "body": "👋 Welcome to Ada Interact! ",
                "has_variables": false,
                "reviewable_message": false
            },
            "recipient": "6232257fb197d1ff65ea92fe",
            "review": 0,
            "sender": "ada"
        },
        {
            "_id": "623225807973ea81fb745781",
            "answer_id": "6216a263c0c9f28ed7a16c1d",
            "answer_title": "Ada Interact > Welcome Message",
            "chatter_id": "6232257fb197d1ff65ea92fe",
            "conversation_id": "62322580b151ff975f1eb495",
            "date_created": "2022-03-16T17:59:28.426000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "text",
                "body": "If you're curious about any of the reports that Mike mentions, click \"Read the reports\" or just type in 'get the reports'. ",
                "has_forced_quick_replies": false,
                "has_variables": false,
                "reviewable_message": false
            },
            "recipient": "6232257fb197d1ff65ea92fe",
            "review": 0,
            "sender": "ada"
        },
        {
            "_id": "623225807973ea81fb745782",
            "answer_id": "6216a263c0c9f28ed7a16c1d",
            "answer_title": "Ada Interact > Welcome Message",
            "chatter_id": "6232257fb197d1ff65ea92fe",
            "conversation_id": "62322580b151ff975f1eb495",
            "date_created": "2022-03-16T17:59:28.455000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "quick_replies",
                "has_variables": false,
                "is_forced": false,
                "quick_replies": [
                    {
                        "button_type": "suggestion",
                        "label": "Read the reports ",
                        "target": "6220f0840fffbae023fa47f0"
                    },
                    {
                        "button_type": "suggestion",
                        "label": "Get a demo of our newest features",
                        "target": "62312ec34abadc6df54df263"
                    },
                    {
                        "button_type": "suggestion",
                        "label": "Need a little pick me up?",
                        "target": "6226319838a50cf76ce74553"
                    },
                    {
                        "button_type": "suggestion",
                        "label": "Having issues with the stream?",
                        "target": "60c8d235b4499cfc9ca3e070"
                    }
                ],
                "reviewable_message": false
            },
            "recipient": "6232257fb197d1ff65ea92fe",
            "review": 0,
            "sender": "ada"
        },
        {
            "_id": "623225807973ea81fb745783",
            "answer_id": "None",
            "answer_title": null,
            "chatter_id": "6232257fb197d1ff65ea92fe",
            "conversation_id": "62322580b151ff975f1eb495",
            "date_created": "2022-03-16T17:59:28.521000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "meta",
                "meta_message_data": {
                    "id": "5faeb1a00aeb31f72a40bc36",
                    "name": "last_answer_id",
                    "new_value": "6216a263c0c9f28ed7a16c1d",
                    "old_value": null,
                    "scope": "meta"
                },
                "meta_message_type": "variable_change"
            },
            "recipient": "4ab42775-e590-47be-91a4-5cc99e8ae1e0",
            "review": 0,
            "sender": "bot"
        },
        {
            "_id": "623225818120de06333dcb43",
            "answer_id": "None",
            "answer_title": null,
            "chatter_id": "62322579d812c2074257c201",
            "conversation_id": "6232257ab6b44fc68056b82a",
            "date_created": "2022-03-16T17:59:29.305000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "greeting",
                "external_chat_id": "09897a21-99af-4714-92b7-10990accdc93",
                "reviewable_message": false
            },
            "recipient": "ada",
            "review": 0,
            "sender": "c6e01111-3e69-42d6-9553-97bc69024e90"
        },
        {
            "_id": "623225818120de06333dcb44",
            "answer_id": "6216a263c0c9f28ed7a16c1d",
            "answer_title": "Ada Interact > Welcome Message",
            "chatter_id": "62322579d812c2074257c201",
            "conversation_id": "6232257ab6b44fc68056b82a",
            "date_created": "2022-03-16T17:59:29.453000+00:00",
            "link_was_clicked": false,
            "message_data": {
                "_type": "picture",
                "alt_text": "",
                "has_variables": false,
                "pic_url": "https://static.ada.support/images/a76040d4-f431-4956-8984-b7fc3c6a635b.svg",
                "reviewable_message": false
            },
            "recipient": "62322579d812c2074257c201",
            "review": 0,
            "sender": "ada"
       }
    ],
    "message": "OK",
    "next_page_uri": "/data_api/v1.2/messages?created_since=2022-03-16T18%3A00%3A05.940000&created_to=2022-03-23T17%3A59%3A28.201000&page_size=100"
}

Get all messages created within 1 week of created_since (v1.1)

GET /data_api/v1.1/messages?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      "answer_title": null,
6      "conversation_id": "<mongodb_12_byte_object_id>",
7      "chatter_id": "<mongodb_12_byte_object_id>",
8      "date_created": "2020-09-21T04:30:22.268000+00:00",
9      "message_data": {
10        "_type": "greeting",
11        "external_chat_id": "<uuid_v4_id>",
12        "reviewable_message": false
13      },
14      "recipient": "ada",
15      "review": 0,
16      "sender": "<uuid_v4_id>"
17    },
18    {
19      "_id": "<mongodb_12_byte_object_id>",
20      "answer_title": null,
21      "conversation_id": "<mongodb_12_byte_object_id>",
22      "chatter_id": "<mongodb_12_byte_object_id>",
23      "date_created": "2020-09-21T04:30:23.256000+00:00",
24      "message_data": {
25        "_type": "meta",
26        "meta_message_data": {
27          "id": "<mongodb_12_byte_object_id>",
28          "name": "browser",
29          "new_value": "chrome",
30          "old_value": null,
31          "scope": "meta"
32        },
33        "meta_message_type": "variable_change"
34      },
35      "recipient": "<uuid_v4_id>",
36      "review": 0,
37      "sender": "bot"
38    }
39  ],
40  "message": "OK",
41  "next_page_uri": "/data_api/v1.1/messages?created_since=2020-09-23T03%3A55%3A03.586000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
42}

Get all messages created within 1 week of created_since (v1)

GET /data_api/v1/messages?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      "answer_title": null,
6      "conversation_id": "<mongodb_12_byte_object_id>",
7      "date_created": "2020-09-21T04:30:22.268000+00:00",
8      "message_data": {
9        "_type": "greeting",
10        "external_chat_id": "<uuid_v4_id>",
11        "reviewable_message": false
12      },
13      "recipient": "ada",
14      "review": 0,
15      "sender": "<uuid_v4_id>"
16    },
17    {
18      "_id": "<mongodb_12_byte_object_id>",
19      "answer_title": null,
20      "conversation_id": "<mongodb_12_byte_object_id>",
21      "date_created": "2020-09-21T04:30:23.256000+00:00",
22      "message_data": {
23        "_type": "meta",
24        "meta_message_data": {
25          "id": "<mongodb_12_byte_object_id>",
26          "name": "browser",
27          "new_value": "chrome",
28          "old_value": null,
29          "scope": "meta"
30        },
31        "meta_message_type": "variable_change"
32      },
33      "recipient": "<uuid_v4_id>",
34      "review": 0,
35      "sender": "bot"
36    }
37  ],
38  "message": "OK",
39  "next_page_uri": "/data_api/v1/messages?created_since=2020-09-23T03%3A55%3A03.586000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
40}