Botões e listas no WhatsApp: mensagens interativas pela API

Mensagens interativas são as que oferecem opções em vez de texto: botões de resposta rápida, listas de opções e botão de link. Pela API oficial do WhatsApp, elas são enviadas dentro da janela de 24 horas; fora dela, os mesmos botões existem, mas dentro de um template aprovado. A resposta do cliente volta pelo webhook com o identificador da opção escolhida.

Por que botão vale mais do que parece

Um botão de resposta rápida gera uma mensagem do cliente. Mensagem do cliente reinicia a janela de 24 horas — em que o texto é livre e não é cobrado.

Um botão de URL não faz isso: ele leva a pessoa para fora do WhatsApp e não gera mensagem nenhuma. Quando o fluxo precisa de continuidade, é o botão de resposta rápida que a compra barato.

Dois botões numa confirmação de entrega custam o mesmo template e devolvem uma janela de 24 horas aberta. É a diferença entre notificar e conversar.

Botões de resposta rápida

Até três, com título curto:

curl -X POST https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "interactive",
    "to": "5541987111527",
    "interactive": {
      "type": "button",
      "body": { "text": "Podemos entregar amanhã entre 9h e 12h?" },
      "action": { "buttons": [
        { "type": "reply", "reply": { "id": "confirma", "title": "Pode sim" } },
        { "type": "reply", "reply": { "id": "remarcar", "title": "Quero remarcar" } }
      ]}
    }
  }'

O id é seu e é o que volta no webhook. Use um identificador estável e semântico — nunca o texto do botão, que muda quando alguém melhora a redação e quebra o seu roteamento em silêncio.

Listas de opções

Quando as alternativas passam de três, a lista substitui os botões: ela abre um menu, com seções e descrição em cada item. Serve bem para escolher horário, unidade de atendimento ou motivo de contato.

A regra prática é a mesma dos botões: identificador estável em cada item, título curto e uma descrição que evite a pergunta seguinte.

Botão de URL

Leva o cliente para uma página — rastreio, pagamento, carrinho. Em template, ele aceita variável no final da URL, o que permite um link por destinatário sem criar um template por pedido.

Não abre janela. Se você precisa que a conversa continue, combine com um botão de resposta rápida.

O que volta no webhook

Quando o cliente toca num botão, chega uma mensagem do tipo interativo com a opção escolhida:

{
  "type": "interactive",
  "interactive": {
    "type": "button_reply",
    "button_reply": { "id": "confirma", "title": "Pode sim" }
  }
}

Roteie pelo id, nunca pelo title. E trate o caso de o cliente responder com texto livre em vez de tocar no botão — que acontece bastante.

Interativos em template, fora da janela

Fora das 24 horas, o interativo precisa estar dentro de um template aprovado. Os botões são definidos na criação do template, não no envio — o que significa que você não muda as opções por mensagem.

Consequência de projeto: as opções precisam ser genéricas o suficiente para servir a todos os envios daquele template.

Boas práticas

• Título curto — botão com texto longo é truncado no aparelho.
• Opções mutuamente exclusivas — dois botões que significam quase a mesma coisa geram escolha aleatória.
• Sempre uma saída — "falar com atendente" evita que a pessoa fique presa no menu.
• Idempotência — o cliente pode tocar duas vezes; trate o segundo toque sem duplicar o efeito.
• Não use botão para consentimento — opt-in precisa de registro auditável, não de um toque ambíguo.

Como receber e validar esses eventos está em webhooks do WhatsApp.

Perguntas frequentes

Quantos botões posso ter?

Até três de resposta rápida por mensagem. Acima disso, use lista.

Botão funciona fora da janela de 24 horas?

Funciona, dentro de um template aprovado — com as opções definidas na criação do template, não no envio.

O toque no botão é cobrado?

A resposta do cliente não é cobrada, e ela abre a janela de 24 horas. O que é cobrado é o template que você enviou.

Dá para saber quem não respondeu?

Dá, pela ausência do evento de resposta associado ao wamid do envio. Vale um prazo de espera no seu fluxo antes de considerar sem resposta.