enquete e mensagens nativas
Enquete WhatsApp API e mensagens nativas para o seu SaaS
Com a enquete da WhatsApp API, o seu SaaS faz uma pergunta e recebe o voto já com o nome da opção escolhida. Localização, cartão de contato e reação completam as mensagens nativas que o seu cliente usa todo dia.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Enquete de 2 a 12 opções
Pergunta, opções e escolha única ou múltipla em quatro campos, com o voto chegando por webhook.
Voto com nome da opção
O WhatsApp entrega o voto como hash. A D-API guarda as opções da enquete e devolve selected_options com o texto escolhido.
Localização e contato
Coordenadas com nome e endereço do local, ou um cartão de contato pronto para salvar, sem link externo.
Reação em uma linha
Reaja a uma mensagem pelo messageId para confirmar recebimento, e remova enviando emoji vazio.
Uma enquete pela WhatsApp API transforma uma pergunta em dado estruturado. A escola quer saber quais responsáveis vão à reunião, a clínica quer a nota do atendimento, o organizador de eventos quer confirmar presença. Em texto livre, cada resposta vem num formato diferente e alguém precisa ler uma por uma. Com a enquete, o contato toca numa opção e o seu SaaS recebe o voto pronto para contar.
Na API de WhatsApp da D-API, a enquete divide espaço com outras mensagens nativas do aplicativo que o cliente final já conhece: localização, cartão de contato e reação. São quatro rotas em /api/v1/messages/send/*, com o mesmo sessionId, o mesmo to e o mesmo header de autenticação do envio de texto.
Enquete pela API: quando faz sentido no seu produto
Enquete funciona quando as opções são poucas e claras. Alguns usos comuns entre clientes SaaS:
- Edtech. Confirmação de presença em aula ao vivo ou escolha do próximo tema, enviada para o grupo da turma.
- Clínicas. Pesquisa de satisfação depois da consulta, com notas de 1 a 5.
- Eventos e condomínios. Votação de horário para uma reunião, com escolha múltipla.
- Atendimento. Uma pergunta de triagem no início da conversa, antes de passar para o atendente certo.
Para menus com muitas opções ou com descrição em cada item, a lista interativa costuma ser melhor, e para escolher entre produtos com foto, o carrossel. O artigo sobre mensagens interativas compara os formatos.
Como enviar uma enquete
O POST /api/v1/messages/send/poll recebe sessionId, to, question e options. As opções são de 2 a 12, cada uma com pelo menos um caractere. O campo opcional multipleAnswers libera a escolha de várias opções; sem ele, o contato marca uma só.
curl -X POST https://api.d-api.cloud/api/v1/messages/send/poll \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "escola-4821",
"to": "5511999999999",
"question": "Qual horário funciona melhor para a reunião de pais?",
"options": ["Terça 19h", "Quarta 19h", "Sábado 10h"],
"multipleAnswers": true
}'
No envio síncrono, a resposta traz o messageId da enquete. Guarde esse ID: é ele que liga cada voto à pergunta no seu banco.
Lendo os votos no webhook
O voto chega no evento messages.received com type: "poll_update". Aqui está o detalhe que mais confunde quem integra enquete: o WhatsApp não manda o texto da opção, só um hash (sha256) de cada opção escolhida. Sem tradução, o seu sistema recebe uma lista de hashes e precisa descobrir a que opção cada um corresponde.
A D-API faz essa tradução. Quando a enquete é enviada pela API, as opções ficam guardadas por 30 dias, associadas ao ID da mensagem. Quando o voto chega, a D-API compara os hashes e acrescenta ao data da mensagem:
| Campo | O que traz |
|---|---|
poll_message_id |
ID da enquete votada |
selected_option_hashes |
Hashes enviados pelo WhatsApp |
selected_options |
Nome das opções escolhidas, na ordem do voto |
selected_options_resolved |
true quando todos os hashes foram traduzidos |
vote_count |
Quantidade de opções no voto |
As opções também são aprendidas quando a enquete é criada em outro aparelho do mesmo número e chega à conexão. Três situações deixam o voto só com hashes: enquete enviada com async: true (a resposta ainda não tem messageId para guardar as opções), enquete que a conexão nunca viu e voto depois dos 30 dias. Se o resultado legível importa, envie a enquete no modo síncrono.
Um caso de borda: quando o voto não pode ser decifrado na primeira tentativa, ele chega com decryption_failed: true e sem opções. A conexão pede a enquete de novo ao aparelho e, quando consegue, reenvia o mesmo voto, com o mesmo ID da mensagem, agora com recovered: true e a seleção preenchida. Trate o ID da mensagem como chave e deixe a versão com voto substituir a vazia.
Localização: endereço da loja ou ponto de encontro
O POST /api/v1/messages/send/location exige latitude e longitude, e aceita name e address para o cartão do local. Uma plataforma de delivery manda o endereço de retirada, um CRM imobiliário manda o ponto do imóvel antes da visita, um software de eventos manda o local do credenciamento.
{
"sessionId": "imobiliaria-4821",
"to": "5511999999999",
"latitude": -23.5874,
"longitude": -46.6389,
"name": "Apartamento Vila Mariana",
"address": "Rua Exemplo, 120, São Paulo"
}
Quando o contato envia uma localização, o evento messages.received chega com type: "location" e traz degrees_latitude, degrees_longitude, name, address e um thumbnail em base64.
Cartão de contato: passe o atendimento adiante
O POST /api/v1/messages/send/contact recebe contactName e contactPhone. É o jeito limpo de apresentar o corretor responsável, o técnico que vai à casa do cliente ou o setor financeiro, com um contato que o cliente final salva com um toque. Na recepção, o tipo contact traz contact_name, contact_phone, display_name e o vcard completo.
Localização e contato aceitam contextInfo para responder a uma mensagem específica, citando o stanzaId da original.
Reação: confirmação sem poluir a conversa
O POST /api/v1/messages/send/reaction reage a uma mensagem pelo messageId. O emoji aceita até 10 caracteres, e emoji vazio remove a reação. O campo fromMe (padrão false) indica se a mensagem reagida foi enviada pela própria conexão.
{
"sessionId": "clinica-4821",
"to": "5511999999999",
"messageId": "3EB00E07AFE6175651FCE9",
"emoji": "\u2705"
}
No exemplo, o emoji vai escapado em JSON (\u2705 é o check verde), o que evita problema de encoding no seu código.
Um uso prático em atendimento: reagir ao comprovante enviado pelo paciente para sinalizar “recebido” sem abrir uma nova mensagem. Na recepção, o tipo reaction traz original_message_id, reaction_text, reaction_timestamp e target_participant, este último em grupos.
Boas práticas para mensagens nativas em escala
- Salve o ID de cada envio. Enquete, reação e resposta citada dependem de IDs. Grave o
messageIdjunto da entidade do seu sistema. - Idempotência no handler. O mesmo voto pode chegar duas vezes, por retentativa de webhook ou recuperação de voto. Use o ID da mensagem como chave.
- Filtre por
fromMe. O webhook também registra mensagens enviadas pelo próprio número em outro aparelho. O artigo sobre webhooks da API de WhatsApp mostra como separar. - Grupos para turmas e comunidades. O
toda enquete aceita o JID de um grupo, então a mesma rota serve para votações em grupos pela API.
Os campos de cada tipo recebido estão na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Quantas opções uma enquete pode ter?
A rota aceita de 2 a 12 opções, cada uma com pelo menos um caractere. Com multipleAnswers: true, o contato pode marcar várias; sem ele, a escolha é única.
Por que o voto às vezes chega sem o nome da opção?
O WhatsApp só envia o hash de cada opção. A D-API traduz o hash quando conhece a enquete: enviada de forma síncrona pela API ou criada em outro aparelho e recebida pela conexão, com as opções guardadas por 30 dias. Fora disso, o voto fica só com os hashes.
Como removo uma reação que enviei pela API?
Envie o POST /api/v1/messages/send/reaction com o mesmo messageId e emoji vazio. O campo emoji aceita até 10 caracteres.
Para reagir a uma mensagem que eu mesmo enviei, o que muda?
Envie fromMe: true. O padrão é false, que vale para mensagens recebidas do contato.
A localização recebida vem com mapa?
O evento messages.received com type location traz degrees_latitude, degrees_longitude, name, address e um thumbnail em base64. O mapa você monta no seu front a partir das coordenadas.