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ê).
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:
{
"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:
{
"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átisComo envio botões de ação (link, copiar e ligar)?
Misture os tipos na mesma mensagem:
{
"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:
{
"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
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());
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,schedulepresente ouurlfora de https.429 rate_limitededaily_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
- Reagir, editar, apagar e status: API de WhatsApp
- Webhook da API de WhatsApp: eventos e assinatura
- Bots de WhatsApp pela API: tipos e limites
- Aprovação humana de mensagens da API de WhatsApp
Í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.