Sending

Buttons and lists

POST/v1/messages

Experimental, with real risks. Buttons and lists are not an official feature for regular WhatsApp accounts. Lists have been confirmed to break the WhatsApp app on the sending iPhone. Some phones (iOS especially) show a plain-text fallback instead, messages can be dropped silently, there is one unconfirmed report of a recipient's iOS app crashing after receiving them, and unusual messages can draw WhatsApp's anti-abuse checks. Test with a few recipients first, don't send them in bulk, prefer buttons over lists, and prefer polls over both when you can.

When a phone doesn't draw the buttons, the recipient sees a numbered list instead, so they can still reply with the number or the label:

Want to proceed?

1. Yes
2. No

Buttons

POST https://api.api-supp.com/v1/messages with type: "buttons" and 1 to 3 buttons.

Field	Type	Notes
`recipient`	string	Required
`message`	string	The text above the buttons
`buttons`	array	Required. 1–3 of `{id?, text}`; `id` defaults to `btn_<index>`
`footer`	string	Optional small grey text

json

{
  "recipient": "14155550132",
  "type": "buttons",
  "message": "Want to proceed?",
  "footer": "We won't spam",
  "buttons": [
    { "id": "yes", "text": "Yes" },
    { "id": "no", "text": "No" }
  ]
}

Lists

POST https://api.api-supp.com/v1/messages with type: "list".

Field	Type	Notes
`recipient`	string	Required
`message`	string	The text above the list
`sections`	array	Required. Each `{title?, rows: [{id?, title, description?, header?}]}`. Row titles are cut to 24 characters
`button_text`	string	Label of the button that opens the list. Default `"Choose"`
`footer`	string	Optional

json

{
  "recipient": "14155550132",
  "type": "list",
  "message": "Pick a plan",
  "button_text": "Open menu",
  "sections": [
    { "title": "Plans", "rows": [
      { "id": "basic", "title": "Basic", "description": "$10/mo" },
      { "id": "pro", "title": "Pro", "description": "$30/mo" }
    ]}
  ]
}

Response

json

{
  "ok": true,
  "recipient": "14155550132@s.whatsapp.net",
  "wa_message_id": "3EB0CB97F37F91F563B060",
  "interactive": {
    "type": "buttons",
    "fallback_text": "Want to proceed?\n{Yes | No}",
    "buttons": [{ "id": "yes", "text": "Yes" }, { "id": "no", "text": "No" }]
  }
}

Replies

When someone taps a button or a row, the reply arrives as a regular incoming message (by webhook or list messages) carrying the chosen id.

Errors

400 no buttons, more than 3 buttons, a button without text, or missing sections