Enquetes pelo WhatsApp com votos no webhook (em breve no PRO)
Enquetes pela API de WhatsApp com os votos no seu webhook estão em desenvolvimento para o plano PRO. Veja o que está previsto e como confirmar respostas hoje.
Atualizado em
Uma enquete é a forma mais rápida de pedir uma decisão pelo WhatsApp: a pessoa toca numa opção e pronto, sem digitar nada. Para quem integra sistemas, é ainda melhor: o voto é uma resposta estruturada, que o seu sistema consegue ler sem interpretar texto livre.
Este recurso ainda não está disponível. Enquetes pela API estão em desenvolvimento na apiwpp e vão fazer parte do plano PRO. Esta página explica o que está previsto e, principalmente, como resolver os mesmos casos hoje com o que já funciona.
O que está previsto
O desenho atual da apiwpp para enquetes tem duas partes:
- Enviar a enquete pelo mesmo
POST /connections/{id}/sendusado para texto e mídia, com a pergunta e as opções, permitindo escolha única ou múltipla. Por passar pela fila do número, a enquete vai respeitar os mesmos limites de ritmo e de destinatários novos de qualquer mensagem. - Receber os votos num evento de webhook novo,
message.poll_vote, com a enquete a que o voto pertence, quem votou e as opções escolhidas.
Os nomes dos campos e o formato final do evento serão publicados na documentação quando o recurso for lançado, e podem mudar até lá. Como todo evento novo, ele será adicionado ao contrato de webhooks sem alterar os que já existem. Se o seu código já ignora tipos de evento desconhecidos, como a apiwpp recomenda, ele não quebra no dia do lançamento.
Onde enquetes ajudam
- Confirmar um agendamento. "Confirma sua consulta amanhã às 15h?" com as opções "Confirmo" e "Preciso remarcar". O voto atualiza a agenda sem que ninguém leia a conversa.
- Pesquisa de satisfação. Uma pergunta curta depois do atendimento, com notas de 1 a 5, somadas direto no seu painel.
- Escolha de horário ou entrega. Oferecer dois ou três horários disponíveis e reservar o que o cliente tocar.
- Decisões em grupo. Uma turma ou equipe escolhendo a data de um encontro.
Em todos esses casos, a mensagem vai para quem já é cliente e espera o contato. Enquetes não mudam a regra de ouro da apiwpp: conversar com quem conhece você é o que protege o número.
Como resolver hoje: resposta em texto
Até as enquetes chegarem, o jeito mais simples de coletar uma decisão é pedir uma resposta curta e ler o texto no webhook message.incoming. Funciona nos planos LITE e PRO, em qualquer versão do WhatsApp.
Envie a pergunta com opções numeradas, usando um clientRef para ligar a mensagem ao agendamento:
{
"to": "5511988887777",
"message": "Olá, Maria! Confirma sua consulta amanhã às 15h?\n\n1 - Confirmo\n2 - Preciso remarcar",
"clientRef": "agendamento-8812-confirmacao"
}
No webhook, normalize a resposta e aceite as variações mais comuns:
const CONFIRMA = ['1', 'sim', 'confirmo', 'confirmado', 'ok']
const REMARCA = ['2', 'remarcar', 'não']
function lerResposta(texto) {
const t = (texto ?? '').trim().toLowerCase()
if (CONFIRMA.includes(t)) return 'confirmado'
if (REMARCA.includes(t)) return 'remarcar'
return null // resposta livre: encaminhe para um atendente
}
// dentro do handler do webhook, depois de verificar a assinatura
if (event.type === 'message.incoming') {
const decisao = lerResposta(event.data.body)
if (decisao) await agenda.registrarResposta(event.data.phone, decisao)
}
Guarde qual pergunta está pendente para cada telefone: assim uma resposta "1" é ligada ao agendamento certo, mesmo que a pessoa tenha outras conversas com o número.
Como resolver hoje: reações
Outra opção, útil para confirmações simples, é pedir uma reação: "Reaja com 👍 para confirmar". Quando a pessoa reage, chega o evento message.reaction com o messageId da mensagem, o emoji e quem reagiu. Como você guardou o messageId a partir do evento message.delivery (que traz o seu clientRef), sabe exatamente qual agendamento foi confirmado.
Uma reação removida chega com o emoji vazio, então dá para tratar também quem desistiu da confirmação. Veja mais sobre reações e presença.
Plano PRO e teste grátis
Quando lançadas, as enquetes serão um recurso do plano PRO. Hoje o PRO inclui editar e apagar mensagens enviadas, marcar como lidas, presença e o IP dedicado como adicional; os valores por número estão em preços. O teste grátis de 7 dias inclui os recursos do PRO (exceto IP dedicado), com 1 número e sem cartão.
Para o fluxo completo de lembretes com confirmação do cliente, veja o caso de uso de agendamentos e o guia de lembretes de agendamento pelo WhatsApp.
Perguntas frequentes
Já posso enviar enquetes pela API?
Ainda não. Enquetes estão em desenvolvimento e serão lançadas no plano PRO. Hoje, a confirmação é feita com uma resposta em texto lida no evento message.incoming ou com uma reação recebida no evento message.reaction.
Quando as enquetes forem lançadas, como vou receber os votos?
O desenho atual prevê um evento de webhook novo, message.poll_vote, com a enquete, quem votou e as opções escolhidas. O formato final será publicado na documentação no lançamento.
Enquetes vão respeitar os limites de envio?
Sim. O envio de uma enquete está previsto para passar pela mesma fila de qualquer mensagem, com os limites de ritmo e o teto de destinatários novos por 24 horas.
A alternativa em texto funciona no plano LITE?
Sim. Enviar a pergunta, receber a resposta pelo message.incoming e as reações pelo message.reaction funcionam nos planos LITE e PRO.
Outros recursos
Todos: Recursos →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.
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.