Interactive Messages

Besides plain text, a chat agent can send a structured interactive message — buttons, a carousel, or a date picker — and wait for the customer to answer it before continuing. Interactive messages arrive the same way regular messages do (a reply on Send Message, a callback on the delivery webhook, or an event over the chat WebSocket), tagged type: "interaction".

Whether an agent offers interactive messages at all depends on its configuration. If your integration can’t render a given type, declare what you can render with supported_interactions on every inbound request — the agent only offers types your client has declared.

Declaring what you support

Send supported_interactions on content/message requests to tell the agent which interaction types your client can display:

"supported_interactions": [
  { "tool_type": "ui_buttons", "schema_version": 2 },
  { "tool_type": "ui_date_picker", "schema_version": 1 }
]

`tool_type`	Description
`ui_buttons`	A label plus a row of tappable options. Schema version `2` additionally supports one free-text option.
`ui_carousel`	A label plus a horizontally-scrollable list of items, each with a title and optional image.
`ui_date_picker`	A single date or a date range, constrained to an allowed window.

Omit supported_interactions (or send an empty array) on a plain text message — the agent then won’t offer any interactive type for that turn.

What the agent sends

An interactive message is a message with type: "interaction":

Field	Description
`interaction_id`	UUID identifying this interactive message. Use it to answer it.
`tool_type`	`ui_buttons`, `ui_carousel`, or `ui_date_picker`.
`schema_version`	Version of the type’s schema (see tables below).
`presentation`	The content to render — shape depends on `tool_type` (see below).
`interaction_status`	`pending` while waiting for an answer, `accepted` once answered, `cancelled` if superseded (e.g. the customer sent a plain message instead), `expired` if it timed out unanswered.

`ui_buttons` presentation

{
  "label": "Would you like to confirm this appointment?",
  "description": "You can also let me know if you'd like to reschedule.",
  "options": [
    { "id": "opt_confirm", "label": "Confirm" },
    { "id": "opt_other", "label": "Something else", "allow_input": true, "input_placeholder": "Tell me more..." }
  ]
}

description and each option’s description are optional. At most one option may have allow_input: true (schema version 2 only) — selecting it lets the customer type free text instead of a fixed answer.

`ui_carousel` presentation

{
  "label": "Here are a few options for you",
  "items": [
    {
      "id": "item_1",
      "title": "Deluxe Room",
      "description": "King bed, city view",
      "image": { "url": "https://cdn.example.com/deluxe.jpg", "alt": "Deluxe room" },
      "action_label": "Select"
    }
  ]
}

description, image, and action_label are optional per item.

`ui_date_picker` presentation

{
  "label": "Pick a date for your appointment",
  "selection_mode": "single",
  "min_date": "2026-06-10",
  "max_date": "2026-07-10"
}

selection_mode is single (answer with one date) or range (answer with a start and end date). min_date/max_date bound the selectable range and may be omitted.

Answering an interactive message

Send an inbound request (Send Message, Send Message Async, or a WebSocket message frame) with:

Field	Description
`type`	`"interaction_response"`.
`interaction_id`	The `interaction_id` from the message you’re answering.
`option_id`	Shorthand for a plain `ui_buttons` (schema version 1 only) tap — the `id` of the selected option. Use this or `response`, not both. For carousel, date picker, or `ui_buttons` schema version 2, use `response` instead.
`response`	`{ "kind": ..., "value": ... }` — see below. Required for every interaction type except a `ui_buttons` v1 tap, where `option_id` is a shorthand for the same thing.

response.kind depends on what you’re answering:

`kind`	`value`	When to use it
`selection`	The selected option/item `id` (string)	`ui_carousel` selections, and `ui_buttons` schema version 2 (the `option_id` shorthand only works for version 1).
`text`	Typed text (string)	Only when the presentation has an option with `allow_input: true` (`ui_buttons` v2).
`date`	An ISO date, e.g. `"2026-06-12"`	`ui_date_picker` with `selection_mode: "single"`.
`date_range`	`{ "start_date": "...", "end_date": "..." }`	`ui_date_picker` with `selection_mode: "range"`.

{
  "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
  "customer_id": "+15551112222",
  "type": "interaction_response",
  "interaction_id": "b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10",
  "response": { "kind": "date_range", "value": { "start_date": "2026-06-10", "end_date": "2026-06-14" } }
}

A response is validated against the exact message you’re answering — a selection id that isn’t among its options/items, or a date outside min_date/max_date, is rejected with a 422. Answering the same interaction twice with the same content (a retry, or a duplicate tap) returns the original answer instead of accepting a second one.

Get Started

Going Deeper

API Reference

Declaring what you support

What the agent sends

`ui_buttons` presentation

`ui_carousel` presentation

`ui_date_picker` presentation

Answering an interactive message

​Declaring what you support

​What the agent sends

​ui_buttons presentation

​ui_carousel presentation

​ui_date_picker presentation

​Answering an interactive message

Declaring what you support

What the agent sends

`ui_buttons` presentation

`ui_carousel` presentation

`ui_date_picker` presentation

Answering an interactive message