> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages with buttons

> How to send WhatsApp interactive buttons (reply, call, url, copyable) with the Zapster API, plus the support matrix for unofficial (QR code) and official (WABA) instances.

## Prerequisites

To use message buttons, you need:

1. **To be enrolled in the beta program** - [Sign up here](https://app.zapsterapi.com/settings/beta-program).
2. **The "Messages with buttons" option to be enabled** - Go to [Beta features](https://app.zapsterapi.com/settings/beta-features) and turn the feature on.

<Warning>
  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.
</Warning>

<Warning>
  **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.
</Warning>

## 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

<AccordionGroup>
  <Accordion title="Reply button (reply)">
    Lets the user reply with a predefined text.

    ```json theme={null}
    {
      "label": "Yes, I want it!",
      "type": "reply"
    }
    ```
  </Accordion>

  <Accordion title="Call button (call)">
    Starts a call to a specific phone number.

    ```json theme={null}
    {
      "label": "Call now",
      "type": "call",
      "phone_number": "+5511999999999"
    }
    ```
  </Accordion>

  <Accordion title="URL button (url)">
    Opens a link in the user's browser.

    ```json theme={null}
    {
      "label": "View product",
      "type": "url",
      "url": "https://example.com/product"
    }
    ```
  </Accordion>

  <Accordion title="Copyable button (copyable)">
    Lets the user copy a specific text.

    ```json theme={null}
    {
      "label": "Copy code",
      "type": "copyable",
      "copy_code": "PROMO2024"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  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.
</Note>

| 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 |

<Info>
  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](/en/v1/guides/send-waba-messages) and understand the [WhatsApp official (WABA) message pricing](/en/v1/concepts/message-pricing).
</Info>

## 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

<ParamField body="buttons" type="object[]">
  Array of buttons. Maximum of 3 buttons allowed.
</ParamField>

<ParamField body="buttons_mode" type="string">
  Button display mode. Accepted values: `auto` or `interactive`.
</ParamField>

### Structure of a button

<ParamField body="label" type="string" required>
  Button text. Maximum of 20 characters.
</ParamField>

<ParamField body="type" type="string">
  Button type. Accepted values: `reply`, `call`, `url`, `copyable`.
</ParamField>

<ParamField body="id" type="string">
  Unique button ID. Maximum of 256 characters.
</ParamField>

<ParamField body="phone_number" type="string">
  Number for the call button. Must be in international format.
</ParamField>

<ParamField body="url" type="string">
  URL for the link button. Must be a valid URL.
</ParamField>

<ParamField body="copy_code" type="string">
  Text to copy. Accepts any text.
</ParamField>

<RequestExample>
  ```bash Simple reply buttons theme={null}
  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"
    }'
  ```

  ```bash Buttons with different types theme={null}
  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"
    }'
  ```

  ```bash Buttons with media theme={null}
  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"
    }'
  ```
</RequestExample>