Interactions

Buttons and forms send events to your webhook through the same signed pipeline as messages. Each event carries its own response_url, so you can reply or update the original message. The payloads are flat — action_id, value, and user sit at the top level. There is no wrapper object.

interaction.button_clicked

{
  "api_version": "2026-07-01",
  "block_kit_version": "1",
  "event": "interaction.button_clicked",
  "type": "interaction.button_clicked",
  "event_id": "evt_01JZYA7M3T",
  "chatbot_id": "c1d4",
  "conversation_id": "9f31",
  "message_id": "m_77ab",
  "block_id": "blk_x8f2",
  "action_id": "approve",
  "value": "req_991",
  "label": "Approve",
  "message_metadata": { "order_id": "4821" },
  "user": { "kind": "visitor", "id": "vs_8c2", "display_name": "Visitor 4821" },
  "clicked_at": "2026-07-17T03:12:44.120Z",
  "response_url": "https://app.my-aichatbot.com/api/v1/responses/eyJ2Ijox",
  "delivery_attempt": 1
}

action_id

string

The action_id from the button you made.

value

string

The button’s value, exactly as you sent it. An empty string if you set none.

label

string | null

The button text at the time of the click.

message_metadata

object

A word-for-word copy of the metadata you set on the message. An empty object if you set none.

user

object

Who clicked.

Show properties

kind

string

visitor (widget or public page) or member (someone in your workspace).

string

The visitor session or member id.

display_name

string

A friendly name, like Visitor 4821.

Link buttons (any button with a url) never send events. They just open a tab.

interaction.form_submitted

Same base fields, with the answers in values:

{
  "api_version": "2026-07-01",
  "block_kit_version": "1",
  "event": "interaction.form_submitted",
  "type": "interaction.form_submitted",
  "event_id": "evt_01JZYB2N8Q",
  "chatbot_id": "c1d4",
  "conversation_id": "9f31",
  "message_id": "m_55cd",
  "block_id": "blk_p2m9",
  "action_id": "callback",
  "form_id": "callback",
  "values": {
    "full_name": "Priya Sharma",
    "email": "priya@example.com",
    "team_size": 14,
    "topic": "other",
    "details": "",
    "consent": true
  },
  "message_metadata": { "flow": "callback_request" },
  "user": { "kind": "visitor", "id": "vs_8c2", "display_name": "Visitor 4821" },
  "submitted_at": "2026-07-17T03:15:02.551Z",
  "response_url": "https://app.my-aichatbot.com/api/v1/responses/eyJ2Ijox",
  "delivery_attempt": 1
}

form_id

string

The form’s form_id — the one you set, or the one we made if you left it out. It matches the event’s action_id.

How values are typed

Field type	Value type	When left empty
`text`, `email`, `textarea`	string	`""`
`number`	number	`null`
`select`	string (the option’s `value`)	`""`
`checkbox`	boolean	`false`

Every key is always there, even when empty. Your field mappings will not break on a missing path.

We check answers on our servers before sending them to you. If a check fails, the visitor sees the errors inline and you get nothing. So anything that reaches you already passed your required, min, max, and options rules.

Replying

Every event carries its own response_url. The natural move is to swap the form for a confirmation:

{ "text": "Thanks Priya! We'll call **+61 400 000 000** tomorrow morning." }

Or return it straight from the webhook. Both work the same.

Two fields that lie

delivery_attempt is always 1. It is written into the payload once and never changes on retry. For the real try number, read the X-MyAIChatbot-Attempt header.

Spot repeats with event_id — it is the same across retries. See Receiving events.

Button state

After we accept a click, the group turns off and the clicked button shows as chosen — unless you set disable_on_click: false. This state is saved on our side, so page reloads and other viewers all agree. Buttons show as turned off when:

The message is over 30 days old.
A human has taken over the conversation.
The conversation has passed its storage window.

Interactions do not turn on the typing dots by default.

Get started

Sending messages

Block Kit

Receiving events

No-code platforms

interaction.button_clicked

interaction.form_submitted

How values are typed

Replying

Two fields that lie

Button state

​interaction.button_clicked

​interaction.form_submitted

​How values are typed

​Replying

​Two fields that lie

​Button state

interaction.button_clicked

interaction.form_submitted

How values are typed

Replying

Two fields that lie

Button state