Buttons and lists (beta)

Beta. Interactive messages rely on WhatsApp behaviour that is not an official contract. WhatsApp can change how they are delivered or rendered at any time, without notice. Read the caveats before you build a flow that depends on them.

WSAPI can send two kinds of interactive message:

Buttons — POST /messages/buttons. A message with 1 to 3 buttons under the text. Use them for short, closed choices: confirm or cancel an appointment, yes or no, or a link, a code to copy or a number to call.
Lists — POST /messages/list. A message with one button that opens a list of up to 10 options, grouped into sections. Use it when there are more than three options, or when each option needs a short description: time slots, menu items, departments.

When the recipient taps a reply button or picks a row, you receive a message event with what they chose. See Button and list replies.

Send buttons

Reply buttons send the choice back to you. Give each one an id — it is what you receive in the event, so make it something your code can route on.

curl -X POST https://api.wsapi.chat/messages/buttons \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID" \
  -d '{
    "to": "1234567890@s.whatsapp.net",
    "text": "Can we confirm your appointment for tomorrow at 10:00?",
    "footer": "Reply with a button",
    "buttons": [
      { "id": "confirm", "text": "Confirm" },
      { "id": "reschedule", "text": "Reschedule" },
      { "id": "cancel", "text": "Cancel" }
    ]
  }'

const response = await fetch("https://api.wsapi.chat/messages/buttons", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY",
    "X-Instance-Id": "YOUR_INSTANCE_ID",
  },
  body: JSON.stringify({
    to: "1234567890@s.whatsapp.net",
    text: "Can we confirm your appointment for tomorrow at 10:00?",
    footer: "Reply with a button",
    buttons: [
      { id: "confirm", text: "Confirm" },
      { id: "reschedule", text: "Reschedule" },
      { id: "cancel", text: "Cancel" },
    ],
  }),
});
const { id } = await response.json();
// Store id next to the appointment: the reply event carries it as replyTo.id

The response is 201 Created with the ID of the message:

{ "id": "3EB07C7B838E3240C9E150" }

Keep that ID. The reply event carries it as replyTo.id, which is how you tell which message — and so which appointment, order or ticket — the recipient answered.

Link, copy and call buttons

Buttons of different types can be mixed in one message. These three act on the recipient’s device and send nothing back:

{
  "to": "1234567890@s.whatsapp.net",
  "header": "Your order has shipped",
  "text": "Order #1042 is on its way. Track it, copy your coupon for next time, or call us.",
  "footer": "Example Store",
  "buttons": [
    { "type": "url", "text": "Track order", "url": "https://example.com/track/1042" },
    { "type": "copy", "text": "Copy coupon", "copyCode": "THANKS10" },
    { "type": "call", "text": "Call us", "phoneNumber": "+1234567890" }
  ]
}

Button types

`type`	Required fields	What the tap does	Event
`reply` (default)	`id`, `text`	Sends the choice back to you as a reply to the message	`message` with `type: "button_reply"`
`url`	`text`, `url`	Opens `url` in the recipient’s browser	None
`copy`	`text`, `copyCode`	Copies `copyCode` to the recipient’s clipboard	None
`call`	`text`, `phoneNumber`	Starts a call to `phoneNumber` from the recipient’s phone	None

type can be omitted for reply buttons.

Send a list

A list shows one button (buttonText) under the message. Tapping it opens the options, grouped into titled sections. The recipient picks one.

curl -X POST https://api.wsapi.chat/messages/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID" \
  -d '{
    "to": "1234567890@s.whatsapp.net",
    "header": "Book a table",
    "text": "Pick a time slot for your reservation.",
    "footer": "Example Bistro",
    "buttonText": "See times",
    "sections": [
      {
        "title": "Lunch",
        "rows": [
          { "id": "slot-1200", "title": "12:00", "description": "Terrace available" },
          { "id": "slot-1330", "title": "13:30" }
        ]
      },
      {
        "title": "Dinner",
        "rows": [
          { "id": "slot-1900", "title": "19:00" },
          { "id": "slot-2030", "title": "20:30", "description": "Indoor seating only" }
        ]
      }
    ]
  }'

const response = await fetch("https://api.wsapi.chat/messages/list", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY",
    "X-Instance-Id": "YOUR_INSTANCE_ID",
  },
  body: JSON.stringify({
    to: "1234567890@s.whatsapp.net",
    header: "Book a table",
    text: "Pick a time slot for your reservation.",
    footer: "Example Bistro",
    buttonText: "See times",
    sections: [
      {
        title: "Lunch",
        rows: [
          { id: "slot-1200", title: "12:00", description: "Terrace available" },
          { id: "slot-1330", title: "13:30" },
        ],
      },
      {
        title: "Dinner",
        rows: [
          { id: "slot-1900", title: "19:00" },
          { id: "slot-2030", title: "20:30", description: "Indoor seating only" },
        ],
      },
    ],
  }),
});
const { id } = await response.json();

A list with a single section does not need a section title.

The AI label

Set aiLabel: true on either endpoint to show WhatsApp’s AI badge on the message — useful when the message comes from an assistant or bot and you want to say so.

{
  "to": "1234567890@s.whatsapp.net",
  "text": "I can help with your booking. What would you like to do?",
  "aiLabel": true,
  "buttons": [
    { "id": "book", "text": "New booking" },
    { "id": "change", "text": "Change booking" }
  ]
}

The badge only applies to 1:1 chats. In a group, aiLabel is ignored and the message is sent without it.

Limits

The limits follow the ones WhatsApp publishes for its Cloud API. Both endpoints

Field	Limit
`text`	Required, up to 1024 characters
`header`	Optional, up to 60 characters, text only
`footer`	Optional, up to 60 characters, text only

Buttons

Field	Limit
`buttons`	1 to 3 buttons
`buttons[].text`	Required, up to 20 characters
`buttons[].id`	Required on `reply` buttons, unique within the message, up to 256 characters
`buttons[].url`	Required on `url` buttons; must be an `http://` or `https://` URL
`buttons[].copyCode`	Required on `copy` buttons, up to 256 characters
`buttons[].phoneNumber`	Required on `call` buttons; an international number, e.g. `+1234567890`

Lists

Field	Limit
`buttonText`	Required, up to 20 characters
`sections`	1 to 10 sections
Rows	At least 1 per section, at most 10 in total across all sections
`sections[].title`	Up to 24 characters; required on every section when there is more than one
`rows[].id`	Required, up to 200 characters, unique across the whole list
`rows[].title`	Required, up to 24 characters
`rows[].description`	Optional, up to 72 characters

A request that breaks a limit is rejected with 400 Bad Request and a message naming the field, and nothing is sent:

{
  "status": 400,
  "detail": "validation error: buttons[1].id \"confirm\" is duplicated"
}

Handling the reply

A reply arrives as a message event with type: "button_reply" or type: "list_reply". Route on the id you set on the button or row, and use replyTo.id — the ID returned by the send call — to find the message it answers. Only reply buttons and list rows produce events.

Button and list replies

Payloads, correlation, and what to watch for in your handler

Caveats

This is a beta feature. Interactive messages rely on WhatsApp behaviour that is not an official contract and can change without notice. Keep a fallback in your flow: for example, accept a typed “confirm” as well as the button.
201 means WhatsApp accepted the message, not that it was rendered. WhatsApp accepts the message even when the recipient’s app does not display the buttons or the list, and there is no signal back when that happens.
Where they render:
- Buttons render on phones and on WhatsApp Web.
- Lists currently render on phones only. WhatsApp Web shows “open your phone to view this message” instead.
The AI label applies to 1:1 chats only, and is ignored in groups.
Header and footer are text only. Images, videos and documents in the header are not supported.
The common send options are not available. These endpoints do not take mentions, replyTo, isForwarded or ephemeralExpiration.

Overview

Reference

Endpoints

Buttons and lists (beta)

Send buttons

Link, copy and call buttons

Button types

Send a list

The AI label

Limits

Handling the reply

Button and list replies

Caveats

​Send buttons

​Link, copy and call buttons

​Button types

​Send a list

​The AI label

​Limits

​Handling the reply

Button and list replies

​Caveats

Send buttons

Link, copy and call buttons

Button types

Send a list

The AI label

Limits

Handling the reply

Caveats