> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/data-export-message-object/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Message object A `message` object is created whenever either Ada (an AI Agent or scripted bot) 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, or `Ada` if the recipient is an AI Agent or scripted 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, or `Ada` if the recipient is an AI Agent or scripted bot. | String | ✔ | ✔ | ✔ | ✔ | ## Message data examples Below are some examples of the `message_data` returned in a message object. ### Greeting **`JSON`** ```json JSON "message_data": { "_type": "greeting", "external_chat_id": "", "reviewable_message": false } ``` ### Text **`JSON`** ```json 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`** ```json 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`** ```json JSON "message_data": { "_type": "quick_replies", "has_variables": false, "is_forced": false, "quick_replies": [ { "button_type": "suggestion", "label": "Pricing", "target": "" }, { "button_type": "suggestion", "label": "Calculate your savings", "target": "" }, { "button_type": "suggestion", "label": "Request a Demo", "target": "" }, { "button_type": "suggestion", "label": "How can Ada help me? ", "target": "" }, { "button_type": "suggestion", "label": "How does Ada work with support teams?", "target": "" }, { "button_type": "suggestion", "label": "Download our Forrester Report", "target": "" } ], "reviewable_message": false } ``` ### Trigger **`JSON`** ```json JSON "message_data": { "_type": "trigger", "body": "Ask something else", "button_type": "suggestion", "external_chat_id": "", "reviewable_message": false } ``` ### Meta #### variable\_change **`JSON`** ```json 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`** ```json JSON "message_data": { "_type": "meta", "meta_message_type": "generative_reply", "meta_message_data": { "article_ids": ["6232257fb197d1ff65ea92fe", "60cb3ef9b72ebfacb39408da"], "status": "success" } } ``` #### event **`JSON`** ```json 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`** ```json JSON "message_data": { "_type": "meta", "meta_message_type": "kb_article_click", "meta_message_data": { "article_id": "622bacf18d48fea09fe32fc8", "message_id": "5d8a7d080afd19b55945c8ab" } } ``` #### business\_event **`JSON`** ```json 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`** ```json JSON "message_data": { "_type": "meta", "meta_message_type": "engagement", "meta_message_data": {} } ``` #### trigger\_campaign **`JSON`** ```json JSON "message_data": { "_type": "meta", "meta_message_type": "trigger_campaign", "meta_message_data": { "campaign_key": "welcome_campaign" } } ``` #### ab\_test **`JSON`** ```json 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`** ```json 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`** ```json 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`** ```json 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`** ```json 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 } ``` ### SMS Consent **`JSON`** ```json JSON "message_data": { "_type": "sms_consent_asked" } ``` ### CSAT Prompt The `sms_text` field is only included when the survey is sent via SMS. **`JSON`** ```json JSON "message_data": { "_type": "csat_shown", "survey_type": "end_chat", "sms_text": "Take a survey: https://app.ada.support/..." } ``` ### CSAT Result **`JSON`** ```json JSON "message_data": { "_type": "csat", "is_positive": true, "score": 5, "style": "NUMERIC", "survey_type": "proactive" } ``` ### Tool selection When an AI Agent selects a tool during a conversation, a separate message is created with `_type: "tool_call"`. Tools currently include configured Handoffs and Actions. The `tool_name` field identifies which tool was selected, and `arguments` and `result` capture the inputs and outputs. Common fields on every tool selection message: | Field | Description | Type | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `_type` | Always `tool_call`. | String | | `tool_name` | Identifies the tool that was selected. A sanitized name derived from the configured Handoff or Action on the AI Agent. | String | | `tool_call_id` | Unique identifier for this tool selection. | String | | `arguments` | The inputs the AI Agent provided to the tool. The shape depends on `tool_name`. May be omitted or empty for tools that take no parameters. | Object | | `result` | The outcome of the tool. Includes `status` (`succeeded`, `failed`, or `processing`), `error_message`, and `return_values`. The shape of `return_values` depends on `tool_name`. | Object | | `timestamp` | Unix timestamp (seconds) when the tool selection was logged. | Number | #### Naming conventions for `tool_name` For Handoffs and Actions configured on the AI Agent, the `tool_name` is the entity's name lowercased, with spaces replaced by underscores, non-alphanumeric characters stripped, and truncated to 64 characters. For example, a Handoff named `Billing Support` produces a `tool_name` of `billing_support`. #### Examples #### Handoff The AI Agent selected a Handoff during the conversation. `return_values` contains the Handoff's `id` and `name`. In this example, the Handoff is named `Billing Support`. **`JSON`** ```json JSON "message_data": { "_type": "tool_call", "reviewable_message": false, "has_variables": false, "tool_name": "billing_support", "tool_call_id": "69f0881860712c866dc4d772", "result": { "status": "succeeded", "error_message": null, "return_values": { "id": "69f0881860712c866dc4d772", "name": "billing_support" } }, "timestamp": 1777371160.413301 } ``` #### Action The AI Agent invoked an Action during the conversation. `arguments` contains the input parameters the AI Agent generated for the Action. `result.return_values` contains the parsed response body and `result.status_code` is the HTTP status code. In this example, the Action is named `Get Order Status`. **`JSON`** ```json JSON "message_data": { "_type": "tool_call", "reviewable_message": false, "has_variables": false, "tool_name": "get_order_status", "tool_call_id": "69f077583280e2e5a851ec86", "arguments": { "order_id": "ORD-48291" }, "result": { "status": "succeeded", "error_message": null, "return_values": { "status": "shipped", "tracking_number": "1Z999AA10123456784", "estimated_delivery": "2026-05-12" }, "status_code": 200 }, "timestamp": 1777366872.74277 } ``` ## 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://.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" } } ``` ## API Docs - Messages [Return messages matching the parameters](https://docs.ada.cx/data-export-message-object/get-messages.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.ada.cx/data-export-message-object/openapi.json) - [OpenAPI YAML](https://docs.ada.cx/data-export-message-object/openapi.yaml)