Mensagem com botões

Pré-requisitos

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

Você esteja inscrito no programa beta - Acesse aqui para se inscrever.
A opção “Mensagens com botões” esteja ativa - Vá em Recursos em beta e ative o recurso.

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.

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.

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

Botão de Resposta (reply)

Permite que o usuário responda com um texto pré-definido.

{
  "label": "Sim, quero!",
  "type": "reply"
}

Botão de Ligação (call)

Inicia uma chamada para um número de telefone específico.

{
  "label": "Ligar Agora",
  "type": "call",
  "phone_number": "+5511999999999"
}

Botão de URL (url)

Abre um link no navegador do usuário.

{
  "label": "Ver Produto",
  "type": "url",
  "url": "https://exemplo.com/produto"
}

Botão Copiável (copyable)

Permite que o usuário copie um texto específico.

{
  "label": "Copiar Código",
  "type": "copyable",
  "copy_code": "PROMO2024"
}

Suporte por tipo de conexão

O suporte a botões varia conforme o tipo de conexão da instância. Em instâncias oficiais (WABA), os botões são enviados como mensagens interativas da Cloud API, que seguem regras próprias da Meta. A assinatura da requisição é a mesma nos dois tipos de conexão.

A coluna “Oficial (WABA)” abaixo descreve mensagens de sessão: mensagens interativas enviadas dentro da janela de conversa de 24 horas. Templates têm registro e aprovação separados na Meta e seguem regras próprias. Botões de ligação e de copiar código existem em templates, mesmo sem suporte em mensagem de sessão.

Recurso	Não oficial (QR code)	Oficial (WABA)
Botões `reply`	Até 3	Até 3
Botão `url`	Sim	Sim, exatamente 1 por mensagem
Botão `call`	Sim	Não em mensagem de sessão. Use um template com botão de ligação (`PHONE_NUMBER`)
Botão `copyable`	Sim	Não em mensagem de sessão. Disponível via template de Marketing ou Authentication
Misturar `url` com `reply`	Sim	Não
Mais de 1 botão `url`	Sim	Não
Mídia junto com botões	Sim	Sim. Imagem, vídeo ou documento viram o cabeçalho da mensagem interativa. Áudio não é suportado
`caption` da mídia	Vira a legenda da mídia	Vira o corpo da mensagem interativa, com prioridade sobre `text` quando os dois são enviados. Só `text` também vira o corpo

Em instâncias WABA, combinações não suportadas retornam erro 400 imediato com os códigos waba_feature_not_supported ou waba_invalid_button_combination. Nenhum campo é descartado silenciosamente. Veja exemplos completos de envio em Enviar mensagens com WABA e entenda a cobrança de mensagens no WhatsApp oficial (WABA).

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

object[]

Array de botões. Máximo 3 botões permitidos.

string

Modo de exibição dos botões. Valores aceitos: auto ou interactive.

Estrutura de um Botão

string

obrigatório

Texto do botão. Máximo 20 caracteres.

string

Tipo do botão. Valores aceitos: reply, call, url, copyable.

string

ID único do botão. Máximo 256 caracteres.

string

Número para botão de ligação. Deve estar no formato internacional.

string

URL para botão de link. Deve ser uma URL válida.

string

Texto para copiar. Aceita qualquer texto.

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"
  }'

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"
  }'

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"
  }'

Introdução

Conceitos

Webhooks

Integrações

Guias

Número 555 da Meta

Pré-requisitos

Visão Geral

Tipos de Botões

Suporte por tipo de conexão

Modos de Botões

Modo Padrão (`auto`)

Modo Interativo (`interactive`)

Como o Modo é Escolhido Automaticamente

Parâmetros dos Botões

Estrutura de um Botão

​Pré-requisitos

​Visão Geral

​Tipos de Botões

​Suporte por tipo de conexão

​Modos de Botões

​Modo Padrão (auto)

​Modo Interativo (interactive)

​Como o Modo é Escolhido Automaticamente

​Parâmetros dos Botões

​Estrutura de um Botão

Pré-requisitos

Visão Geral

Tipos de Botões

Suporte por tipo de conexão

Modos de Botões

Modo Padrão (`auto`)

Modo Interativo (`interactive`)

Como o Modo é Escolhido Automaticamente

Parâmetros dos Botões

Estrutura de um Botão