> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/conversations/conversation-message-webhook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Webhook: Conversation message

POST 

A webhook sent when a message is sent to a conversation

Reference: https://docs.ada.cx/reference/conversations/conversation-message-webhook

## Request

### Payload

- `type` (enum, optional) — The webhook event type
  - Allowed values: `v1.conversation.message`
- `timestamp` (string, optional) — The timestamp for when the event was generated, uses millisecond precision to help with event ordering needs
- `data` (ConversationMessageWebhookPayloadData, optional) — The webhook event data

## Types

### ConversationMessageWebhookPayloadData

The webhook event data

- `message_id` (string, optional) — The ID of the message that triggered the webhook event
- `conversation_id` (string, optional) — The ID of the conversation that contains the message
- `end_user_id` (string, optional) — The ID of the end user associated with the conversation
- `handoff_integration` (string, optional, nullable) — The name of the handoff integration if the message is part of a handoff conversation. This field is null when the message is directed to the AI Agent.
- `channel` (ConversationMessageWebhookChannel, optional) — The channel that the message was sent on
- `created_at` (string, optional) — The date and time the message was created
- `author` (ConversationMessageWebhookPayloadDataAuthor, optional) — Information about the message author
- `content` (ConversationMessageWebhookPayloadDataContent, optional)
- `ai_agent_domain` (string, optional) — The API domain of the AI Agent environment this webhook event is emitted from

### ConversationMessageWebhookChannel

- `type`: `native` (native)
  - `description` (string, required) — A description of the channel
  - `id` (string, required) — The channel ID
  - `modality` (enum, required) — The modality of the channel
    - Allowed values: `messaging`, `email`, `voice`, `sms`
  - `name` (string, required) — The name of the channel
  - `capabilities` (BaseChannelCapabilities, optional) — What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface.
- `type`: `custom` (custom)
  - `description` (string, required) — A description of the channel
  - `id` (string, required) — The channel ID
  - `modality` (enum, required) — The modality of the channel
    - Allowed values: `messaging`, `email`, `voice`, `sms`
  - `name` (string, required) — The name of the channel
  - `capabilities` (BaseChannelCapabilities, optional) — What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface.
  - `created_at` (string, optional) — The date and time the channel was created
  - `metadata` (map from string to ConversationMessageWebhookCustomChannelMetadata, optional) — A dictionary of key/value pairs assigned to the channel. Metadata may not exceed 4KB total - keys: string - values: string, boolean, or integer

### ConversationMessageWebhookPayloadDataAuthor

Information about the message author

- `id` (string, optional, nullable) — The ID of the user that will be participating in the conversation
- `role` (enum, optional) — The author's role
  - Allowed values: `end_user`, `ai_agent`, `human_agent`
- `avatar` (string, optional, nullable) — The URL of the author's avatar
- `display_name` (string, optional, nullable) — The author's display name

### ConversationMessageWebhookPayloadDataContent

### BaseChannelCapabilities

What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface.

- `markdown` (boolean, optional, default: false) — Preserve Markdown (bold, italic, and links) in replies instead of flattening to plain text.
- `quick_replies` (boolean, optional, default: false) — Deliver the tappable options of a Playbook Ask step as a `quick_replies` message instead of listing them in the reply's text. Applies to conversations created after the capability is set. Only a channel with the `messaging` modality can set it; the request is rejected on other modalities. Custom channels only: native channels always report false because Ada manages their message rendering.

### ConversationMessageWebhookCustomChannelMetadata

### TextContent

The content of the text message

- `type` (enum, required) — The type of the message
  - Allowed values: `text`
- `body` (string, required) — The body of the message

### LinkContent

The content of a standalone link style messages, such as CSAT

- `type` (enum, optional) — The type of the message
  - Allowed values: `link`
- `url` (string, optional) — The link's URL
- `link_text` (string, optional, nullable) — Text that can be used to display the link

### FileContent

The content of a file message

- `type` (enum, required) — The type of the message
  - Allowed values: `file`
- `url` (string, required) — Presigned URL from the attachment upload endpoint (valid for 7 days)
- `mime_type` (string, required) — MIME type of the file
- `filename` (string, required) — Name of the file

### QuickRepliesContent

The accepted values of a Playbook Ask step with quick replies enabled, as tappable options for the AI Agent message that asked the question. Delivered only on channels whose `capabilities.quick_replies` is true; other channels receive the options as text in the reply body. Render each option's `label` under the message named by `question_message_id`; the two arrive as separate messages and may arrive in either order. When the end user taps an option, post its `value` as a `text` message from the end user; the AI Agent resolves it to the option even when the label was translated. Free text remains accepted, so keep the composer available.

- `type` (enum, required) — The type of the message
  - Allowed values: `quick_replies`
- `question_message_id` (string, required, nullable) — The `message_id` of the AI Agent message whose question these options answer. Null only for a message written before the reference was recorded.
- `options` (list of QuickRepliesContentOptionsItems, required) — The options, in the order the AI Agent presents them

### QuickRepliesContentOptionsItems

- `label` (string, required) — The text to show on the option, translated into the end user's language
- `value` (string, required) — The text to send back as the end user's message when the option is tapped