Catálogo de eventos

Webhook e WebSocket compartilham o mesmo envelope e o mesmo catálogo de eventos. A única diferença é o canal de entrega, o data é idêntico. Esta página documenta os 6 tipos: message.exchange, message.status, call.update, group.flow, instance.state e label.update.

Envelope

{
  "event": "<event-name>",
  "data": { /* payload específico */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "<name>",
    "token":    "<instance-token>"
  }
}

Filtragem é feita pelo nome do event no campo events da config. Vazio = todos os tipos.

Filtragem e roteamento

{ "events": ["message.exchange", "call.update", "instance.state"] }

Quando byEvents=true (apenas em webhook), o nome do evento é anexado à URL:

Config: url: "https://app/wh", byEvents: true
Delivery: POST https://app/wh/message.exchange

Útil para roteamento por endpoint sem precisar inspecionar o payload.

`message.exchange`

Mensagens enviadas e recebidas (texto, mídia, sticker, documento, áudio, enquete, contato, localização, etc.), edits e revogações.

Payload

{
  "id": "wamid.msg.123",
  "message": {
    "id": "wamid.msg.123",
    "direction": "incoming | outgoing",
    "timestamp": "2026-04-28T10:30:00Z",
    "chat": {
      "jid": "5511999999999",
      "lid": "100@s.whatsapp.net",
      "name": "João Silva",
      "type": "private | group | newsletter",
      "isCommunity": true
    },
    "sender": {
      "jid": "5511999999999",
      "lid": "100@s.whatsapp.net",
      "name": "João Silva"
    },
    "content": { "text": "Ola" },
    "media": {
      "type": "image | video | audio | document | sticker | ptt | ptv",
      "url": "https://media-...whatsapp.net/...",
      "s3Url": "https://bucket.s3.amazonaws.com/...",
      "base64": "iVBORw0KGgo...",
      "mimetype": "image/jpeg",
      "size": 45678,
      "caption": "Foto do evento",
      "fileName": "doc.pdf"
    },
    "edit": {
      "original_id": "wamid.original",
      "originalContent": "Texto antigo",
      "text": "Texto novo"
    },
    "forward": { "count": 2 },
    "reply": {
      "message_id": "wamid.replied",
      "sender": { "jid": "...", "name": "..." },
      "text": "...",
      "media": { /* objeto media simplificado */ }
    },
    "poll": {
      "title": "Qual sabor?",
      "options": [{ "name": "Chocolate", "count": 0 }]
    },
    "location": {
      "latitude": -23.5505,
      "longitude": -46.6333,
      "address": "Av. Paulista, 1374"
    },
    "contact": {
      "display_name": "Maria",
      "phone_number": "5511987654321",
      "vcard": "BEGIN:VCARD..."
    },
    "list_response": {
      "title": "...",
      "body": "...",
      "list_type": "single_select",
      "single_select_reply": { "option_name": "p1" }
    },
    "button_response": {
      "title": "Comprar",
      "body": "...",
      "selected_button_id": "buy_camiseta"
    },
    "interactive": { /* form / native flow / outras superfícies */ },
    "adOrigin": {
      "entryPointSource": "ctwa_ad | click_to_chat_link | global_search_new_chat | qr_code",
      "adType": "CTWA | CAWC",
      "sourceId": "120210350926390440",
      "ctwaClid": "AfjMN6zW...",
      "sourceApp": "instagram | facebook",
      "sourceType": "ad",
      "sourceUrl": "https://www.instagram.com/p/DGnlj_hAqGX/",
      "title": "Príncipe do Mutá Hotel Design",
      "body": "Aqui, seus dias são mais felizes!",
      "mediaType": "IMAGE | VIDEO",
      "thumbnailUrl": "https://scontent-...fbcdn.net/...",
      "greetingMessageBody": "Olá! Como podemos ajudar?",
      "conversionSource": "FB_Ads",
      "entryPointExternalSource": "FB_Ads",
      "ctwaPayload": "QWZqa2xTQkt...(base64)",
      "originalImageUrl": "https://.../ad-creative.jpg",
      "clickToWhatsappCall": true
    }
  }
}

Campos condicionais

Apenas os campos relevantes para o tipo da mensagem são preenchidos. Edits têm edit populado; revogações chegam com type: "message_revoke" em data.message.type.

chat.isCommunity aparece apenas quando true, indica que o chat é o canal de aviso (parent / announcement channel) de uma comunidade WhatsApp. Subgrupos vinculados a uma comunidade continuam com type: "group" e sem o campo isCommunity. Em grupos comuns e DMs o campo também é omitido.

media.base64 só aparece quando mediaBase64=true na config (webhook ou WebSocket). Caso contrário, use media.url (whatsapp.net, expira) ou media.s3Url (se S3 estiver configurado na instância).

`adOrigin` — atribuição de origem (Click-to-WhatsApp)

Presente apenas na primeira mensagem recebida de uma conversa iniciada por um anúncio Meta ou por um ponto de entrada (link wa.me, busca, QR). Permite rotear o lead por campanha sem consultar o banco. Dois cenários:

Anúncio nativo (Click-to-WhatsApp / Call Ads) — entryPointSource é ctwa_ad e vem o bloco completo: sourceId (ID do anúncio — agrupa leads por campanha), ctwaClid (chave de atribuição da Meta, use na Conversions API), sourceApp, sourceUrl, title, body, mediaType, greetingMessageBody, além de conversionSource, entryPointExternalSource, ctwaPayload (token base64 para a Conversions API), originalImageUrl e clickToWhatsappCall.
Ponto de entrada sem anúncio — link wa.me (click_to_chat_link), busca do WhatsApp (global_search_new_chat), QR code, etc. Vem apenas entryPointSource (e, quando disponível, entryPointApp / entryPointDelaySeconds), sem sourceId / ctwaClid — a Meta não anexa dados de anúncio a esses.

Mensagens orgânicas — e qualquer mensagem que não seja a primeira da conversa — não trazem adOrigin. O texto pré-preenchido de um anúncio não é prova de origem: a atribuição confiável vem de sourceId / ctwaClid.

Exemplo (recebimento de imagem)

{
  "event": "message.exchange",
  "data": {
    "id": "wamid.123",
    "message": {
      "id": "wamid.123",
      "direction": "incoming",
      "timestamp": "2026-04-28T10:30:00Z",
      "chat":   { "jid": "5511999999999", "name": "João", "type": "private" },
      "sender": { "jid": "5511999999999", "name": "João" },
      "media": {
        "type":     "image",
        "url":      "https://media-abc.whatsapp.net/...",
        "mimetype": "image/jpeg",
        "size":     45678,
        "caption":  "Foto"
      }
    }
  },
  "instanceData": { "baseUrl": "https://api...", "instance": "minha", "token": "..." }
}

`message.status`

Recibos de entrega: delivered, read, played, etc.

Payload

{
  "status": "delivered | read | played | sender | read_self | played_self | retry | inactive | server_error",
  "messageIds": ["wamid.123", "wamid.124"],
  "timestamp":  "2026-04-28T10:45:00Z",
  "chat": {
    "jid": "5511999999999",
    "type": "private | group | broadcast",
    "isCommunity": true
  },
  "recipient":     "5511999999999",
  "messageSender": null,
  "isFromMe":      false
}

Enum `status`

Valor	Significado
`delivered`	Mensagem chegou no device do destinatário.
`read`	Destinatário leu (read receipts ativos).
`played`	Áudio/voice note foi reproduzido.
`sender`	Eco interno (a própria origem reportando entrega).
`read_self`	O próprio usuário marcou como lido em outro device.
`played_self`	O próprio usuário reproduziu em outro device.
`retry`	Servidor pediu reentrega (transient).
`inactive`	Destinatário offline há tempo demais.
`server_error`	Erro genérico do servidor WhatsApp.

messageSender em grupos: JID do autor original da mensagem (relevante quando alguém leu uma mensagem de outro participante).
chat.isCommunity segue a mesma regra de message.exchange: presente e true apenas quando o chat é o canal de aviso de comunidade.

`call.update`

Eventos de chamada: oferta, aceite, recusa, encerramento, latência.

Payload

{
  "type": "offer | accepted | rejected | terminated | notification | latency",
  "direction": "incoming | outgoing",
  "callId": "call-abc123",
  "from": "5511999999999",
  "to":   "5511888888888",
  "timestamp": "2026-04-28T10:35:00Z",
  "groupJid": null,
  "callMedia": "audio | video | null",
  "remotePlatform": "Android | iPhone | null",
  "remoteVersion": "2.23.15.74",
  "noticeType": "group | null",
  "reason": null,
  "duration": 123,
  "latency":  45.6,
  "latencyStatus": "Excellent | Good | Average | Poor"
}

Enum `type`

Valor	Quando dispara
`offer`	Chamada recebida/enviada (toque inicial).
`accepted`	Lado remoto atendeu.
`rejected`	Lado remoto rejeitou.
`terminated`	Chamada encerrada, `duration` em segundos vem populado.
`notification`	Notificação contextual de chamada (ex.: chamada perdida em grupo).
`latency`	Métrica de latência durante a chamada (`latency` em ms, `latencyStatus`).

Para rejeitar chamadas automaticamente, configure autoRejectCalls=true no bloco settings da instância, você ainda recebe os eventos offer + rejected no webhook.

`group.flow`

Mudanças em grupos: membros, metadata, settings.

Payload, participant change

{
  "type": "joined | left | promoted | demoted",
  "groupJid": "120363406289005073@g.us",
  "groupName": "Time de Dev",
  "timestamp": "2026-04-28T11:00:00Z",
  "participants": [
    { "jid": "5511999999999", "action": "joined" }
  ]
}

Subtipos de metadata

`type`	Significado
`name`	Nome do grupo alterado
`topic`	Descrição alterada
`locked` / `unlocked`	Members can/cannot edit info
`announce` / `not_announce`	Members can/cannot send messages
`ephemeral` / `not_ephemeral`	Mensagens efêmeras on/off
`invite`	Invite link gerado
`link` / `unlink`	Subgrupo vinculado/desvinculado de comunidade
`delete`	Grupo deletado
`membership_approval`	Modo de aprovação de novos membros alterado
`suspended` / `unsuspended`	Grupo suspenso/reativado pelo WhatsApp

`instance.state`

Mudanças no estado da própria instância (conexão, QR, ban, pareamento).

Payload

{
  "instance": "minha",
  "state": "connected | disconnected | logged_out | stream_replaced | temp_banned | client_outdated | connect_failure | stream_error | cat_refresh_error | qr_ready | pair_success | pair_error | qr_scanned_no_multidevice | keepalive_timeout | keepalive_restored | manual_reconnect",
  "timestamp": "2026-04-28T10:50:00Z",
  "reason": "...",
  "reasonCode": 123,
  "message": "...",
  "expireAt": "2026-04-28T11:50:00Z",
  "expireInSeconds": 3600,
  "onConnect": true,
  "codes": ["1@abc...,xyz==,base64string"],
  "jid": "5511999999999@s.whatsapp.net",
  "platform": "iPhone | Android | Desktop",
  "errorMsg": "..."
}

Enum `state`

State	Significado	Campos extras populados
`connected`	Sessão ativa, pronta para enviar/receber.	,
`disconnected`	Desconectado (transient, geralmente reconecta sozinho).	,
`logged_out`	Sessão invalidada (precisa novo `connect`).	`reason`
`stream_replaced`	Outra sessão tomou o lugar (multi-device conflict).	,
`temp_banned`	Ban temporário aplicado pelo WhatsApp.	`expireAt`, `expireInSeconds`, `reason`
`client_outdated`	Versão do WhatsApp Web em uso está obsoleta, entre em contato com o suporte.	`message`
`connect_failure`	Falha durante conexão.	`reason`, `reasonCode`
`stream_error`	Erro de stream do WhatsApp.	`errorMsg`
`cat_refresh_error`	Falha ao renovar credenciais (`cat`).	`errorMsg`
`qr_ready`	Novo QR disponível para pareamento.	`codes[]`, `onConnect`
`pair_success`	Pareamento concluído.	`jid`, `platform`
`pair_error`	Erro durante o pareamento.	`errorMsg`
`qr_scanned_no_multidevice`	QR escaneado mas o device-alvo não tem multidevice.	,
`keepalive_timeout`	Conexão instável, keepalive não respondido.	,
`keepalive_restored`	Conexão estabilizou após `keepalive_timeout`.	,
`manual_reconnect`	Reconexão disparada manualmente via REST.	,

Para o seu cliente saber quando recarregar o QR na UI, escute instance.state com state=qr_ready e renderize data.codes[0].

`label.update`

Edição/associação de etiquetas (WhatsApp Business labels).

Payload

{
  "type":   "edit | chat | message",
  "labelId": "1",
  "timestamp": "2026-04-28T10:00:00Z",
  "action": "updated | deleted | add | remove",

  // type=edit:
  "name": "Important",
  "color": 0,
  "labelType": "CUSTOM",
  "isActive": true,
  "isImmutable": false,
  "orderIndex": 1,
  "deleted": false,

  // type=chat:
  "chatJid": "5511999999999@s.whatsapp.net",
  "labeled": true,

  // type=message:
  "messageId": "wamid.abc"
}

Combinações `type` × `action`

`type`	`action` válida	Campos extras
`edit`	`updated`, `deleted`	`name`, `color`, `labelType`, `isActive`, `isImmutable`, `orderIndex`, `deleted`
`chat`	`add`, `remove`	`chatJid`, `labeled`
`message`	`add`, `remove`	`chatJid`, `messageId`

Eventos não emitidos (internos)

Capturados pelo handler whatsmeow mas não propagados via webhook/WS:

*events.Picture, mudança de foto de perfil (apenas logado).
*events.FBMessage, Facebook Business (apenas logado).
*events.HistorySync, sync de histórico (processado e gravado em DB).

Se você precisar consumir alguma dessas mudanças, faça polling pelos endpoints REST correspondentes (perfil, histórico).

Referências

Configurar webhook

Filtre os eventos via events[] na config.

Configurar WebSocket

Mesma sintaxe de filtro do webhook.

Conectar via WebSocket

Receba os eventos em tempo real.

Visão geral de Eventos

Comparação webhook x WebSocket.

​Envelope

​Filtragem e roteamento

​message.exchange

​Payload

​Campos condicionais

​adOrigin — atribuição de origem (Click-to-WhatsApp)

​Exemplo (recebimento de imagem)

​message.status

​Payload

​Enum status

​call.update

​Payload

​Enum type

​group.flow

​Payload, participant change

​Subtipos de metadata

​instance.state

​Payload

​Enum state

​label.update

​Payload

​Combinações type × action

​Eventos não emitidos (internos)

​Referências

Configurar webhook

Configurar WebSocket

Conectar via WebSocket

Visão geral de Eventos

Envelope

Filtragem e roteamento

`message.exchange`

Payload

Campos condicionais

`adOrigin` — atribuição de origem (Click-to-WhatsApp)

Exemplo (recebimento de imagem)

`message.status`

Payload

Enum `status`

`call.update`

Payload

Enum `type`

`group.flow`

Payload, participant change

Subtipos de metadata

`instance.state`

Payload

Enum `state`

`label.update`

Payload

Combinações `type` × `action`

Eventos não emitidos (internos)

Referências