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

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.

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.