Pular para o conteúdo
D-APITestar grátis

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 messageId junto 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 to da 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.