Pular para o conteúdo
apiwpp
RecursoEm breve

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

CasoCom botões (não disponível)Como fazer hoje
Confirmar um agendamentoBotões "Confirmar" e "Remarcar"Texto com "1 - Confirmo / 2 - Remarcar" ou reação 👍
Menu de atendimentoLista de assuntosTemplate com opções numeradas
Pesquisa de satisfaçãoBotões de notaPergunta com notas de 1 a 5 em texto
Escolher horárioLista de horáriosDois 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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.