integração · catálogo de eventos
Eventos de webhook do WhatsApp, um a um, com o payload de cada
O catálogo dos eventos de webhook do WhatsApp na D-API, para o seu SaaS saber o que ligar e o que esperar em data: mensagens, ticks, conexão, chats, grupos, etiquetas, chamadas e histórico.
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
Um envelope para todos
event, sessionId, data, timestamp e traceId em todo evento. Só o conteúdo de data muda.
Ligue só o que usa
Cada evento tem enabled próprio. Evento desabilitado não é enviado, e no modo per_event cada um tem a sua URL.
Deduplicação na origem
Leitura e entrega têm janela de 30 segundos, presença de 5 segundos e chats e contatos têm debounce de 2 segundos.
Os eventos de webhook do WhatsApp definem o que o seu SaaS consegue mostrar ao cliente em tempo real: a mensagem nova na inbox, o tick azul na proposta, o aviso de que o número caiu, a ligação tocando. Escolher bem quais eventos ligar reduz tráfego e simplifica o handler. Conhecer o payload de cada um evita os bugs que só aparecem em produção, como tratar edição como mensagem nova ou perder o logout.
Esta página é o catálogo, organizado por grupo, com os campos que importam em data. Para configuração, política de entrega, retentativa e deduplicação do lado do seu endpoint, o artigo sobre webhook WhatsApp API cobre o assunto em detalhe.
O envelope que todos os eventos compartilham
Todo evento chega com event (o nome), sessionId (a sessão de origem), data (o conteúdo específico), timestamp em ISO 8601 e traceId para rastreamento. Os headers são Content-Type: application/json e User-Agent: Deliverify-Webhook/1.0. A partir daqui, a página descreve só o que vai dentro de data.
Eventos de mensagem
messages.received
O evento central de qualquer inbox. Dispara para mensagens recebidas de contatos (fromMe: false) e também para mensagens enviadas pelo próprio número em outro aparelho (fromMe: true).
Campos principais: id, type, message (o texto), timestamp em milissegundos, fromMe, is_group, group_name, from com jid, lid e name, to, from_name e media_url. O campo isMetaAI vem sempre e é true quando a mensagem foi escrita pela Meta AI da conta business do contato.
O type diz como ler o resto: text, image, video, audio, document, sticker, contact, location, reaction, edited_message, poll_update, list_response, template_button_reply, list, carousel e nativeflow. Em mídia, media_data traz mimetype, file_length, caption, duration, is_ptt em áudio e filename em documento. Em respostas, context_info traz quoted_message_id e a mensagem citada; em conversas vindas de anúncio, traz a origem do clique.
Dois tipos pedem cuidado. Em edited_message, o ID da mensagem original está em data.data.original_message_id, e o data.id é o ID do evento de edição. Em list_response e template_button_reply, a escolha do cliente vem em selected_row_id ou selected_id, que é o que um fluxo de mensagens interativas usa para decidir o próximo passo.
messages.sent
Dispara só para mensagens enviadas pela API (/messages/send/* e /interactive/send/*). A estrutura é a mesma de messages.received para o mesmo type, com fromMe: true, from sendo o número da sessão e to o destinatário. Quando a mídia é enviada por URL externa, media_data pode trazer pending_media_url, e o id pode vir em letras maiúsculas: normalize antes de comparar com o messageId que a rota de envio devolveu.
Status de mensagem
message.delivered e message.read têm o mesmo formato:
{
"event": "message.read",
"sessionId": "clinica-sorriso",
"timestamp": "2026-11-15T13:00:00.000Z",
"data": {
"message_id": "3EB0F61B5D1F94FAFCD306",
"remote_jid": "[email protected]",
"participant": "",
"timestamp": 1794747600000
}
}
O participant só vem preenchido em grupos. Confirmações repetidas do mesmo status para o mesmo message_id dentro de 30 segundos não geram webhooks duplicados.
message.deleted avisa mensagem apagada, com message_id, chat_jid, sender_jid, is_from_me e timestamp. E message.update aparece na configuração, mas não é disparado: edição chega em messages.received, como descrito acima.
Eventos de conexão
São os eventos que mantêm a tela de conexão do seu produto viva e avisam quando o cliente precisa reconectar.
| Evento | O que traz em data |
|---|---|
connection.qrcode |
qr (texto do QR) e qrImage (PNG em data URL, pode vir null) |
connection.paircode |
code (o código a digitar no aparelho) e phone |
connection.status |
status e, conforme o estado, jid, phone, name, profilePictureUrl, connected ou reason |
session.created |
Conexão da API Oficial provisionada pelo connect hospedado, com connectionId, wabaId, phoneNumberId, accessToken e metadata |
O data.status de connection.status assume connected, disconnected, logged_out ou qrcode_timeout. O logout nunca chega como evento próprio: é sempre connection.status com status: "logged_out" e um reason, como device_removed. O qrcode_timeout aparece quando a sessão passa 45 minutos gerando QR sem leitura e sem pedido de QR; a D-API hiberna a geração e a sessão volta no próximo pedido de QR. QR idêntico ao anterior não gera novo connection.qrcode.
O session.created carrega o access token da Meta da conexão, por isso só é entregue no webhookUrl da própria conexão e apenas por HTTPS.
Chats, contatos e presença
chats.upsert (chat criado ou recebido na sincronização) e chats.update (chat alterado) trazem jid, name, unread_count, conversation_timestamp em segundos, archived, pinned e mute_end_time. contacts.upsert e contacts.update trazem jid, push_name, full_name, first_name e business_name. Os eventos .upsert passam por debounce de 2 segundos por chat ou contato, agrupando atualizações em sequência.
presence informa jid, name, unavailable (true para offline) e last_seen em segundos, com deduplicação de 5 segundos por contato e estado. É o evento que alimenta o “online” ao lado do nome na sua inbox.
Grupos
Os quatro eventos de participantes compartilham o formato: groups_participants.join, .leave, .promote e .demote, com group_jid, group_name, participants (lista de JIDs), timestamp em segundos e sender, quem executou a ação. Para grupos com aprovação de entrada, group_participants.join-request traz requester_jid e requester_name, e há as variantes .revoked e .approved. A gestão de grupos pela API está em grupos pela API de WhatsApp.
Etiquetas
labels.edit avisa etiqueta criada, editada ou excluída, com label_id, name, color, deleted, list_type (como custom ou as listas do próprio WhatsApp) e is_immutable. labels.association.chat avisa etiqueta aplicada ou removida de uma conversa, com label_id, label_name, chat e labeled, e labels.association.message faz o mesmo para uma mensagem. É o par de eventos que um CRM usa para espelhar o funil, como mostra a página de etiquetas pela API.
Chamadas
Todos os eventos call.* trazem phone, o telefone da outra ponta, só dígitos, que é o campo certo para identificar o contato. call.offer avisa chamada recebida, com callId e isGroup. Nas chamadas de saída, call.ringing, call.connected, call.ended e call.not_answered acompanham o andamento, com reason no encerramento. call.accepted e call.rejected cobrem atendimento em outro aparelho e recusa. call.audio tem duas variantes: chunks ao vivo, com volume alto, em torno de um evento por segundo por chamada, ou um único evento final com as URLs da gravação no modo stream. A página de webhook de chamadas entra nos detalhes.
Histórico e sincronização
| Evento | No webhook | No RabbitMQ |
|---|---|---|
history.message.upsert |
Suprimido | Entregue |
history.message.received |
Suprimido | Entregue |
history.messages.sent |
Convertido em messages.received com fromMe: true, só os recentes, com menos de 5 minutos |
Entregue com o nome original |
history_sync |
Entregue, com chats, contacts e messages do backfill |
Entregue |
appstate.agent.update |
Entregue | Entregue |
As mensagens de histórico seguem o formato de messages.received, sem mídia e com JIDs normalizados. Se o seu produto precisa delas, o caminho é a integração com RabbitMQ.
Os eventos que um SaaS liga primeiro
Para a primeira versão de uma inbox, cinco eventos bastam: messages.received, messages.sent, message.delivered, message.read e connection.status. Com isso você tem conversa, ticks e alerta de desconexão. connection.qrcode entra quando a tela de conexão fica dentro do seu produto. Etiquetas, grupos e chamadas entram conforme o recurso. O command.result dos comandos assíncronos vem por outro canal, um webhook de conta, e não aparece nesta lista.
O detalhe de cada campo, com os exemplos por tipo de mensagem, está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Existe um evento para mensagem editada?
A edição chega por outro caminho. message.update não é disparado; a edição chega em messages.received com type edited_message, e o ID da mensagem original vem em data.data.original_message_id.
Como detecto que o cliente desconectou o WhatsApp?
Pelo connection.status. Não há evento logged_out separado: o logout chega como connection.status com data.status logged_out. Trate também disconnected para pedir reconexão.
Existe evento de pedido de entrada em grupo rejeitado?
Não. Os eventos de solicitação são join-request, join-request.revoked e join-request.approved. Para cancelamento pelo solicitante, use o .revoked.
Por que o histórico não chega no meu webhook?
history.message.upsert e history.message.received são suprimidos no webhook para evitar uma enxurrada de chamadas durante a sincronização. Eles chegam só pelo RabbitMQ. O history_sync, que resume o backfill, chega normalmente.
As etiquetas que o cliente já tinha geram evento ao conectar?
Não. A sincronização inicial de etiquetas não gera webhook. Leia o estado completo em GET /api/v1/labels/list e GET /api/v1/labels/contact-labels e use os eventos labels.* para as mudanças seguintes.