Botões e listas no WhatsApp pela API: situação e alternativas
Mensagens interativas com botões e listas estão em avaliação na apiwpp, sem data. Veja por que e como montar confirmações e menus de atendimento hoje.
Atualizado em
Botões de resposta rápida e listas de opções são o sonho de qualquer fluxo de atendimento: o cliente toca em "Confirmar" ou escolhe "Segunda via do boleto" numa lista, e o sistema recebe uma resposta exata, sem interpretar texto. Por isso, "a API tem botões?" é uma das primeiras perguntas de quem avalia uma API de WhatsApp.
A resposta honesta: a apiwpp não envia botões nem listas hoje, e ainda não há decisão sobre oferecê-los. Esta página explica o motivo e mostra como montar os mesmos fluxos com o que já funciona.
Por que botões e listas ainda não estão na API
A apiwpp conecta o número pelo protocolo do WhatsApp Web, como um aparelho conectado. Nesse protocolo, mensagens interativas não têm um formato estável para envio: a biblioteca usada pela apiwpp não oferece esse tipo de conteúdo, e a única forma de montá-lo é construir a mensagem à mão, no formato interno do WhatsApp.
O problema é o que acontece do outro lado. Se a mensagem aparece com os botões, sem os botões ou nem aparece depende do aparelho de quem recebe (Android, iPhone, WhatsApp Web, desktop), do tipo de conta e de mudanças que o WhatsApp faz sem aviso. Um recurso que funciona hoje num celular e some amanhã em outro não é algo que dá para vender com tranquilidade.
Por isso, o plano da apiwpp é testar antes de prometer: enviar cada tipo de mensagem interativa para aparelhos e contas diferentes e só então decidir. Se o resultado for positivo, o recurso entra no plano PRO, com a escolha do cliente chegando estruturada no webhook. Se não for, o PRO segue sem ele. Não há data, e esta página será atualizada quando houver uma decisão.
A alternativa hoje: menu numerado
Para confirmações e menus de atendimento, uma mensagem de texto com opções numeradas funciona em qualquer versão do WhatsApp, nos planos LITE e PRO. O cliente responde "1" ou "2", e a resposta chega no seu sistema pelo evento message.incoming.
Salve o menu como um template, com variáveis para personalizar:
{
"name": "menu_atendimento",
"body": "Olá, {{nome}}! Como podemos ajudar?\n\n1 - Segunda via do boleto\n2 - Status do pedido\n3 - Falar com um atendente"
}
E envie pelo nome, com um clientRef para ligar a mensagem ao atendimento:
{
"to": "5511988887777",
"template": "menu_atendimento",
"variables": { "nome": "Maria" },
"clientRef": "atendimento-5521-menu"
}
No webhook, trate a resposta como a escolha de um botão:
const OPCOES = {
'1': 'segunda-via',
'2': 'status-pedido',
'3': 'atendente',
}
// dentro do handler do webhook, depois de verificar a assinatura HMAC
if (event.type === 'message.incoming') {
const escolha = OPCOES[(event.data.body ?? '').trim()]
if (escolha) {
await atendimento.seguir(event.data.phone, escolha)
} else {
await atendimento.encaminharParaHumano(event.data.phone, event.data.body)
}
}
Duas dicas que fazem diferença: guarde qual menu está aberto para cada telefone, para que um "1" seja lido no contexto certo; e sempre ofereça uma saída para falar com uma pessoa. Quem responde fora das opções não deve ficar preso num robô.
A alternativa hoje: reações para confirmar
Para um "sim ou não" simples, peça uma reação: "Reaja com 👍 para confirmar sua consulta". O evento message.reaction chega com o messageId da mensagem, o emoji e quem reagiu. Como o message.delivery já devolveu o messageId junto com o seu clientRef, o sistema sabe qual agendamento foi confirmado. Veja reações e presença.
Casos de uso e como montá-los hoje
| Caso | Com botões (não disponível) | Como fazer hoje |
|---|---|---|
| Confirmar um agendamento | Botões "Confirmar" e "Remarcar" | Texto com "1 - Confirmo / 2 - Remarcar" ou reação 👍 |
| Menu de atendimento | Lista de assuntos | Template com opções numeradas |
| Pesquisa de satisfação | Botões de nota | Pergunta com notas de 1 a 5 em texto |
| Escolher horário | Lista de horários | Dois ou três horários numerados |
Os eventos de webhook entregam cada resposta com o telefone, o texto e o messageId, então o seu sistema tem tudo o que precisa para seguir o fluxo.
E a API oficial?
A API oficial do WhatsApp, oferecida pela Meta, tem mensagens interativas documentadas, com as regras, a aprovação e a cobrança dela. Se botões e listas são indispensáveis para o seu produto, vale comparar os dois modelos no comparativo entre a apiwpp e a API oficial. Os recursos que o plano PRO da apiwpp inclui hoje, e os valores por número, estão em preços.
Perguntas frequentes
A apiwpp envia botões ou listas?
Não. Mensagens interativas não estão disponíveis na apiwpp, e ainda não há decisão sobre oferecê-las, porque pelo protocolo do WhatsApp Web elas não aparecem de forma confiável em todos os aparelhos.
Existe previsão de lançamento?
Não há data. O próximo passo é testar cada tipo de mensagem em aparelhos e contas diferentes. Se o resultado for bom, o recurso entra no plano PRO; se não for, o plano segue sem ele. Esta página será atualizada quando houver decisão.
Como faço um menu de atendimento sem botões?
Envie um template com opções numeradas e leia a resposta no evento message.incoming. Guarde qual menu está aberto para cada telefone e ofereça sempre a opção de falar com um atendente.
A alternativa em texto funciona no plano LITE?
Sim. Templates, respostas em texto pelo message.incoming e reações pelo message.reaction funcionam nos planos LITE e PRO.
Outros recursos
Todos: Recursos →Salve uma vez o texto de uma mensagem com variáveis como {{nome}} e {{pedido}} e envie pelo nome, preenchendo os valores em cada envio. Sem aprovação da Meta: o template vale assim que é criado.
Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.
Reaja a mensagens com emoji e receba as reações dos clientes pelo evento message.reaction em qualquer plano. Todo texto enviado mostra "digitando…" antes. No PRO, marque mensagens como lidas e controle a presença do número.