> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/data-export/data-export-v1-4/messages/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": "<uuid_v4_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": "<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`**

```json 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`**

```json JSON
"message_data": {
  "_type": "meta",
  "meta_message_data": {
      "id": "<mongodb_object_id>",
      "name": "last_answer_id",
      "new_value": "<mongodb_object_id>",
      "old_value": "<mongodb_object_id>",
      "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": ["<mongodb_object_id>", "<mongodb_object_id>"],
    "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": "<mongodb_object_id>"
    },
    "response_id": "<mongodb_object_id>"
  }
}
```

#### kb\_article\_click

**`JSON`**

```json JSON
"message_data": {
  "_type": "meta",
  "meta_message_type": "kb_article_click",
  "meta_message_data": {
    "article_id": "<mongodb_object_id>",
    "message_id": "<mongodb_object_id>"
  }
}
```

#### 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": "<mongodb_object_id>"
  }
}
```

#### 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": "<mongodb_object_id>"
    },
    "response_id": "<mongodb_object_id>"
  }
}
```

### 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
}
```

### CSAT Prompt

**`JSON`**

```json JSON
"message_data": {
  "_type": "csat_shown",
  "survey_type": "proactive"
}
```

### CSAT Result

**`JSON`**

```json 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` (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`**

```json JSON

{
  "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)

`GET
/data_api/v1/messages?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100`

**`JSON`**

```json JSON

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


## API Docs

- Messages [Return messages matching the parameters](https://docs.ada.cx/reference/data-export/data-export-v1-4/messages/return-messages-matching-the-parameters.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.ada.cx/reference/data-export/data-export-v1-4/messages/openapi.json)
- [OpenAPI YAML](https://docs.ada.cx/reference/data-export/data-export-v1-4/messages/openapi.yaml)