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

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

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
}

JSON

"message_data": {
  "_type": "sms_consent_asked"
}

CSAT Prompt

The sms_text field is only included when the survey is sent via SMS.

JSON

"message_data": {
  "_type": "csat_shown",
  "survey_type": "end_chat",
  "sms_text": "Take a survey: https://app.ada.support/..."
}

CSAT Result

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

"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

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

Message object

Attributes

Message data examples

Greeting

Text

Picture

Quick Reply

Trigger

Meta

variable_change

generative_reply

event

kb_article_click

business_event

engagement

trigger_campaign

ab_test

action_integration_action_invoke

proactive_conversation_opened

Link

Web Window

CSAT Prompt

CSAT Result

Tool selection

Naming conventions for `tool_name`

Examples

Handoff

Action

Responses

Get all messages created within 1 week of `created_since` (v2)

Attributes

Message data examples

Greeting

Text

Picture

Quick Reply

Trigger

Meta

variable_change

generative_reply

event

kb_article_click

business_event

engagement

trigger_campaign

ab_test

action_integration_action_invoke

proactive_conversation_opened

Link

Web Window

SMS Consent

CSAT Prompt

CSAT Result

Tool selection

Naming conventions for tool_name

Examples

Handoff

Action

Responses

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

Naming conventions for `tool_name`

Get all messages created within 1 week of `created_since` (v2)