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
Attribute | Description | Type | v1.0 | v1.1 | v1.2-1.3 | v1.4 |
---|---|---|---|---|---|---|
_id | The unique ID of the message. | String | ✔ | ✔ | ✔ | ✔ |
answer_id | Internal ID of the Answer that triggered the message (for example 627d28a9bd9ca9e5337b9763 ). Null if the message was not sent by an Ada bot. | String | ✔ | ✔ | ||
answer_title | The title of the answer in the builder interface. | String | ✔ | ✔ | ✔ | ✔ |
chatter_id | A reference to the chatter object to which the message belongs. | String | ✔ | ✔ | ✔ | |
conversation_id | A reference to the conversation object to which the message belongs. | String | ✔ | ✔ | ✔ | ✔ |
date_created | The timestamp indicating when the message was originally created. | UTC Timestamp | ✔ | ✔ | ✔ | ✔ |
in_response_to | The message ID of the message that this message was in response to. | String | ✔ | |||
link_was_clicked | Indicates whether the chatter clicked a link in an Answer. Values are true or false . | Boolean | ✔ | ✔ | ||
message_data | An object containing the message content. The message text is in the body property of the object. | JSON Dictionary | ✔ | ✔ | ✔ | ✔ |
recipient | The recipient of the message. A unique ID if it is a chatter, otherwise “agent” or “bot”. | String | ✔ | ✔ | ✔ | ✔ |
record_last_updated | The timestamp indicating when the record was uploaded to the API. | UTC Timestamp | ✔ | |||
review | Indicates whether the answer was given a thumbs up or thumbs down. | Integer | ✔ | ✔ | ✔ | ✔ |
sender | The 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
"message_data": {
"_type": "greeting",
"external_chat_id": "<uuid_v4_id>",
"reviewable_message": false
}
Text
"message_data": {
"_type": "text",
"body": "Hi there 👋 Nice to meet you! I’m Ada the chatbot 🤖",
"has_variables": false,
"reviewable_message": false
}
Picture
"message_data": {
"_type": "picture",
"alt_text": "Picture of a Ada art waving \"hello\"",
"has_variables": false,
"pic_url": "https://static.ada.support/images/4d096cfc-2518-4811-8443-e8c063262082.gif",
"reviewable_message": false
}
Quick Reply
"message_data": {
"_type": "quick_replies",
"has_variables": false,
"is_forced": false,
"quick_replies": [
{
"button_type": "suggestion",
"label": "Pricing",
"target": "<mongodb_12_byte_object_id>"
},
{
"button_type": "suggestion",
"label": "Calculate your savings",
"target": "<mongodb_12_byte_object_id>"
},
{
"button_type": "suggestion",
"label": "Request a Demo",
"target": "<mongodb_12_byte_object_id>"
},
{
"button_type": "suggestion",
"label": "How can Ada help me? ",
"target": "<mongodb_12_byte_object_id>"
},
{
"button_type": "suggestion",
"label": "How does Ada work with support teams?",
"target": "<mongodb_12_byte_object_id>"
},
{
"button_type": "suggestion",
"label": "Download our Forrester Report",
"target": "<mongodb_12_byte_object_id>"
}
],
"reviewable_message": false
}
Trigger
"message_data": {
"_type": "trigger",
"body": "Ask something else",
"button_type": "suggestion",
"external_chat_id": "<uuid_v4_id>",
"reviewable_message": false
}
Meta
"message_data": {
"_type": "meta",
"meta_message_data": {
"id": "<mongodb_12_byte_object_id>",
"name": "last_answer_id",
"new_value": "<mongodb_12_byte_object_id>",
"old_value": "<mongodb_12_byte_object_id>",
"scope": "meta"
},
"meta_message_type": "variable_change"
}
Link
"message_data": {
"_type": "link",
"alt_text": "This is a link",
"generate_link_preview": true,
"has_variables": false,
"is_handoff": false,
"link_description": "",
"link_icon": "",
"link_text": "",
"new_window": true,
"raw_url": "https://www.example.com/",
"reviewable_message": false,
"title": "",
"url": "https://www.example.com"
}
Web Window
"message_data": {
"_type": "web_window",
"has_forced_quick_replies": true,
"has_variables": false,
"is_handoff": false,
"locked": false,
"raw_url": "https://www.example.com",
"reviewable_message": true,
"window_button_label": "Open me",
"window_height": 568,
"window_title": "Webwindow",
"window_url": "https://www.example.com",
"window_width": 320
}
CSAT Prompt
"message_data": {
"_type": "csat_shown",
"survey_type": "proactive"
}
CSAT Result
"message_data": {
"_type": "csat",
"is_positive": true,
"score": 5,
"style": "NUMERIC",
"survey_type": "proactive"
}
Responses
Below are some examples of the data returned in message
objects.
Get all messages created within 1 week of created_since
(v1.2)
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)
created_since
(v1.1)GET /data_api/v1.1/messages?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100
{
"data": [
{
"_id": "<mongodb_12_byte_object_id>",
"answer_title": null,
"conversation_id": "<mongodb_12_byte_object_id>",
"chatter_id": "<mongodb_12_byte_object_id>",
"date_created": "2020-09-21T04:30:22.268000+00:00",
"message_data": {
"_type": "greeting",
"external_chat_id": "<uuid_v4_id>",
"reviewable_message": false
},
"recipient": "ada",
"review": 0,
"sender": "<uuid_v4_id>"
},
{
"_id": "<mongodb_12_byte_object_id>",
"answer_title": null,
"conversation_id": "<mongodb_12_byte_object_id>",
"chatter_id": "<mongodb_12_byte_object_id>",
"date_created": "2020-09-21T04:30:23.256000+00:00",
"message_data": {
"_type": "meta",
"meta_message_data": {
"id": "<mongodb_12_byte_object_id>",
"name": "browser",
"new_value": "chrome",
"old_value": null,
"scope": "meta"
},
"meta_message_type": "variable_change"
},
"recipient": "<uuid_v4_id>",
"review": 0,
"sender": "bot"
}
],
"message": "OK",
"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"
}
Get all messages created within 1 week of created_since
(v1)
created_since
(v1)GET /data_api/v1/messages?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100
{
"data": [
{
"_id": "<mongodb_12_byte_object_id>",
"answer_title": null,
"conversation_id": "<mongodb_12_byte_object_id>",
"date_created": "2020-09-21T04:30:22.268000+00:00",
"message_data": {
"_type": "greeting",
"external_chat_id": "<uuid_v4_id>",
"reviewable_message": false
},
"recipient": "ada",
"review": 0,
"sender": "<uuid_v4_id>"
},
{
"_id": "<mongodb_12_byte_object_id>",
"answer_title": null,
"conversation_id": "<mongodb_12_byte_object_id>",
"date_created": "2020-09-21T04:30:23.256000+00:00",
"message_data": {
"_type": "meta",
"meta_message_data": {
"id": "<mongodb_12_byte_object_id>",
"name": "browser",
"new_value": "chrome",
"old_value": null,
"scope": "meta"
},
"meta_message_type": "variable_change"
},
"recipient": "<uuid_v4_id>",
"review": 0,
"sender": "bot"
}
],
"message": "OK",
"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"
}