Como criar botões e listas interativas no WhatsApp API na prática

Se você quer que o cliente clique em vez de digitar, criar botões e listas interativas no WhatsApp API é o caminho: você envia uma mensagem do tipo interactive pela WhatsApp Cloud API, escolhe entre botões de resposta (até 3) ou uma lista (até 10 itens no total) e recebe de volta, pelo webhook, o id exato do que a pessoa escolheu. Parece simples, e é, mas tem detalhe que quase todo mundo esbarra na primeira tentativa.

O primeiro deles: mensagem interativa livre só sai dentro da janela de 24 horas. Vou explicar isso melhor daqui a pouco, porque é o ponto que mais gera dúvida.

Os dois tipos de mensagem interativa que você vai usar

Na prática, 90% dos casos caem em dois formatos.

O botão de resposta (reply button) mostra até três opções em forma de botão logo abaixo do texto. Serve para pergunta objetiva: "Confirma o pedido?", com "Sim", "Não" e "Falar com atendente". É o formato mais clicado porque a escolha está na tela, sem precisar abrir nada.

A lista interativa (list) mostra um único botão que, ao ser tocado, abre um menu com itens agrupados em seções. Serve quando você tem muitas opções: escolher um serviço, um horário, um setor de atendimento. Cabem até 10 itens no total, somando todas as seções.

Existe ainda um terceiro caso, os botões que vão dentro de templates aprovados (quick reply, URL e ligação). Esses seguem regra diferente e valem um tópico próprio mais abaixo.

Botões de resposta: a estrutura do JSON

O envio é um POST para o endpoint de mensagens do seu número. O corpo fica assim:

{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "interactive", "interactive": { "type": "button", "body": { "text": "Recebemos seu pedido. Deseja confirmar?" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "confirma_sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "confirma_nao", "title": "Não" } } ] } } }

Os limites que você precisa respeitar aqui:

No máximo 3 botões por mensagem.
O title de cada botão tem limite curto (por volta de 20 caracteres). Se estourar, a API rejeita.
O id é seu, você define. É ele que volta no webhook quando a pessoa clica, então use algo que seu sistema entenda, tipo menu_agendar.
Os títulos dos botões não podem se repetir na mesma mensagem.

Você pode adicionar header (texto, imagem, vídeo ou documento) e footer (texto pequeno de rodapé). Não são obrigatórios, mas o header com imagem costuma aumentar bastante a taxa de clique em botão de confirmação.

Listas interativas: quando as três opções não bastam

A lista tem uma estrutura um pouco mais aninhada. Você define o rótulo do botão que abre a lista e, dentro de sections, agrupa os itens (rows):

{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "interactive", "interactive": { "type": "list", "header": { "type": "text", "text": "Atendimento" }, "body": { "text": "Escolha o setor que você precisa:" }, "footer": { "text": "Horário: 9h às 18h" }, "action": { "button": "Ver opções", "sections": [ { "title": "Comercial", "rows": [ { "id": "vendas", "title": "Falar com vendas", "description": "Novos planos e propostas" } ] }, { "title": "Suporte", "rows": [ { "id": "suporte_tec", "title": "Suporte técnico", "description": "Problemas na integração" } ] } ] } } }

Pontos de atenção que aprendemos apanhando:

São até 10 rows no total, não por seção. Se você tem 4 seções, a soma dos itens de todas não pode passar de 10.
Cada row exige id e title. O description é opcional, mas ajuda muito o cliente a entender a diferença entre itens parecidos.
O title da row tem limite em torno de 24 caracteres, e o description em torno de 72. O rótulo do botão (action.button) também é curto, na casa dos 20 caracteres.
O header na lista aceita apenas texto, diferente do botão que aceita mídia.

A janela de 24 horas muda tudo

Aqui está o erro número um de quem começa. Mensagens interativas livres, esses botões e listas montados no JSON, só podem ser enviadas dentro da janela de 24 horas, ou seja, depois que o cliente te mandou alguma mensagem. Fora dessa janela, o único jeito de reabrir a conversa é com um template aprovado pela Meta.

Então, se você tentar disparar uma lista interativa para um contato que nunca te respondeu ou cuja última mensagem foi há dois dias, a API devolve erro. Não é bug. É a regra de sessão do WhatsApp.

Na prática, o fluxo saudável é: você reabre a conversa com um template (que pode ter botões de quick reply), o cliente responde, a janela abre, e a partir daí você manda quantas listas e botões interativos quiser, de graça, durante 24 horas.

Botões dentro de templates: o outro caminho

Quando você precisa iniciar a conversa (fora da janela), os botões vão no próprio template, que passa por aprovação da Meta antes de existir. Os tipos disponíveis são:

Quick reply: botões de resposta rápida, que funcionam parecido com os reply buttons e devolvem o clique no webhook.
URL: leva o cliente para um link (pode ser dinâmico, com uma variável no final da URL).
Ligação: abre a discagem para um número que você definiu.

A diferença central: no template você monta os botões na hora de cadastrar o modelo, dentro da categoria certa (marketing, utilidade ou autenticação), e espera a aprovação. Na mensagem interativa de sessão, você monta o JSON livremente, sem aprovação prévia, mas só dentro da janela.

Segundo a covercut, BSP oficial do WhatsApp, quando um cliente nos procura reclamando que "a lista não sai", em quase todos os casos ele está tentando enviar mensagem interativa livre para um contato fora da janela de 24h. A solução não é mexer no JSON, é usar template para reabrir a conversa.

Como capturar a resposta do clique

De nada adianta o cliente clicar se seu sistema não lê o retorno. Quando alguém toca em um botão ou item de lista, a Meta envia um evento para o seu webhook. Dentro dele vem o id que você definiu.

Para botão de resposta, o retorno vem em interactive.button_reply.id. Para lista, em interactive.list_reply.id. É esse valor que seu backend usa para decidir o próximo passo do fluxo. Por isso vale a pena dar id semânticos: agendar_corte é muito mais fácil de tratar do que 1.

Erros comuns que derrubam o envio

Alguns que vemos com frequência e que economizam horas de debug:

Título de botão ou item acima do limite de caracteres. A API não trunca, ela recusa a mensagem inteira.
Enviar mais de 3 botões ou mais de 10 itens de lista.
Esquecer o body.text. Ele é obrigatório em ambos os formatos.
Repetir o mesmo id em dois botões ou duas rows.
Usar emojis ou caracteres estranhos no id. Mantenha o id simples, tipo letras, números e underline.

Se você usa uma ferramenta de atendimento sobre a API, como o Chatwoot integrado, boa parte dessa montagem de JSON fica escondida atrás da interface. Ainda assim, entender a estrutura ajuda quando algo não aparece como esperado, porque o limite de caracteres e a janela de 24h continuam valendo por baixo.

Coexistência: testar sem perder o número atual

Uma dúvida frequente antes de começar a montar fluxos: "vou perder o WhatsApp que já uso na loja?". Não. Com o modo de coexistência, o mesmo número segue funcionando no app do WhatsApp Business no celular e, ao mesmo tempo, na API oficial, sem apagar conta nem perder histórico. Isso permite testar botões e listas interativas na API enquanto sua equipe continua atendendo pelo app normalmente.

Na covercut você não cria app na Meta nem configura nada no Gerenciador manualmente: a conexão do número acontece pelo fluxo oficial (Embedded Signup) direto pela nossa plataforma, que é parceira Meta. A cobrança das conversas continua sendo direto entre você e a Meta, no cartão cadastrado na conta; a covercut cobra apenas a mensalidade fixa do serviço.

O próximo passo prático: escolha um único fluxo para começar, tipo um menu de atendimento com 3 botões, teste o retorno no seu webhook e só depois parta para listas mais longas. Fluxo interativo que ninguém lê no webhook é botão bonito que não faz nada.

Perguntas frequentes

Quantos botões posso colocar em uma mensagem do WhatsApp API?

Em mensagens interativas de resposta, o limite é de 3 botões. Se precisar oferecer mais opções, use uma lista interativa, que comporta até 10 itens no total distribuídos em seções.

Posso enviar botões interativos a qualquer momento?

Não. Botões e listas interativas livres só saem dentro da janela de 24 horas, ou seja, depois que o cliente te enviou uma mensagem. Fora dessa janela, é preciso reabrir a conversa com um template aprovado pela Meta, que pode conter botões próprios.

Qual a diferença entre botão de template e botão interativo?

O botão de template é definido no cadastro do modelo e passa por aprovação da Meta, servindo para iniciar conversas fora da janela. O botão interativo é montado livremente no JSON, sem aprovação prévia, mas só funciona dentro da janela de 24 horas.

Como sei em qual botão o cliente clicou?

A Meta envia o clique para o seu webhook. Para botões vem em interactive.button_reply.id e para listas em interactive.list_reply.id. O valor é o id que você mesmo definiu ao montar a mensagem, por isso use identificadores claros.

Preciso apagar meu WhatsApp atual para usar mensagens interativas?

Não. Com o modo de coexistência, o mesmo número funciona no app do celular e na API oficial ao mesmo tempo, sem perder histórico nem contatos. Você pode montar e testar seus fluxos interativos na API mantendo o atendimento no app.