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

# Mensagem com botões

> Aprenda como enviar mensagens com botões interativos usando a API do ZapsterAPI

## Pré-requisitos

Para utilizar a funcionalidade de botões em mensagens, é necessário que:

1. **Você esteja inscrito no programa beta** - [Acesse aqui](https://app.zapsterapi.com/settings/beta-program) para se inscrever.
2. **A opção "Mensagens com botões" esteja ativa** - Vá em [Recursos em beta](https://app.zapsterapi.com/settings/beta-features) e ative o recurso.

<Warning>
  A funcionalidade de botões está disponível apenas para usuários inscritos no programa beta. Caso não tenha acesso, entre em contato com nossa equipe de suporte.
</Warning>

<Warning>
  **OBSERVAÇÃO:** Atualmente, ao enviar os três tipos de botões simultaneamente, o WhatsApp Web gera um erro, que também ocorre ao usar a própria API da Meta. Uma alternativa é enviar apenas os botões CALL, URL e COPYABLE juntos, e sempre enviar o botão REPLY separadamente.
</Warning>

## Visão Geral

Os botões permitem criar mensagens interativas no WhatsApp, oferecendo aos usuários opções de resposta rápida. Você pode adicionar até 3 botões por mensagem, cada um com diferentes tipos de ação.

## Tipos de Botões

<AccordionGroup>
  <Accordion title="Botão de Resposta (reply)">
    Permite que o usuário responda com um texto pré-definido.

    ```json theme={null}
    {
      "label": "Sim, quero!",
      "type": "reply"
    }
    ```
  </Accordion>

  <Accordion title="Botão de Ligação (call)">
    Inicia uma chamada para um número de telefone específico.

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

  <Accordion title="Botão de URL (url)">
    Abre um link no navegador do usuário.

    ```json theme={null}
    {
      "label": "Ver Produto",
      "type": "url",
      "url": "https://exemplo.com/produto"
    }
    ```
  </Accordion>

  <Accordion title="Botão Copiável (copyable)">
    Permite que o usuário copie um texto específico.

    ```json theme={null}
    {
      "label": "Copiar Código",
      "type": "copyable",
      "copy_code": "PROMO2024"
    }
    ```
  </Accordion>
</AccordionGroup>

## Modos de Botões

Os modos de botões (`buttons_mode`) definem como sua mensagem será enviada no WhatsApp. Existem dois modos disponíveis:

### Modo Padrão (`auto`)

* Usado para botões de resposta rápida simples
* Ideal quando você quer apenas receber respostas de texto do usuário
* O WhatsApp exibe os botões de forma básica

### Modo Interativo (`interactive`)

* Usado para botões mais avançados como ligações, links e textos copiáveis
* Permite uma experiência mais rica com diferentes tipos de ação
* O WhatsApp exibe os botões com mais destaque visual

### Como o Modo é Escolhido Automaticamente

Se você não especificar o `buttons_mode`, o sistema escolhe automaticamente:

* **Modo Interativo**: Será usado quando pelo menos um botão for do tipo `call`, `url` ou `copyable`
* **Modo Padrão**: Será usado quando todos os botões forem do tipo `reply`

**Dica importante**: Mesmo com todos os botões sendo `reply`, você pode forçar o modo interativo definindo `"buttons_mode": "interactive"` para ter uma apresentação visual melhor.

### Parâmetros dos Botões

<ParamField body="buttons" type="object[]">
  Array de botões. Máximo 3 botões permitidos.
</ParamField>

<ParamField body="buttons_mode" type="string">
  Modo de exibição dos botões. Valores aceitos: `auto` ou `interactive`.
</ParamField>

### Estrutura de um Botão

<ParamField body="label" type="string" required>
  Texto do botão. Máximo 20 caracteres.
</ParamField>

<ParamField body="type" type="string">
  Tipo do botão. Valores aceitos: `reply`, `call`, `url`, `copyable`.
</ParamField>

<ParamField body="id" type="string">
  ID único do botão. Máximo 256 caracteres.
</ParamField>

<ParamField body="phone_number" type="string">
  Número para botão de ligação. Deve estar no formato internacional.
</ParamField>

<ParamField body="url" type="string">
  URL para botão de link. Deve ser uma URL válida.
</ParamField>

<ParamField body="copy_code" type="string">
  Texto para copiar. Aceita qualquer texto.
</ParamField>

<RequestExample>
  ```bash Botões de Resposta Simples 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": "Gostaria de receber nossas ofertas exclusivas?",
      "buttons": [
        {
          "label": "Sim, quero!",
          "type": "reply"
        },
        {
          "label": "Não, obrigado",
          "type": "reply"
        }
      ],
      "buttons_mode": "interactive"
    }'
  ```

  ```bash Botões com Diferentes Tipos 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": "Como posso te ajudar hoje?",
      "buttons": [
        {
          "label": "Falar com Atendente",
          "type": "call",
          "phone_number": "+5511888888888"
        },
        {
          "label": "Ver Catálogo",
          "type": "url",
          "url": "https://minhaloja.com/catalogo"
        },
        {
          "label": "Copiar Cupom",
          "type": "copyable",
          "copy_code": "DESCONTO10"
        }
      ],
      "buttons_mode": "auto"
    }'
  ```

  ```bash Botões com 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": "Confira nosso novo produto!",
      "media": {
        "url": "https://exemplo.com/imagem.jpg",
        "caption": "Produto incrível com desconto especial"
      },
      "buttons": [
        {
          "label": "Comprar Agora",
          "type": "url",
          "url": "https://minhaloja.com/comprar"
        },
        {
          "label": "Ver Detalhes",
          "type": "url",
          "url": "https://minhaloja.com/detalhes"
        }
      ],
      "buttons_mode": "interactive"
    }'
  ```
</RequestExample>