Botões e listas na API de WhatsApp: o que realmente funciona hoje

Por que esse assunto confunde tanta gente

Quem pesquisa "botões no WhatsApp" encontra tutoriais antigos mostrando três botões de resposta embaixo da mensagem. Esse formato deixou de funcionar de forma estável fora dos canais controlados pela Meta, e muita integração quebrou sem aviso. O resultado é um mercado cheio de promessas que não se sustentam quando o cliente abre a mensagem.

Esta página separa o que você pode colocar em produção numa API de WhatsApp não oficial hoje, o que depende do dispositivo e o que é melhor evitar.

O mapa dos formatos interativos

A regra prática: se a escolha do cliente precisa voltar para o seu sistema e funcionar em qualquer tela, use lista. Os demais formatos são complementos.

Lista: o substituto confiável dos botões de resposta

A lista mostra um botão (o buttonText) que abre um menu com seções e opções. Cabem de 1 a 10 seções, cada uma com 1 a 10 linhas. Cada linha tem um rowId, que é o que o seu sistema recebe de volta, e um title, que é o que o cliente lê.

import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })

await dapi.interactive.sendList({
  sessionId: 'clinica-centro',
  to: '5511999999999',
  title: 'Sua consulta de amanhã',
  description: 'Dra. Paula, 14h30. Como prefere seguir?',
  buttonText: 'Responder',
  footerText: 'Clínica Centro',
  sections: [
    {
      title: 'Agenda',
      rows: [
        { rowId: 'confirmar', title: 'Confirmar presença' },
        { rowId: 'remarcar', title: 'Remarcar', description: 'Mostramos novos horários' },
        { rowId: 'cancelar', title: 'Cancelar' },
      ],
    },
  ],
})

Use rowId estáveis e sem acento. O título pode mudar por campanha ou idioma; o identificador é o contrato com o seu backend.

Como a escolha volta para o seu sistema

Quando o cliente toca numa opção, chega um evento messages.received com type: "list_response". Dentro dele vêm o selected_row_id, o título escolhido e um resumo da lista original. O fluxo típico fica assim:

1. Seu sistema envia a lista e guarda o contexto (qual consulta, qual pedido).
2. O cliente escolhe. O webhook recebe o list_response.
3. O worker lê o selected_row_id, cruza com o contexto do número e executa a ação: confirma, oferece horários, cancela.
4. Se o cliente digitar em vez de tocar, trate como texto livre e reenvie a lista ou chame um atendente.

O quarto passo é o que separa um fluxo que funciona de um que trava. Parte das pessoas sempre vai responder "sim" digitado, e o sistema precisa entender isso.

Botões de link, ligação, PIX e carrossel

Link e ligação

O endpoint /interactive/send/template envia uma mensagem com botões do tipo url ou call. Serve para "Ver pedido", "Acompanhar entrega" ou "Falar com a loja". Apesar do nome, não tem relação com os templates aprovados da API oficial.

curl -X POST https://api.d-api.cloud/api/v1/interactive/send/template \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "loja",
    "to": "5511999999999",
    "content": "Seu pedido 4471 foi enviado.",
    "buttons": [
      { "type": "url", "title": "Rastrear", "url": "https://loja.com/pedido/4471" },
      { "type": "call", "title": "Ligar para a loja", "phone": "5511988887777" }
    ]
  }'

NativeFlow

Aceita de 1 a 4 botões dos tipos quick_reply, url, call e copy. É o formato mais rico, mas aparece apenas no celular. Use quando você sabe que o público está no aplicativo e tenha sempre um plano B em texto.

PIX e carrossel

O envio de PIX recebe content e pixKey, com valor e mensagem opcionais, e facilita o pagamento em fluxos de cobrança pelo WhatsApp. O carrossel mostra cards lado a lado, cada um com mídia, texto e até dois botões, bom para vitrine de produtos.

Limitações que vale assumir desde o começo

• Renderização muda por dispositivo e versão do app. Teste no celular, no WhatsApp Web e no desktop antes de lançar.
• O WhatsApp pode mudar formatos sem aviso. Deixe o texto da mensagem autoexplicativo, para que ela faça sentido mesmo se os botões não aparecerem.
• Interativo não substitui consentimento. Mandar lista para quem não pediu continua sendo envio não solicitado.

Listas e botões costumam ser a peça visível de um fluxo maior, com gatilhos, esperas e condições. Se esse é o seu caso, veja os fluxos de automação e, para entender quando a API oficial faz mais sentido, API oficial vs não oficial.