Messages with buttons

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "Would you like to receive our exclusive offers?",
    "buttons": [
      {
        "label": "Yes, please!",
        "type": "reply"
      },
      {
        "label": "No, thanks",
        "type": "reply"
      }
    ],
    "buttons_mode": "interactive"
  }'

curl -X POST https://api.zapsterapi.com/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "How can I help you today?",
    "buttons": [
      {
        "label": "Talk to an agent",
        "type": "call",
        "phone_number": "+5511888888888"
      },
      {
        "label": "View catalog",
        "type": "url",
        "url": "https://mystore.com/catalog"
      },
      {
        "label": "Copy coupon",
        "type": "copyable",
        "copy_code": "DISCOUNT10"
      }
    ],
    "buttons_mode": "auto"
  }'

curl -X POST https://api.zapsterapi.com/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "Check out our new product!",
    "media": {
      "url": "https://example.com/image.jpg",
      "caption": "Amazing product with a special discount"
    },
    "buttons": [
      {
        "label": "Buy now",
        "type": "url",
        "url": "https://mystore.com/buy"
      },
      {
        "label": "See details",
        "type": "url",
        "url": "https://mystore.com/details"
      }
    ],
    "buttons_mode": "interactive"
  }'

Prerequisites

To use message buttons, you need:

To be enrolled in the beta program - Sign up here.
The “Messages with buttons” option to be enabled - Go to Beta features and turn the feature on.

The buttons feature is available only to users enrolled in the beta program. If you do not have access, get in touch with our support team.

NOTE: Currently, sending all three button types at once makes WhatsApp Web throw an error, which also happens when using Meta’s own API. One alternative is to send only the CALL, URL, and COPYABLE buttons together, and always send the REPLY button separately.

Overview

Buttons let you create interactive messages on WhatsApp, offering users quick reply options. You can add up to 3 buttons per message, each with a different action type.

Button types

Reply button (reply)

Lets the user reply with a predefined text.

{
  "label": "Yes, I want it!",
  "type": "reply"
}

Call button (call)

Starts a call to a specific phone number.

{
  "label": "Call now",
  "type": "call",
  "phone_number": "+5511999999999"
}

URL button (url)

Opens a link in the user’s browser.

{
  "label": "View product",
  "type": "url",
  "url": "https://example.com/product"
}

Copyable button (copyable)

Lets the user copy a specific text.

{
  "label": "Copy code",
  "type": "copyable",
  "copy_code": "PROMO2024"
}

Support by connection type

Button support varies with the instance’s connection type. On official (WABA) instances, buttons are sent as Cloud API interactive messages, which follow Meta’s own rules. The request signature is the same for both connection types.

The “Official (WABA)” column below describes session messages: interactive messages sent within the 24-hour conversation window. Templates have separate registration and approval with Meta and follow their own rules. Call and copy-code buttons exist in templates, even though they are not supported in session messages.

Feature	Unofficial (QR code)	Official (WABA)
`reply` buttons	Up to 3	Up to 3
`url` button	Yes	Yes, exactly 1 per message
`call` button	Yes	Not in a session message. Use a template with a call button (`PHONE_NUMBER`)
`copyable` button	Yes	Not in a session message. Available through a Marketing or Authentication template
Mixing `url` with `reply`	Yes	No
More than 1 `url` button	Yes	No
Media together with buttons	Yes	Yes. An image, video, or document becomes the header of the interactive message. Audio is not supported
Media `caption`	Becomes the media caption	Becomes the interactive message body, taking priority over `text` when both are sent. `text` alone also becomes the body

On WABA instances, unsupported combinations return an immediate 400 error with the codes waba_feature_not_supported or waba_invalid_button_combination. No field is silently dropped. See full send examples in Sending WhatsApp messages with WABA and understand the WhatsApp official (WABA) message pricing.

Button modes

Button modes (buttons_mode) define how your message is sent on WhatsApp. There are two available modes:

Default mode (`auto`)

Used for simple quick reply buttons
Ideal when you just want text replies from the user
WhatsApp shows the buttons in a basic way

Interactive mode (`interactive`)

Used for more advanced buttons like calls, links, and copyable text
Enables a richer experience with different action types
WhatsApp shows the buttons with more visual prominence

How the mode is chosen automatically

If you do not specify buttons_mode, the system chooses automatically:

Interactive mode: used when at least one button is of type call, url, or copyable
Default mode: used when all buttons are of type reply

Important tip: even with all buttons being reply, you can force interactive mode by setting "buttons_mode": "interactive" for a better visual presentation.

Button parameters

object[]

Array of buttons. Maximum of 3 buttons allowed.

string

Button display mode. Accepted values: auto or interactive.

Structure of a button

string

required

Button text. Maximum of 20 characters.

string

Button type. Accepted values: reply, call, url, copyable.

string

Unique button ID. Maximum of 256 characters.

string

Number for the call button. Must be in international format.

string

URL for the link button. Must be a valid URL.

string

Text to copy. Accepts any text.

curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "Would you like to receive our exclusive offers?",
    "buttons": [
      {
        "label": "Yes, please!",
        "type": "reply"
      },
      {
        "label": "No, thanks",
        "type": "reply"
      }
    ],
    "buttons_mode": "interactive"
  }'

curl -X POST https://api.zapsterapi.com/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "How can I help you today?",
    "buttons": [
      {
        "label": "Talk to an agent",
        "type": "call",
        "phone_number": "+5511888888888"
      },
      {
        "label": "View catalog",
        "type": "url",
        "url": "https://mystore.com/catalog"
      },
      {
        "label": "Copy coupon",
        "type": "copyable",
        "copy_code": "DISCOUNT10"
      }
    ],
    "buttons_mode": "auto"
  }'

curl -X POST https://api.zapsterapi.com/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Instance-ID: YOUR_INSTANCE_ID" \
  -d '{
    "recipient": "5511999999999",
    "text": "Check out our new product!",
    "media": {
      "url": "https://example.com/image.jpg",
      "caption": "Amazing product with a special discount"
    },
    "buttons": [
      {
        "label": "Buy now",
        "type": "url",
        "url": "https://mystore.com/buy"
      },
      {
        "label": "See details",
        "type": "url",
        "url": "https://mystore.com/details"
      }
    ],
    "buttons_mode": "interactive"
  }'

Number health: best practices and restrictions How to schedule your first message

Introduction

Concepts

Guides

Messages with buttons

Prerequisites

Overview

Button types

Support by connection type

Button modes

Default mode (`auto`)

Interactive mode (`interactive`)

How the mode is chosen automatically

Button parameters

Structure of a button

​Prerequisites

​Overview

​Button types

​Support by connection type

​Button modes

​Default mode (auto)

​Interactive mode (interactive)

​How the mode is chosen automatically

​Button parameters

​Structure of a button

Prerequisites

Overview

Button types

Support by connection type

Button modes

Default mode (`auto`)

Interactive mode (`interactive`)

How the mode is chosen automatically

Button parameters

Structure of a button