Message object
This page is for version Generative (default).
For other versions, use one of these documentation indexes:
- Generative (default): https://developers.ada.cx/generative/llms.txt
- Scripted: https://developers.ada.cx/scripted/llms.txt
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
JSON
"message_data": {"_type": "greeting","external_chat_id": "<uuid_v4_id>","reviewable_message": false}
Text
JSON
"message_data": {"_type": "text","body": "Hi there 👋 Nice to meet you! I’m Ada the chatbot 🤖","has_variables": false,"reviewable_message": false}
Picture
JSON
"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
JSON
"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
JSON
"message_data": {"_type": "trigger","body": "Ask something else","button_type": "suggestion","external_chat_id": "<uuid_v4_id>","reviewable_message": false}
Meta
variable_change
JSON
"message_data": {"_type": "meta","meta_message_data": {"id": "5f8a7d080afd19b55945c8ab","name": "last_answer_id","new_value": "62322580b151ff975f1eb495","old_value": "619d95c0c063a5bf2b1efb7c","scope": "meta"},"meta_message_type": "variable_change"}
generative_reply
JSON
"message_data": {"_type": "meta","meta_message_type": "generative_reply","meta_message_data": {"article_ids": ["6232257fb197d1ff65ea92fe", "60cb3ef9b72ebfacb39408da"],"status": "success"}}
event
JSON
"message_data": {"_type": "meta","meta_message_type": "event","meta_message_data": {"event_type": "handoff","event_subtype": "handoff_requested","event_data": {"triggered_by": "5dbaef7283d791f585563d84"},"response_id": "6216a263c0c9f28ed7a16c1d"}}
kb_article_click
JSON
"message_data": {"_type": "meta","meta_message_type": "kb_article_click","meta_message_data": {"article_id": "622bacf18d48fea09fe32fc8","message_id": "5d8a7d080afd19b55945c8ab"}}
business_event
JSON
"message_data": {"_type": "meta","meta_message_type": "business_event","meta_message_data": {"event_key": "ada:message_received:campaign_key","meta": {"campaign_key": "welcome_campaign"},"value": 0.0,"response_id": "654952d3e90767ff49713fbf"}}
engagement
JSON
"message_data": {"_type": "meta","meta_message_type": "engagement","meta_message_data": {}}
trigger_campaign
JSON
"message_data": {"_type": "meta","meta_message_type": "trigger_campaign","meta_message_data": {"campaign_key": "welcome_campaign"}}
ab_test
JSON
"message_data": {"_type": "meta","meta_message_type": "ab_test","meta_message_data": {"meta": {"ab_test_variable_id": "654952d3e90767ff49713fb2"},"response_id": "619d95c0c063a5bf2b1efb64"}}
action_integration_action_invoke
JSON
"message_data": {"_type": "meta","meta_message_type": "action_integration_action_invoke","meta_message_data": {"integration": "zendesk","action_id": "create_ticket"}}
proactive_conversation_opened
JSON
"message_data": {"_type": "meta","meta_message_type": "proactive_conversation_opened","meta_message_data": {"proactive_conversation_key": "welcome_campaign","proactive_conversation_id": "60cb3ef9b72ebfacb39408da"}}
Link
JSON
"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
JSON
"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
JSON
"message_data": {"_type": "csat_shown","survey_type": "proactive"}
CSAT Result
JSON
"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 (v2)
{"data": [{"_id": "623225807973ea81fb74577f","answer_id": "6216a263c0c9f28ed7a16c1d","answer_title": "Ada Interact > Welcome Message","chatter_id": "6232257fb197d1ff65ea92fe","conversation_id": "62322580b151ff975f1eb495","date_created": "2024-03-16T17:59:28.356000+00:00","in_response_to": null,"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","record_last_updated": "2024-07-31T13:56:44.423229+00:00","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","record_last_updated": "2024-07-31T13:56:44.423229+00:00","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","record_last_updated": "2024-07-31T13:56:44.423229+00:00","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","record_last_updated": "2024-07-31T13:56:44.423229+00:00","review": 0,"sender": "ada"}],"meta": {"next_page_uri": "https://<bot-handle>.ada.support/api/v2/export/messages?created_since=2024-03-15T14%3A01%3A01.563000%2B00%3A00&created_to=2024-09-22T00%3A00%3A00%2B00%3A00&page_size=100"}}