Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Enviar e receber

Como enviar botões de resposta e de ação pela API de WhatsApp?

Envie botões de resposta, link, copiar código e ligar com POST /messages/interactive. Provado em aparelho real. Lista e carrossel não funcionam hoje.

7 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Use POST /messages/interactive com to, body e uma lista de buttons (de 1 a 10) dos tipos reply (resposta), url (link), copy (copiar código) e call (ligar). Esses quatro foram provados em aparelho real em 12/11/2026. Lista de opções (menu) e carrossel não funcionam hoje: o WhatsApp mostra "mensagem incompatível", e a API recusa o pedido com 422 interactive_unsupported. O botão de localização ainda não foi provado.

Beta, com prova parcial. O envio dos botões de resposta e de ação foi provado em aparelho real em 12/11/2026 (veja versões). O que ainda não foi provado: o botão de localização, e o aviso que chega quando alguém toca num botão. A rota segue marcada como em beta no catálogo.

Este guia mostra como montar cada botão, os limites de tamanho, o que a API devolve e como receber a escolha. Para texto simples, veja os primeiros passos; para enquetes, o guia de mensagens e ações.

Como envio dois botões de resposta?

Envie buttons com dois itens reply, cada um com id (o que o seu sistema recebe de volta) e text (o que a pessoa lê).

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/interactive" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{
    "to": "5547999999999",
    "body": "Seu pedido 4512 chega amanhã. Confirma o endereço?",
    "footer": "Atendimento da loja",
    "buttons": [
      { "type": "reply", "id": "sim", "text": "Confirmo" },
      { "type": "reply", "id": "nao", "text": "Quero mudar" }
    ]
  }'

A resposta traz o id da mensagem e um aviso:

json
{
  "ok": true,
  "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
  "to": "5547999999999",
  "status": "sent",
  "data": { "rendered": null },
  "warning": "O WhatsApp pode aceitar a mensagem e não mostrar os botões."
}

rendered vem sempre nulo: a API não sabe, depois do envio, se o botão foi desenhado. O aviso fica por prudência, porque o WhatsApp muda o que aceita sem aviso. Nos testes de 12/11/2026, os botões de resposta e de ação apareceram no celular.

Quais tipos de botão funcionam?

type Campos O que faz Situação
reply id*, text* Resposta rápida: o toque volta no aviso Provado em 12/11/2026
url text*, url* (https) Abre um endereço no navegador Provado em 12/11/2026
copy text*, code* Copia um código (por exemplo, de cupom) Provado em 12/11/2026
call text*, phone* Abre a ligação para o telefone Provado em 12/11/2026
location nenhum Pede a localização da pessoa; só pode ser o único botão Não provado
list title*, sections* Lista de opções (menu) Não funciona; recusado

Limites conferidos pela API: texto do botão até 25 caracteres, id até 100, body até 1.024 e footer até 60; de 1 a 10 botões. Passou disso, a API responde 422 invalid_request com a lista de fields.

E a lista de opções e o carrossel?

Não funcionam hoje. Nos testes em aparelho real de 12/11/2026, o WhatsApp exibiu "mensagem incompatível" para os dois formatos. Por isso a API recusa o pedido antes de enviar, com:

json
{
  "ok": false,
  "error": "interactive_unsupported",
  "message": "Lista e carrossel ainda não funcionam: o WhatsApp mostra \"mensagem incompatível\". Use botões (resposta, link, copiar ou ligar).",
  "fields": ["buttons"]
}

HTTP 422. Isso vale também nas rotas de compatibilidade: sendList da Evolution e send-option-list e send-carousel da Z-API recusam do mesmo jeito. Se o seu fluxo precisa de um menu, use até 10 botões de resposta, ou escreva as opções numeradas no texto e aceite "1", "2" e "3" como resposta (o bot trata os dois jeitos). Quando o WhatsApp passar a aceitar o formato, esta página e o histórico de versões dirão a data.

Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.

Testar grátis

Misture os tipos na mesma mensagem:

json
{
  "to": "5547999999999",
  "body": "Seu boleto está pronto.",
  "buttons": [
    { "type": "url", "text": "Abrir boleto", "url": "https://exemplo.com.br/boleto/4512" },
    { "type": "copy", "text": "Copiar código", "code": "34191.79001 01043.510047 91020.150008 8 99990000010000" },
    { "type": "call", "text": "Falar conosco", "phone": "5547999999999" }
  ]
}

Use endereços https públicos no botão de link. Os botões de ação executam a ação no celular da pessoa (abrir o link, copiar o código, abrir a ligação); não conte com um aviso ao seu sistema quando eles são tocados. Só o botão de resposta (reply) foi desenhado para devolver a escolha.

Como recebo a escolha da pessoa?

Pelo aviso automático. Quando a pessoa toca num botão de resposta, deve chegar um message.received com type igual a button_reply e data.selected com o id e o text escolhidos:

json
{
  "event": "message.received",
  "uid": "in_3EB0F1",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-12T10:00:02-03:00",
  "occurred_at": "2026-11-12T13:00:01Z",
  "data": { "id": "3EB0F1", "from": "5547999999999", "name": "Maria", "type": "button_reply", "text": "Confirmo", "selected": { "id": "sim", "text": "Confirmo" }, "reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C" }
}

Programe pelo selected.id, que é seu, e não pelo texto. O aviso de toque recebido ainda não foi provado em aparelho (os avisos de mensagens de fora ainda estão em beta); por isso trate selected e text como opcionais e aceite também a resposta por texto. No formato Z-API do aviso, a mesma resposta vira buttonsResponseMessage.

Em Node e em Python

js
const r = await fetch("https://proxybox.com.br/api/whatsapp/v1/messages/interactive", {
  method: "POST",
  headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    to: "5547999999999",
    body: "Confirma a entrega amanhã?",
    buttons: [{ type: "reply", id: "sim", text: "Sim" }, { type: "reply", id: "nao", text: "Não" }],
  }),
});
console.log(r.status, await r.json());
python
import os, requests

r = requests.post(
    "https://proxybox.com.br/api/whatsapp/v1/messages/interactive",
    headers={"apikey": os.environ["WA_KEY"]},
    json={"to": "5547999999999", "body": "Confirma a entrega amanhã?",
          "buttons": [{"type": "reply", "id": "sim", "text": "Sim"},
                      {"type": "reply", "id": "nao", "text": "Não"}]},
    timeout=30,
)
print(r.status_code, r.json())

Com Python, prefira requests (ou defina um User-Agent próprio): o agente padrão do urllib pode receber 403 do Cloudflare.

Quais erros e limites valem aqui?

  • 422 interactive_unsupported: lista ou carrossel. Nada é enviado.
  • 422 invalid_request: texto do botão acima de 25 caracteres, mais de 10 botões, schedule presente ou url fora de https.
  • 429 rate_limited e daily_limit: o envio de botões conta no mesmo ritmo do texto (padrão de 10 por minuto e 500 por dia).
  • 409 opted_out: o telefone está em não perturbe. Nada é enviado.
  • 409 new_contacts_locked: a trava de contato novo vale também para botões.
  • O campo reply_to é aceito, mas ainda não é enviado ao WhatsApp nesta versão.
  • Não existe botão de pagamento por PIX nem de código de uso único (OTP).

Na Evolution, sendButtons funciona (provado em 12/11/2026); na Z-API, send-button-actions e send-button-list viram esta rota. Veja migrar da Z-API e migrar da Evolution. A lista completa de erros está em erros e limites.

Quando vale a pena usar?

Quando você controla o que acontece depois do toque: confirmar uma entrega, abrir um link de pagamento, copiar um código de cupom. Escreva o body já com a pergunta e aceite também a resposta por texto ("sim", "1"). Para conversas longas, combine a rota com um bot.

Veja também

Índice completo: índice dos guias. Sobre o produto: API de WhatsApp para o seu sistema.

Autoria: equipe técnica da ProxyBox. Atualizado em 12/11/2026, contra o catálogo da versão 1.2 (operação send.interactive) e a prova em aparelho de 12/11/2026. Botões de resposta e de ação provados; lista, carrossel e localização não.

Perguntas frequentes

Posso enviar lista de opções (menu) ou carrossel?
Hoje não. O WhatsApp mostra "mensagem incompatível" e a API recusa o pedido com 422 interactive_unsupported. Use botões de resposta, link, copiar ou ligar.
Posso agendar uma mensagem com botões?
Não. Botões não aceitam o campo schedule; a API responde 422.
O que chega ao meu sistema quando a pessoa toca num botão?
Um aviso message.received com type button_reply e, em data.selected, o id e o texto escolhidos. O toque recebido foi provado em aparelho real em 14/11/2026: o aviso trouxe o id e o texto do botão tocado e o id da mensagem original em reply_to.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp