Webhooks

15. Webhooks#

Webhooks permitem receber eventos em tempo real via HTTP POST no seu servidor.

Semantica de entrega: pelo menos uma vez (at-least-once). Retries do worker, falhas de rede ou retry manual podem gerar o mesmo event_id mais de uma vez. O endpoint do cliente deve ser idempotente e deduplicar por event_id (ou pelo par webhook_id + event_id).

Ordem em relação ao banco (tenant): para message.delivered, message.read, message.played, message.deleted e message.edited, o Catcher aplica primeiro o UPDATE na tabela messages do tenant e em seguida enfileira/dispara webhooks e streams em tempo real — o estado persistido não fica atrás do envio do evento HTTP.

Flag international (todos os eventos com phone): todo evento que carrega um phone inclui também "international": true|false — true quando o número é de outro país (código de país ≠ 55; ex.: EUA +1, Reino Unido +44), false quando é brasileiro ou desconhecido/vazio. O flag é derivado do número na origem (Catcher), então o consumidor não precisa adivinhar o país nem fabricar um prefixo 55. O número em phone é entregue exatamente como recebido — o flag apenas é adicionado, nunca modifica o número. Exemplo: { "phone": "17819578651", "international": true } (EUA); { "phone": "554199887766", "international": false } (BR).

POST/v1/webhooks#

Cria um novo webhook.

Auth: Owner, Admin

Request:

json
{
  "url": "https://meuservidor.com/webhook",
  "instance_id": "84c2e480-...",
  "events": "message.received,message.sent",
  "secret": "whsec_minha_chave_compartilhada",
  "active": true,
  "allowed_destination_ips": "203.0.113.10,2001:db8::/32"
}
Campo Tipo Obrigatório Descricao
url string sim URL do seu endpoint (https:// por padrão)
instance_id string não ID da instância para filtrar. Vazio/omitido = global (recebe de todas as instâncias da empresa)
events string sim Eventos filtrados (separados por virgula). * = todos
secret string não Secret customizado. Se omitido, a API gera um automaticamente
active boolean não Default true. Envie false para criar o webhook pausado.
allowed_destination_ips string não Allowlist separada por virgula de IPv4/IPv6/CIDR para defesa contra DNS rebinding. Vazio/omitido = sem restrição.
simulator boolean não Default false. Quando true, o servidor gera um token (UUID v7) + a URL de ingestão interna ({API_PUBLIC_URL}/v1/sim/{token}) e ignora url. Veja a seção Simulador de webhooks.

Escopo do webhook — por instância vs global:

  • Por instância: defina instance_id para receber eventos apenas daquela instância. Recomendado quando cada instância envia para um backend diferente.
  • Global: omita instance_id (ou envie vazio) para receber eventos de todas as instâncias da empresa no mesmo endpoint.
  • Cuidado com duplicacao: se você criar um webhook global E um por instância apontando para o mesmo URL, os eventos daquela instância serao entregues duas vezes (uma por cada webhook). Prefira um ou outro.

Nomenclatura por tipo de conteúdo (<kind>.<action>): os 9 eventos genéricos de ciclo de vida de mensagem — message.received, message.sent, message.delivered, message.read, message.played, message.deleted, message.edited, message.delivery_failed, message.acked — podem, quando a plataforma habilita o modo específico, chegar com o tipo de conteúdo no nome do evento: audio.sent, text.received, document.delivered, reaction.deleted, etc. O kind é o mesmo valor de message_type no payload (text, image, video, audio, document, sticker, location, contact, reaction, poll, template, interactive, ptv, gif, event, link_preview, status_text, status_image, status_video, status_audio, album, live_location, list, group_invite, button_reply, list_reply, interactive_reply, pin_chat, unpin_chat, poll_vote, product, order, view_once, unsupported).

O nome da família é canônico entre os 3 providers (whatsmeow, wwebjs e Meta Cloud oficial): o mesmo gesto do usuário gera o mesmo message_type e o mesmo nome de evento em qualquer canal. Toques em botão de template chegam como button_reply (nunca o vocabulário cru do provider — button, buttons_response, template_button_reply), escolha em lista como list_reply (nunca list_response), resposta de native flow como interactive_reply, convite de grupo como group_invite. Um message_type raro fora do catálogo permanece no evento genérico message.<action> — a plataforma nunca inventa nome de evento.

Você não precisa migrar sua assinatura: uma assinatura ao evento genérico message.<action> cobre automaticamente todas as formas específicas <kind>.<action> correspondentes (assinar message.sent continua entregando audio.sent, text.sent, …). Para receber só um tipo, assine o nome específico diretamente (audio.sent). O envelope, a assinatura HMAC e o data (que sempre carrega message_type) permanecem idênticos — só o type de topo muda. Domínios como status.received/call.received não são afetados.

Um fato, um evento (desde 2026-08-02). Os antigos eventos dedicados message.reaction_received, message.pinned, message.unpinned, message.poll_vote_received, message.product_received, message.order_received e message.interactive_reply_received foram APOSENTADOS — eles duplicavam o evento de ciclo de vida para o mesmo fato. Cada inbound emite agora um único message.received (reaction.received, pin_chat.received, poll_vote.received, product.received, order.received, button_reply.received… sob o dialeto específico), que carrega:

  • target_from_me achatado no topo (a mensagem alvo é sua? — vale pra reaction, pin e enquete);
  • reaction: tudo no topo, sem detail — content = emoji ("" = reação removida), reaction_target_id = UUID Catcher da mensagem reagida;
  • demais famílias: a estrutura específica vem no campo detail (poll_message_id/poll_from_me no voto; target_message_id no pin; produto/pedido/reply interativo com seus campos próprios — as mesmas formas dos antigos dedicados, então o parser que você tinha funciona igualzinho em data.detail).

message_ids continua canônico: é o UUID da linha persistida, ou [] quando o fato não vira linha (reaction do canal oficial, voto de enquete). Vale para os três providers (whatsmeow, wwebjs e Meta Cloud oficial) e para o canal Instagram. Assinaturas antigas aos nomes dedicados simplesmente não recebem mais nada — assine message.received (cobre todas as formas) ou o nome específico (reaction.received).

Eventos disponíveis:

events: "*" cobre tudo, EXCETO os eventos de alto volume marcados como opt-in. Hoje são dois: presence.update (digitando/online) e status.received (um contato postou status). Sozinhos eles são ~41% de tudo que a API emite, então entregá-los por padrão faria toda integração pagar por sinal que não pediu — e enterraria os eventos que exigem ação. Eles continuam mapeados, gravados e disponíveis: para recebê-los, cite o nome explicitamente na lista de events (ex.: "message.received,presence.update"). Eventos novos que a Catcher passe a emitir entram no * normalmente; só a lista de opt-in é exceção, e mudanças nela vão no CHANGELOG.

Evento Descricao Persistido
message.received Mensagem recebida Sim (tabela messages)
message.sent Mensagem enviada com sucesso Sim (tabela messages)
message.delivered Mensagem entregue (double check) Sim (atualiza delivered_at)
message.read Mensagem lida (blue check) Sim (atualiza read_at)
message.played Mídia visualizar-uma-vez aberta Sim (atualiza played_at)
message.deleted Mensagem apagada/revogada Sim (atualiza status=deleted)
message.edited Mensagem editada Sim (atualiza content)
message.undecryptable Mensagem recebida mas não pode ser decriptada whatsmeow: persiste uma linha placeholder (reusada no message.received recuperado, carrega o UUID Catcher); wwebjs: só evento operacional, sem linha
message.decrypt_recovered Mensagem antes indecriptável recuperada após retry Não cria linha extra em messages; salvo como evento operacional
message.decrypt_lost Mensagem indecriptável expirada sem recuperação Não cria linha em messages; salvo como evento operacional
message.starred Mensagem marcada/desmarcada com estrela Não
message.deleted_for_me Mensagem apagada localmente (apenas para mim) Não
message.interactive_reply_sent Eco outbound de clique em botão, lista ou native-flow interativo feito pela instância/outro dispositivo Não cria linha extra; acompanha o message.sent genérico
call.received Chamada recebida (ou, com direction:"outbound", chamada que a instância discou) Sim (tabela call_logs)
call.accepted Chamada aceita pela parte remota — OU (VoIP manual) a instância atendeu via POST .../calls/{callID}/answer Sim (tabela call_logs)
call.rejected Chamada rejeitada pela parte remota (caller-side) — OU (VoIP manual) a instância rejeitou via POST .../calls/{callID}/reject Sim (tabela call_logs)
call.declined_by_me Você (instância) recusou uma chamada de entrada (UI do telefone ou auto-rejeição) Não cria nova linha — atualiza call_logs.end_reason via call.ended
call.ended Chamada finalizada (qualquer motivo: timeout, hangup, rejeição) Sim (tabela call_logs)
call.group_offer Chamada em grupo recebida Sim (tabela call_logs)
connection.update Mudanca de status da conexão Sim (tabela instances)
presence.update Presença ou digitacao de contato Não em MySQL; snapshot opcional em Redis quando o contato está monitorado
group.update Mudanca em grupo Sim (tabela group_events)
group.joined Instância foi adicionada a um grupo Sim (tabela group_events)
contact.update Mudanca de contato (foto, nome, etc.) Sim (tabela contact_events)
contact.identity_changed Contato trocou dispositivo principal Sim (tabela contact_events)
contact.sync Contato sincronizado do dispositivo Sim (tabela contact_events)
instance.banned Instância recebeu ban do WhatsApp Sim (atualiza ban_expiry e ban_reason na instância)
instance.offline Instância desconectada ha 15min ou mais (transicao única, não re-fira) Sim (campo offline_alert_level=warning na instância)
instance.critical_offline Instância desconectada ha 6h ou mais; também dispara email para o owner + superadmins Sim (campo offline_alert_level=critical na instância)
instance.recovered Instância voltou a conectar após ter ficado offline/critical_offline Sim (limpa offline_alert_level)
blocklist.update Lista de bloqueados alterada Não
chat.pin Chat fixado/desfixado Não
chat.archive Chat arquivado/desarquivado Não
chat.mute Chat silenciado/dessilenciado Não
chat.read_state Chat marcado como lido/não lido Não
chat.clear Chat limpo Não
chat.delete Chat apagado Não
chat.disappearing_timer WhatsApp sinalizou alteração do timer de mensagens temporárias de um chat Não
settings.unarchive_chats Configuração global "manter chats arquivados" alterada em outro dispositivo Não
chat.archive_sent A instância arquivou/desarquivou um chat via API Não
chat.pin_sent A instância fixou/desfixou um chat via API Não
chat.mute_sent A instância silenciou/dessilenciou um chat via API Não
chat.unread_sent A instância marcou um chat como não lido via API Não
chat.disappearing_timer_sent A instância alterou o timer de mensagens temporárias via API Não
chat.clear_sent A instância limpou mensagens de um chat via API Não
chat.delete_sent A instância removeu um chat da lista via API Não
privacy.update Configurações de privacidade alteradas Não
history.sync Sincronização de histórico recebida Não
history.import_started Importação manual/automática de histórico começou Não
history.import_skipped Importação de histórico foi pulada por falta de âncora ou falha total Não
history.import_completed Pedido de importação de histórico foi concluído Não
sync.preview Preview de sincronização offline Não
sync.app_state_error Falha de AppState sync reportada pelo whatsmeow Não
sync.offline_completed Janela offline absorvida após reconexão Não
media.retry_result Resultado de retry de mídia Não
label.edit Etiqueta criada/editada/removida Não
label.chat_association Chat etiquetado/desetiquetado Não
label.message_association Mensagem etiquetada/desetiquetada Não
message.acked Outro dispositivo SEU confirmou recebimento de uma mensagem que você enviou (sync multi-device; distinto de message.delivered, que e o contato) Não
message.read_other_device Você leu uma mensagem inbound em outro dispositivo seu Não
message.pin_sent A instância fixou/desfixou uma mensagem via API Não
message.poll_vote_sent A instância votou/limpou voto em enquete via API Não
message.star_sent A instância favoritou/desfavoritou uma mensagem via API Não
message.read_sent A instância marcou mensagem(ns) como lida(s) via API Não
message.decrypt_retry_pending Retry de decriptação ainda pendente Não
message.delivery_failed Envio falhou de forma terminal Sim (outbound_request marcado como failed)
media.moderation_blocked Mídia outbound bloqueada pela moderação da Meta (Kaleidoscope) — entregue mas não reproduzível Sim (messages.moderation_status/score) — provider wwebjs
status.received Status/story de um contato recebido Sim (feed de status)
status.viewed Contato visualizou um status seu Sim (views do status)
status.reaction Contato reagiu a um status seu Não
status.reply Contato respondeu/comentou um status seu Não
status.reply_sent A instância respondeu/comentou o status de um contato via API Não
contact.block_sent A instância bloqueou um contato via API Não
contact.saved_sent A instância salvou ou renomeou um contato na agenda do WhatsApp via API (wwebjs) Não
contact.deleted_sent A instância apagou um contato da agenda do WhatsApp via API (wwebjs) Não
sticker.favorite_sent A instância adicionou/removeu uma figurinha das favoritas via API (wwebjs) Não
quick_reply.saved_sent A instância criou ou editou uma resposta rápida do WhatsApp Business via API (wwebjs) Não
quick_reply.deleted_sent A instância apagou uma resposta rápida do WhatsApp Business via API (wwebjs) Não
contact.unblock_sent A instância desbloqueou um contato via API Não
contact.presence_subscribed A instância assinou presença de um contato via API Não
contact.temperature_changed Temperatura anti-spam do contato mudou de tier Sim (contadores de temperatura)
contacts.bulk_imported Roster de contatos absorvido em massa (após pareamento novo) Não
presence.broadcast_sent A instância publicou presença própria via API Não
profile.name_changed_sent A instância alterou o nome do perfil via API Não
profile.picture_changed_sent A instância alterou a foto do perfil via API Não
group.create_sent A instância criou grupo via API Não
group.name_changed_sent A instância alterou nome de grupo via API Não
group.description_changed_sent A instância alterou descrição de grupo via API Não
group.picture_changed_sent A instância alterou foto de grupo via API Não
group.participants_add_sent A instância adicionou participantes via API Não
group.participants_remove_sent A instância removeu participantes via API Não
group.participants_promote_sent A instância promoveu participantes via API Não
group.participants_demote_sent A instância rebaixou participantes via API Não
group.participants_approved_sent A instância aprovou solicitações de entrada via API Não
group.participants_rejected_sent A instância rejeitou solicitações de entrada via API Não
group.settings_sent A instância alterou configurações de grupo via API Não
group.invite_link_revoked_sent A instância revogou link de convite via API Não
group.join_sent A instância entrou em grupo via link via API Não
group.leave_sent A instância saiu de grupo via API Não
connection.diagnostic Timeline fina do ciclo de conexão (dialing, qr emitido, ws fechado, etc.) — usado pela modal de QR Não
connection.recovered_quick Connected logo após um Disconnected (<~60s); ruido de estabilidade, distinto de instance.recovered Não
instance.deleted Instância removida via API/admin Sim (linha removida)
instance.no_proxy_blocked Conexão recusada porque a instância exigia proxy e não tinha IP válido Não
instance.no_proxy_available Instância NÃO-pareada sem IP saudável pra parear — a plataforma vai auto-provisionar um IP novo validado e re-tentar o connect (não-terminal; desired_state permanece connected) Não
instance.qr_scanned QR code foi lido antes da conexão completar Não
instance.proxy_changed IP de proxy dedicado da instância foi trocado Sim (vínculo da instância)
instance.provider_changed Instância migrada para outro provider (POST .../migrate-provider) Não
session.recreated Sessão Signal de um peer foi recriada para recuperar decriptação Não
anti_spam.blocked Envio bloqueado pelo guard anti-spam antes de enfileirar Não
whatsapp.policy_warning Sinal/aviso de política recebido do WhatsApp Não
account.restricted WhatsApp restringiu a CONTA (reachout timelock) — traz o tipo de restrição e a data/hora EXATA em que ela termina Não
account.restriction_cleared A janela de restrição da conta terminou Não
instance.send_locked A trava por conta travou os envios iniciados por nós (rajada com cara de acidente) ou um operador travou à mão. Respostas em conversa aberta seguem Não
instance.send_unlocked Um operador destravou; os envios segurados voltam a sair (ou foram descartados) Não
send.paced Envio iniciado por nós aceito (202) mas segurado pela cota da conta; sai sozinho quando a janela abre Não
send.outbox_stuck Instância com envios travados: attempts>=3 (loop de retry) ou parados em pending há mais de 10min sem sair (fila congelada/segurada — não incrementa attempts, então só a idade denuncia) Não
send.outbox_recovered A fila que disparou o send.outbox_stuck voltou a andar (all-clear). Emitido uma vez por episódio, no MESMO ponto em que o alerta é limpo Não
wwebjs.bundle_changed Versão do bundle do WA Web mudou numa instância wwebjs — validar a fork antes que o cliente sinta Não
wwebjs.contract_drift Uma superfície de runtime wwebjs bateu numa forma que não reconhece (id-less, sendMessage undefined, etc.). data.surface diz qual: além das antigas, signature (uma função do WA Web que chamamos mudou de forma entre bundles — detail traz send_breaking/other_breaking), signature_hold_expired (envios retidos liberados pelo teto), event_shape (um evento cru perdeu um campo que sempre tinha ou trocou o tipo), event_shape_added (campos novos, agregados por minuto) e event_shape_hold_expired (eventos retidos liberados pelo teto) Não
wwebjs.contract_suspect Self-check pós-ready achou ≥30% dos primeiros eventos malformados (provável bundle novo) Não
wwebjs.canary_result Canário ativo (Fase 6, WWEBJS_CANARY_SEND=on): após mudança de bundle, enviou 1 mensagem de contrato e reporta se o send gerou waId válido (ok=false ⇒ o bundle novo provavelmente quebrou o envio). Env-gated OFF por padrão; WWEBJS_CANARY_TO = destinatário de teste (nunca hardcoded); WWEBJS_CANARY_MIN_INTERVAL_MS = rate-limit (default 1h) Não
* Todos os eventos —

Assinaturas legadas em events continuam aceitas e são normalizadas para os eventos canônicos: message.receive/message.incoming -> message.received, message.updated -> message.edited, message.reaction -> reaction.received, message.revoke -> message.deleted, message.failed -> message.delivery_failed, message.ack/message.receipt/message.status -> ciclo de ack/delivery/read/played, connection.connected/connection.disconnected -> connection.update, qr.update -> connection.diagnostic.

Resposta 201:

json
{
  "id": 1,
  "company_id": 10,
  "instance_id": "84c2e480-...",
  "url": "https://meuservidor.com/webhook",
  "secret": "a1b2c3d4e5f6...64_hex_chars",
  "events": "message.received,message.sent",
  "active": true,
  "allowed_destination_ips": "203.0.113.10,2001:db8::/32",
  "created_at": "2026-03-07T10:00:00Z",
  "updated_at": "2026-03-07T10:00:00Z"
}

O secret e gerado automaticamente e usado para assinar os payloads via HMAC-SHA256. A URL e validada no cadastro/edicao e revalidada no momento da entrega; destinos internos ou resolvidos para rede privada são rejeitados. O secret aparece somente na resposta de criação. GET, LIST e PATCH nunca o reexibem. A entrega e https only por padrão. Em runtime você pode afrouxar isso com WEBHOOK_ALLOW_INSECURE_HTTP=true ou restringir dominios com WEBHOOK_ALLOWED_DOMAINS / WEBHOOK_BLOCKED_DOMAINS.

Email verificado obrigatório: o cadastro de webhook exige que a conta já tenha confirmado o email — uma conta recem-criada e ainda não verificada recebe 403.

Respostas de erro:

Status error_code Quando
400 INVALID_JSON Corpo não e JSON válido
400 BAD_REQUEST url ou events ausente; events com mais de 1024 caracteres; secret informado com menos de 16 caracteres; ou allowed_destination_ips inválido
400 WEBHOOK_URL_INVALID URL inválida — HTTP em produção, scheme não suportado, mais de 2048 caracteres ou destino que resolve para rede privada (SSRF)
403 FORBIDDEN Limite de webhooks do plano atingido
404 INSTANCE_NOT_FOUND instance_id informado não corresponde a nenhuma instância da empresa
409 CONFLICT Já existe um webhook para a mesma empresa + instância + URL

GET/v1/webhooks#

Lista todos os webhooks da empresa.

Auth: Owner, Admin

Query Parameters:

Parametro Tipo Padrão Descricao
instance_id string — Filtra webhooks dessa instância. Para tenants, retorna webhooks da própria empresa com instance_id igual ao informado OU globais. Para superadmin, faz lookup cross-company apenas por instance_id.

Resposta 200:

json
[
  {
    "id": 1,
    "company_id": 10,
    "instance_id": "84c2e480-...",
    "url": "https://meuservidor.com/webhook",
    "events": "message.received,message.sent",
    "active": true,
    "allowed_destination_ips": "",
    "created_at": "2026-03-07T10:00:00Z",
    "updated_at": "2026-03-07T10:00:00Z"
  }
]

GET/v1/webhooks/{webhookId}#

Retorna detalhes de um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Resposta 200: Objeto webhook sem o campo secret.


PATCH/v1/webhooks/{webhookId}#

Atualiza um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Request:

json
{
  "url": "https://novo-servidor.com/webhook",
  "events": "*",
  "active": false,
  "secret": "whsec_rotacionado_manual",
  "allowed_destination_ips": ""
}

Todos os campos são opcionais. Em allowed_destination_ips, campo omitido preserva o valor atual; string vazia limpa a allowlist; valor não vazio substitui após validação.

Resposta 200: Objeto webhook atualizado sem o campo secret.


DELETE/v1/webhooks/{webhookId}#

Remove um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Resposta 204: Sem corpo.


GET/v1/webhooks/{webhookId}/logs#

Lista logs de entrega do webhook.

Retencao e privacidade: registros de entrega com sucesso são removidos após 7 dias; falhas permanecem 14 dias (tarefa periodica webhook:cleanup_logs). Em cada execução, linhas com mais de 48 horas passam por redacao: o campo payload da API vira um JSON enxuto com event_type, event_id e redacted: true; copia completa do corpo enviado ao cliente e apagada no armazenamento interno; respostas HTTP muito longas são truncadas. Novas linhas já gravam em payload apenas metadados (tipo, id, tamanho do JSON). O retry manual depende dessa copia original: quando payload_raw já tiver sido limpo, o reenvio não e mais permitido.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Query Parameters:

Parametro Tipo Padrão Descricao
page int 1 Página
limit int 50 Itens por página (max 100)

Resposta 200:

json
{
  "data": [
    {
      "id": 1,
      "webhook_id": 1,
      "event_id": "evt-abc-123",
      "event_type": "message.received",
      "payload": "{...}",
      "status_code": 200,
      "response": "OK",
      "success": true,
      "attempt": 1,
      "error_class": "",
      "created_at": "2026-03-07T12:00:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 50
}

Erro 404 (WEBHOOK_NOT_FOUND): webhook inexistente ou de outra empresa.


POST/v1/webhooks/{webhookId}/logs/{logId}/retry#

Reenvia um evento que falhou.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds) Regras: so aceita logs com success=false e com payload_raw ainda preservado. Logs já entregues com sucesso ou já redatados retornam 409 Conflict.

Resposta 202:

json
{
  "status": "retrying",
  "event_id": "evt_xxxx"
}

GET/v1/webhooks/queue — Fila de entrega ordenada (autoatendimento)#

A entrega de eventos é estritamente ordenada por webhook: um loop serial percorre o outbox por cursor e só avança quando o evento corrente é aceito (2xx). Consequência: um evento que o SEU endpoint rejeita de forma determinística (4xx de parse, validação, etc.) segura TODOS os eventos posteriores daquele webhook. Este grupo de endpoints dá ao consumidor controle total da própria fila: ver o estado, listar os eventos pendentes (com os ids), buscar qualquer evento individualmente, ler o erro do evento que está travando, e destravar descartando o evento travado (ou um range).

Retorna o estado da fila de TODOS os webhooks da sua company.

Auth: Owner, Admin Escopo: somente webhooks da company autenticada.

Resposta 200:

json
{
  "summary": {
    "total_webhooks": 3,
    "active": 3,
    "blocked": 1,
    "draining": 0,
    "idle": 2,
    "total_pending": 140,
    "oldest_lag_seconds": 8760
  },
  "webhooks": [
    {
      "id": 5,
      "company_id": 2,
      "instance_id": "9ff50fa4-...",
      "instance_name": "Catcher 3",
      "url": "https://seu-sistema.com/webhook",
      "events": "message.received,message.sent,...",
      "active": true,
      "simulator": false,
      "cursor_event_log_id": 3199,
      "head_event_log_id": 4524,
      "pending_count": 140,
      "pending_capped": false,
      "state": "blocked",
      "lag_seconds": 8760,
      "blocked_event": {
        "event_log_id": 3200,
        "event_id": "61b9a2b8-...",
        "event_type": "connection.update",
        "instance_id": "9ff50fa4-...",
        "emitted_at": "2026-06-12T14:33:14-03:00",
        "payload_size": 54,
        "attempts": 67,
        "last_status_code": 401,
        "last_error_class": "permanent_4xx",
        "last_response": "{\"error\":\"Assinatura inválida\"}",
        "first_attempt_at": "2026-06-12T14:33:14-03:00",
        "last_attempt_at": "2026-06-12T18:55:01-03:00"
      }
    }
  ]
}
Campo Significado
state blocked (o próximo evento tem tentativas falhas e nenhum sucesso — o retry eterno está preso nele), draining (atrasado, entregando em ordem), idle (em dia), inactive (webhook desativado)
cursor_event_log_id / head_event_log_id posição do cursor de entrega vs o último evento do outbox
pending_count eventos após o cursor que casam com a sua assinatura (instância + event types). pending_capped=true = contagem é um piso (varredura limitada a 2.000 rows)
lag_seconds idade do evento pendente mais antigo
blocked_event presente só em state=blocked; last_response é o body cru que o SEU endpoint respondeu (truncado em 2 KB)

GET/v1/webhooks/{webhookId}/queue/events#

A fila literal de um webhook: lista os eventos pendentes atrás do cursor, na ordem exata em que serão entregues. A primeira row é o evento em que o cursor parou — quando travado, ela carrega a própria evidência da falha inline.

Auth: Owner, Admin (webhook precisa pertencer à sua company — 404 caso contrário)

Query Parameters:

Parametro Tipo Padrão Descricao
limit int 50 Máximo de eventos retornados (cap 200)

Resposta 200:

json
{
  "webhook_id": 5,
  "cursor_event_log_id": 3199,
  "total": 140,
  "total_capped": false,
  "events": [
    {
      "event_log_id": 3200,
      "event_id": "61b9a2b8-...",
      "event_type": "connection.update",
      "instance_id": "9ff50fa4-...",
      "emitted_at": "2026-06-12T14:33:14-03:00",
      "payload_size": 54,
      "blocking": true,
      "attempts": 67,
      "last_status_code": 401,
      "last_error_class": "permanent_4xx",
      "last_response": "{\"error\":\"Assinatura inválida\"}"
    },
    {
      "event_log_id": 3201,
      "event_id": "05ff8713-...",
      "event_type": "connection.diagnostic",
      "instance_id": "9ff50fa4-...",
      "emitted_at": "2026-06-12T14:33:14-03:00",
      "payload_size": 177,
      "blocking": false
    }
  ]
}

Os campos de erro (attempts, last_status_code, last_error_class, last_response) são omitempty e aparecem APENAS na row bloqueante. Use o event_log_id de cada row para buscar o evento individual (abaixo) ou como alvo do discard.


GET/v1/webhooks/{webhookId}/queue/events/{eventLogId}#

Busca UM evento da fila individualmente — o envelope completo, incluindo o data parseado (o mesmo payload que seria entregue no POST do webhook).

Auth: Owner, Admin (webhook da sua company)

Resposta 200:

json
{
  "event_log_id": 3200,
  "event_id": "61b9a2b8-...",
  "event_type": "connection.update",
  "instance_id": "9ff50fa4-...",
  "emitted_at": "2026-06-12T14:33:14-03:00",
  "payload_size": 54,
  "pending": true,
  "matches_subscription": true,
  "event": {
    "event_id": "61b9a2b8-...",
    "type": "connection.update",
    "instance_id": "9ff50fa4-...",
    "timestamp": "2026-06-12T14:33:14-03:00",
    "data": { "status": "connected" }
  }
}
Campo Significado
pending true quando a row ainda está à frente do cursor (vai ser entregue/descartada)
matches_subscription true quando o evento casa com a assinatura deste webhook (instância + event types) — rows que não casam avançam silenciosamente sem entrega

POST/v1/webhooks/{webhookId}/queue/discard — Destravar a fila#

A válvula de destravamento self-service. Arma o descarte em range: o dispatcher descarta — com delivery log auditado error_class=discarded_by_operator, SEM chamada HTTP — todo evento que casa com a assinatura até up_to_event_log_id (inclusive), avança o cursor e retoma a entrega do evento seguinte em diante.

  • Para descartar só o evento travado: up_to_event_log_id = o event_log_id do blocked_event.
  • Para descartar o travado e os próximos N: up_to_event_log_id = o event_log_id da última row que você quer dropar (pegue da lista de eventos).

Os eventos descartados permanecem em event_logs (histórico/GET .../events/history) — eles apenas não serão entregues a este webhook.

Auth: Owner, Admin (webhook da sua company)

Body:

json
{ "up_to_event_log_id": 3205 }

Validações:

Condição Resposta
up_to_event_log_id ≤ cursor atual 409 — a fila já passou desse ponto
up_to_event_log_id > head do outbox 422 — descartar eventos FUTUROS não é permitido

Resposta 202:

json
{
  "status": "armed",
  "webhook_id": 5,
  "up_to_event_log_id": 3205,
  "cursor_event_log_id": 3199,
  "note": "the dispatcher will record discarded_by_operator delivery rows for every matching event up to the given id and resume delivery past it"
}

Cada evento descartado gera uma row em GET /v1/webhooks/{id}/logs com error_class=discarded_by_operator — o descarte é auditável, nunca silencioso.


GET/v1/webhooks/stuck#

Lista entregas webhook falhadas que precisam de atenção, agregadas por event_id (uma linha por evento, com a contagem total de tentativas e a classe do erro).

Auth: Owner, Admin Escopo: somente webhooks da company autenticada.

Query params (todos opcionais):

Param Tipo Default Descricao
webhook_id int — Filtra por webhook especifico
instance_id string — Estreita para webhooks dessa instância OU webhooks globais (sem instance_id, que disparam para qualquer instância). Usado pela aba Webhooks da página de detalhe da instância.
event_type string — Filtra por tipo de evento (ex: message.received)
class string — Filtra por classe do erro: permanent_4xx, payload_rejected, transient_5xx, rate_limit, network, unknown
since RFC3339 now-24h Cutoff inferior
page int 1 Página
limit int 50 Itens por página (max 200)

Resposta 200:

json
{
  "data": [
    {
      "log_id": 123,
      "webhook_id": 7,
      "webhook_url": "https://app.exemplo.com/webhook",
      "event_id": "evt-abc-123",
      "event_type": "message.received",
      "status_code": 503,
      "response": "service unavailable",
      "attempts": 25,
      "error_class": "transient_5xx",
      "is_hard_failed": false,
      "has_payload_raw": true,
      "payload_raw_size": 7421,
      "payload_raw_json_valid": true,
      "created_at": "2026-04-08T15:30:45Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 50
}

is_hard_failed=true indica que o evento bateu em SkipRetry por ser uma classe hard-fail (permanent_4xx ou payload_rejected) após 3 tentativas — provavelmente um bug de configuração, contrato ou limite/parser do consumer. has_payload_raw=false indica que o payload_raw foi redatado ou nunca foi salvo, e não da pra reenviar via API. payload_raw_size / payload_raw_json_valid ajudam a separar erro de payload gerado pela Catcher de erro no consumer. Se payload_raw_json_valid=true e a resposta do consumer indica EOF/truncamento perto de 8KB, verifique limite de body parser no receiver.


POST/v1/webhooks/retry-bulk#

Re-enfileira em batch um conjunto de entregas falhadas. Aceita dois modos:

Modo 1 — explicito por log IDs:

json
{
  "log_ids": [123, 124, 125]
}

Modo 2 — por filtro:

json
{
  "webhook_id": 7,
  "event_type": "message.received",
  "class": "payload_rejected",
  "status_code": 400,
  "response_contains": "Unexpected end-of-input",
  "since": "2026-04-07T00:00:00Z",
  "dry_run": true
}

Auth: Owner, Admin Escopo: somente webhooks da company autenticada (logs de outros tenants são silenciosamente pulados). Limites: máximo de 500 retries por chamada. Eventos com payload_raw vazio são pulados. Re-enfileiramento e deduplicado por event_id.

Resposta 202:

json
{
  "matched": 8,
  "requeued": 7,
  "skipped": 1,
  "errors": ["log 199: payload unavailable"]
}

dry_run=true calcula matched/skipped com os mesmos filtros, mas não enfileira entregas; quando ativo, o response inclui "dry_run": true. Use status_code + response_contains para isolar incidentes como HTTP 400 de body parser sem reenviar todos os eventos do mesmo webhook.


Garantia de ordem de entrega (entrega ordenada)#

Desde 2026-06-11 a camada de entrega é ordenada — e desde 2026-06-12 esse é o ÚNICO modo de entrega (o modo paralelo legado foi removido após a validação de 100% de entrega em ordem em produção): cada webhook tem um dispatcher SERIAL próprio com cursor no banco sobre o outbox de eventos (event_logs).

Garantias da entrega ordenada:

  • Ordem estrita de emissão por webhook: os eventos são entregues um a um, na ordem em que foram emitidos (por instância, com tolerância de milissegundos). message.read/message.edited/message.delivered de uma mensagem nunca chegam antes do message.sent dela.
  • Nada se perde, nada é pulado automaticamente: qualquer falha (rede, 5xx, 429 e também 4xx) segura a fila e retenta o MESMO evento eternamente, com backoff progressivo (transiente 5s→5min; rejeição 4xx 1min→15min). Quando o consumer volta, recebe TUDO em ordem.
  • Zero duplicatas: um evento entregue com 2xx nunca é re-entregue (dedup estrutural na entrega).
  • Válvula manual: a única forma de a fila passar por cima de um evento é uma ação explícita do operador (POST /v1/admin/webhooks/{id}/skip-event), auditada e visível nos delivery logs como error_class=skipped_by_operator.
  • Latência visível: cada delivery log carrega event_emitted_at (timestamp de emissão do evento); created_at − event_emitted_at é a latência emissão→entrega, exposta no painel "Entrega de Webhooks" e na métrica biazap_webhook_delivery_latency_seconds. Um alerta dispara quando o evento mais antigo não-entregue de um webhook passa de 2 minutos.

Implicação para consumers: mantenha o endpoint rápido (responda 2xx e processe assíncrono) — um consumer lento atrasa a PRÓPRIA fila (ordem tem custo de serialização), mas nunca afeta outros webhooks.

Estrategia de retry e classificação de erros#

Quando uma entrega falha, o Catcher classifica o erro e aplica a estrategia de retry adequada. (No modo ordenado, a classificação continua valendo para o BACKOFF — mas nenhuma classe avança a fila automaticamente; o schedule abaixo descreve o modo legado asynq.)

Classe Códigos Estrategia
permanent_4xx 400, 401, 403, 404, 405, 410, 415, 422, 501 Hard-fail após 3 tentativas — vai pra DLQ. Quase sempre indica URL errada, secret expirado ou bug no parser do consumer. 405/415/501 significam que o endpoint não aceita o POST (método/content-type/handler ausente) — retry nunca resolve. Aparece como "Eventos travados" na UI com badge vermelho.
payload_rejected 400 com assinatura de body parser/limite/JSON truncado Hard-fail após 3 tentativas — separa payload rejeitado de 4xx comum. Tipico em consumers com limite de body baixo ou parser encerrando em Unexpected end-of-input. Use status_code + response_contains no retry para validar antes de reenfileirar.
rate_limit 408, 429 Retry pelo schedule completo.
transient_5xx 500-599 Retry pelo schedule completo.
network sem status (DNS, refused, timeout) Retry pelo schedule completo. Caso típico: consumer reiniciando.
unknown qualquer outro Retry pelo schedule completo.

Schedule de retry (default WEBHOOK_MAX_RETRY=30, configuravel por env):

text
n=1   → 5s
n=2   → 15s
n=3   → 30s
n=4   → 1min
n=5   → 2min
n=6   → 5min
n=7   → 10min
n=8   → 15min
n=9   → 30min
n>=10 → 1h (capped)

Janela total: ~22 horas. Cobre restart de serviço, manutenção planejada, picos de carga e blips de infraestrutura sem perder eventos.

Wake-up retry on success: quando uma entrega chega com sucesso a um webhook, o Catcher automaticamente re-enfileira todos os eventos falhados (excluindo classes hard-fail como permanent_4xx e payload_rejected) desse mesmo webhook nas últimas 24h. Isso acelera a recuperacao quando o consumer volta de um restart — você não precisa esperar o backoff exponencial drainar. Um Redis lock por webhook (60s TTL) evita thundering herd.

Persistencia de payload_raw: entregas falhadas mantem o payload original não redatado pelo periodo de retencao completo (14 dias), de modo que retry manual via UI ou via POST /v1/webhooks/retry-bulk continue funcionando para eventos antigos.

Compaction de thumbnail inline: quando o payload serializado passa de 8KB e contém data.jpeg_thumbnail, o task de webhook omite o base64 inline e adiciona jpeg_thumbnail_omitted=true + jpeg_thumbnail_size_bytes, mantendo media_id/metadados. A métrica biazap_webhook_payload_compacted_total{reason="jpeg_thumbnail"} conta esse caminho.


Simulador de webhooks#

O simulador permite testar webhooks sem precisar de um servidor próprio: a Catcher cria um endpoint público interno e seguro que recebe as entregas reais, e o Console mostra os eventos chegando em tempo real (histórico + ao vivo) com o JSON completo, headers, timestamp e validade do HMAC.

Crie um webhook simulador passando simulator: true em POST /v1/webhooks (veja a seção acima). O servidor gera o token (UUID v7) e a URL de ingestão; o webhook resultante tem is_simulator: true. A entrega usa o mesmo pipeline de sempre (worker → POST → retry → HMAC), validando o caminho real ponta a ponta.

POST /v1/sim/{token}#

Endpoint público, sem autenticação que recebe as entregas de um webhook simulador. Resolve o webhook pelo token (UUID v7 inguessável). É um sink: aceita qualquer POST, guarda corpo (até 256KB) + headers + IP de origem + se o HMAC bateu, e responde 204. Token desconhecido → 404. Não é chamado diretamente pelo integrador — o worker da Catcher entrega aqui.

GET /v1/webhooks/{webhookId}/sim/events#

Lista paginada dos eventos recebidos por um webhook simulador. Auth: Owner, Admin (escopo da empresa). Query: page, limit (default 50, max 100). Resposta: { data: SimEvent[], total, page, limit }, onde cada SimEvent tem event_type, method, headers (JSON string), body, body_size, source_ip, hmac_valid, received_at. Webhook não-simulador → 400.

GET /v1/webhooks/{webhookId}/sim/stream#

Stream SSE dos eventos recebidos em tempo real. Auth: header (Authorization / X-API-Key). Emite eventos nomeados sim.event com o SimEvent no data. Heartbeat a cada 15s.

DELETE /v1/webhooks/{webhookId}/sim/events#

Limpa o histórico de eventos recebidos de um webhook simulador. Auth: Owner, Admin (escopo da empresa). Responde 204.

Retenção: os eventos recebidos são guardados por 7 dias e limitados aos 1000 mais recentes por simulador (limpeza automática diária).


Verificação de assinatura HMAC#

Cada requisição webhook inclui X-Catcher-Timestamp e X-Catcher-Signature. A assinatura HMAC-SHA256 cobre a string timestamp + "." + raw_body, usando o secret do webhook.

Validação recomendada no receiver:

  • rejeite timestamps com skew maior que 5 minutos
  • use comparacao constant-time (hmac.compare_digest, crypto.timingSafeEqual, subtle.ConstantTimeCompare)
  • deduplicate por event_id porque a entrega e at-least-once

Headers enviados pelo Catcher:

text
Content-Type: application/json
User-Agent: Catcher-Webhook/1.0
X-Catcher-Timestamp: 1711035600
X-Catcher-Signature: sha256=<hmac_hex>

Validação (exemplo em Python):

python
import hmac
import hashlib
import time

def verify_signature(payload_body, secret, timestamp, signature_header):
    now = int(time.time())
    ts = int(timestamp)
    if abs(now - ts) > 300:
        return False
    signed = f"{timestamp}.".encode() + payload_body
    expected = "sha256=" + hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Validação (exemplo em Node.js):

javascript
const crypto = require('crypto');

function verifySignature(payloadBody, secret, timestamp, signatureHeader) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) {
    return false;
  }
  const signed = Buffer.concat([
    Buffer.from(`${timestamp}.`),
    Buffer.isBuffer(payloadBody) ? payloadBody : Buffer.from(payloadBody)
  ]);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signed)
    .digest('hex');
  if (expected.length !== signatureHeader.length) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Payloads dos eventos#

Todos os eventos seguem a estrutura base:

json
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "message.received",
  "instance_id": "84c2e480-...",
  "timestamp": "2026-03-07T15:30:45.123Z",
  "data": { ... }
}
Campo do envelope Tipo Observacoes
event_id string (UUID v4) Identificador único da entrega. Use para deduplicacao idempotente no receiver.
type string Nome do evento (message.received, connection.update, etc.). Este e o nome do campo — não e event.
instance_id string (UUID) A instância que originou o evento.
timestamp string (RFC3339) Quando o Catcher registrou o evento (não necessariamente quando o WhatsApp gerou).
data object Payload especifico do evento. Shape depende de type — veja os blocos abaixo.

Troubleshooting — se o seu consumer responde 400 Bad Request: "missing event fields" ou "malformed envelope", o parser do receiver está esperando uma chave de envelope com nome diferente do que o Catcher envia (tipicamente event em vez de type). A correção e no consumer: leia body.type (não body.event). Cheque também se o consumer usa express.raw() (ou equivalente) para preservar os bytes exatos do body — JSON.parse + JSON.stringify muda a ordem das chaves e quebra a verificação HMAC (veja seção anterior).

data.message_type é uniforme nos 9 eventos de ciclo de vida da mensagem (received, sent, delivered, read, played, deleted, edited, delivery_failed, acked) — em todos os providers (whatsmeow, wwebjs, meta_cloud). Ele carrega o kind do conteúdo (text, audio, image, contact, …). Em received/sent o campo legado type é preservado com o mesmo valor; nos demais só existe message_type.

Use message_type — e não o prefixo do nome do evento — para decidir o kind. Isso importa porque, com EVENT_NAMING=specific, um vCard vira contact.received / contact.sent, e contact é o único prefixo que é ao mesmo tempo domínio reservado de evento (contact.update) e kind de conteúdo. Um consumidor que desempata pelo nome classificaria o cartão de contato como evento de domínio e o descartaria; data.message_type: "contact" é o desempate autoritativo.

Exceção (não é gap): quando a mensagem referenciada não tem linha persistida no tenant (edit/delete de mensagem anterior à instância), tanto message_type quanto message_ids são omitidos — a mesma classe de status.received (status de um contato, não é mensagem nossa): sem linha, sem kind e sem UUID. message.undecryptable é provider-específico: no whatsmeow persiste uma linha placeholder e emite o UUID Catcher dela (reusado no message.received recuperado); só no wwebjs carrega o hex bruto (ver o carve-out da família de decriptacao mais abaixo).

Campos de mutualidade (is_mutual / mutuality_checked_at) — todos os eventos que carregam um phone também podem trazer is_mutual (bool) e mutuality_checked_at (string ISO-8601). is_mutual=true significa que o contato resolvido tem a instância salva na agenda dele (lido do cache contact_mutuality_cache, sem roundtrip extra com o Meta). Ambos são omitidos quando a resposta não está em cache — permite distinguir "não-mutuo" de "desconhecido".

message.received#

Disparado quando uma mensagem e recebida no WhatsApp. Persistido na tabela messages. Para mensagens de mídia (image, video, audio, document, sticker), o arquivo e baixado do WhatsApp, armazenado no S3 e um registro Media e criado. O campo media_id pode ser usado para baixar a mídia via GET /v1/instances/{instanceId}/media/{mediaId}. Mensagens de status@broadcast e ecos da própria instância (IsFromMe) não geram esse evento.

Quando a mensagem é uma resposta/reply do WhatsApp, os eventos inbound de conteúdo (message.received ou o nome específico equivalente, como text.received, image.received, audio.received, video.received, document.received, location.received e contact.received) carregam data.quoted_id com o UUID Catcher da mensagem citada. O campo histórico data.quoted_msg_id continua sendo enviado como alias com o mesmo valor para consumidores existentes. Os campos são omitidos quando não há quote ou quando a mensagem citada não existe no tenant DB. O ID hexadecimal do WhatsApp nunca é exposto: o worker extrai getQuotedMessage().id.id (wwebjs), ou _data.quotedMsg.id como fallback defensivo, e resolve esse ID para o UUID antes de persistir e emitir o evento. O caminho whatsmeow faz a mesma resolução a partir de ContextInfo.StanzaID.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "sender_lid": "216251804708983:34@lid",
  "chat_lid": "216251804708983@lid",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "type": "audio",
  "message_type": "audio",
  "content": "",
  "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mime_type": "audio/ogg; codecs=opus",
  "file_size": 34567,
  "duration": 15,
  "quoted_id": "d28b6749-0a5c-47bc-9c12-fd4537a5d149",
  "quoted_msg_id": "d28b6749-0a5c-47bc-9c12-fd4537a5d149",
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Joao Silva"
}

Exemplo de mensagem de grupo:

json
{
  "phone": "554199999999",
  "from": "554199999999@s.whatsapp.net",
  "chat": "120363025555555555@g.us",
  "message_ids": ["76089f45-b309-43eb-9f2b-198ce302aa28"],
  "type": "text",
  "content": "oi pessoal",
  "timestamp": 1741360245,
  "is_group": true,
  "push_name": "Joao Silva",
  "group_name": "Vendas 2026",
  "group_subject": "Time comercial"
}

Para grupos: chat e o JID do grupo (@g.us), from/phone/push_name identificam o participante que enviou, e group_name/group_subject descrevem o grupo. Veja Mensagens de Grupo para o padrão completo.

Exemplo com contexto de anuncio (Instagram/Facebook click-to-WhatsApp):

json
{
  "phone": "554188322497",
  "from": "554188322497@s.whatsapp.net",
  "chat": "554188322497@s.whatsapp.net",
  "message_ids": ["ACDFD74C4368A916E0FE"],
  "type": "text",
  "content": "Ola! Tenho interesse no tratamento com o iModel",
  "ad_context": {
    "source_type": "instagram",
    "source_app": "Instagram",
    "source_id": "ad-123",
    "title": "Tratamento iModel",
    "body": "Agende sua consulta agora",
    "media_type": "image",
    "ctwa_clid": "ARA...",
    "ref": "utm_campaign_xyz",
    "thumbnail_url": "https://media.catcher.one/biazap_abc/ads/thumbs/7a3b1c...d.jpg",
    "media_url": "https://media.catcher.one/biazap_abc/ads/media/91ef02...c.mp4"
  },
  "link_preview": {
    "url": "https://exemplo.com/produto/123",
    "title": "Produto X — Loja Exemplo",
    "description": "Descrição resolvida pelo cliente de quem enviou",
    "thumbnail_url": "https://media.catcher.one/biazap_abc/ads/linkpreview/5c9e...a.jpg"
  },
  "is_forwarded": false,
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Patricia"
}

Exemplo de contato compartilhado (type=contact):

json
{
  "phone": "554196332719",
  "from": "554196332719@s.whatsapp.net",
  "chat": "554196332719@s.whatsapp.net",
  "message_ids": ["b1e2c3d4-5678-90ab-cdef-1234567890ab"],
  "type": "contact",
  "content": "Amor",
  "contacts": [
    {
      "display_name": "Amor",
      "phones": ["5541988887777"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;Amor;;;\nFN:Amor\nTEL;type=CELL;type=VOICE;waid=5541988887777:+55 41 8888-7777\nEND:VCARD"
    }
  ],
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Adriano"
}

Compartilhar varios contatos de uma vez (ou enviar via POST .../messages/contact com contacts: [...]) produz um ContactsArrayMessage: o mesmo evento type=contact com uma entrada em contacts por contato.

Campo Tipo Descricao
phone string Número de telefone sem sufixo (ex: "554192464230"). Resolvido do registro de identidade quando o sender e um LID
from string JID do remetente (resolvido para phone JID quando possível)
chat string JID do chat (igual a from em DM, JID do grupo em grupo; resolvido para phone JID quando possível)
sender_lid string LID original do remetente, presente apenas quando o WhatsApp usou LID internamente. Util para correlação (ver seção 22)
chat_lid string LID original do chat, presente apenas quando o WhatsApp usou LID internamente
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado.
type string Tipo: text, image, video, audio, document, sticker, location, live_location, contact, reaction, poll, poll_vote, list, list_reply, group_invite, pin_chat, unpin_chat, product, order, ptv, event, button_reply, interactive_reply, view_once. (ptv = nota de vídeo redonda; event = evento do WhatsApp; *_reply = o contato tocou um botão / escolheu opção de lista / respondeu a uma mensagem interativa; template/buttons colapsam em button_reply.)
content string Texto, caption, ou emoji (para reactions). Para mídia (image, video, document…) é só a legenda que o remetente digitou — "" quando não há legenda; o nome do arquivo nunca vem aqui, vem em file_name. Para type=contact, e o nome de exibição do(s) contato(s) — use contacts para os dados estruturados
contacts []object Cartoes de contato compartilhados. Presente apenas quando type=contact. Um contato gera 1 entrada; varios contatos de uma vez geram 1 entrada por contato. Ver campos de cada item abaixo
media_url string URL da mídia (deprecado, use media_id)
media_id string ID da mídia para download via API (presente se mídia foi armazenada com sucesso)
mime_type string MIME type da mídia (ex: audio/ogg; codecs=opus, image/jpeg)
file_name string Nome original do arquivo, exatamente como o remetente enviou (extensão, espaços, acentos e parênteses preservados). Presente em todo documento e em qualquer mídia para a qual o WhatsApp informa um nome; vem mesmo quando o download dos bytes acontece depois. Ausente só quando o WhatsApp não informa nome (foto/áudio comuns)
file_size uint64 Tamanho do arquivo em bytes (do proto WhatsApp)
duration uint32 Duração em segundos (para audio e video)
quoted_id string Preferido. UUID Catcher (v4) da mensagem sendo respondida. Presente apenas em respostas/reply threading; omitido se a mensagem citada não estiver no tenant DB. Nunca é o hex do WhatsApp — correlacione com message_ids[0] de eventos anteriores.
quoted_msg_id string Alias histórico de quoted_id, com exatamente o mesmo UUID Catcher e as mesmas regras de presença. Mantido para compatibilidade com consumidores existentes.
reaction_target_id string UUID Catcher (v4) da mensagem que recebeu a reaction (apenas para type=reaction). Vazio se o alvo não estiver no tenant DB. A resolução tolera a troca de JID individual @lid↔@s.whatsapp.net durante o retry de descriptografia.
ad_context object Contexto de anuncio do Instagram/Facebook (presente apenas quando a mensagem originou de um click-to-WhatsApp ad). Ver campos abaixo
link_preview object Cartão de link que o cliente do remetente anexou a uma mensagem de texto com URL. Presente apenas quando o WhatsApp casou uma URL no corpo. A riqueza varia com quem enviou: um celular costuma mandar só o domínio em title; o WhatsApp Web resolve título + descrição + thumbnail. Campos: url (sempre), title, description, thumbnail_url (opcionais — omitidos quando ausentes). thumbnail_url é sempre uma URL Catcher (o thumbnail chega inline no fio e é armazenado no R2) — nunca uma URL de CDN da Meta, e nunca base64 inline no payload.
is_animated bool true quando a figurinha é animada (inclui Lottie). Omitido quando false
is_gif bool true quando o vídeo foi enviado como GIF (loop, sem áudio). Omitido quando false
accessibility_label string Texto alternativo (alt-text) que o WhatsApp anexa à mídia para acessibilidade. Omitido quando ausente. É a descrição mais barata que um pipeline de IA consegue ler sem baixar os bytes
links []object URLs que o texto da mensagem contém, na ordem em que aparecem: [{"url": "https://…", "suspicious": true}]. No wwebjs é a detecção de links do próprio WhatsApp Web, incluindo a flag suspicious (domínio parecido/homógrafo — o aviso "link suspeito" do app); no whatsmeow as URLs são extraídas do texto e suspicious nunca aparece. Só texto (não captions). Omitido quando não há URL
association object Vínculo com a mensagem-mãe que agrupa esta: {"type": "media_album", "parent_whatsapp_id": "<hex>", "index": 2}. Hoje o caso real é o álbum — cada foto/vídeo de um post com várias mídias chega como sua própria image.received/video.received carregando a chave do cabeçalho do álbum (que não é persistido); agrupe pelo parent_whatsapp_id. index (posição no álbum) só no whatsmeow e só quando > 0 — o zero é omitido, então a primeira mídia chega sem index e a ordem de entrega é a referência segura. Outros tipos mantêm o nome do enum em snake_case (status_add_yours, sticker_annotation, …). Omitido fora de um vínculo
is_ai_sticker bool true quando a figurinha foi gerada pela Meta AI. Omitido quando false
sticker_premium int Status "premium" da figurinha (StickerMessage.premium / stickerPremiumStatus). Omitido quando 0
is_view_once bool Mídia de visualização única (isViewOnce da Meta). Provider wwebjs (desde 2026-10-28, promovido de extras); vem com o valor que a Meta mandou — false também é informação. Omitido quando a Meta não manda o campo
is_spoiler bool Conteúdo marcado como spoiler pelo remetente (isSpoiler da Meta). Provider wwebjs (desde 2026-10-28, promovido de extras); false vem explícito. Omitido quando a Meta não manda o campo
is_ephemeral bool Mensagem temporária (mensagens que desaparecem; isEphemeral da Meta). Provider wwebjs (desde 2026-10-29, promovido de extras); false vem explícito. Omitido quando a Meta não manda o campo
is_from_template bool Mensagem enviada a partir de um modelo de conta comercial (isFromTemplate da Meta). Provider wwebjs (desde 2026-10-29, promovido de extras); false vem explícito. Omitido quando a Meta não manda o campo
is_event_canceled bool Evento (mensagem de evento) cancelado por quem o criou (isEventCanceled da Meta). Provider wwebjs (desde 2026-10-29, promovido de extras); a Meta manda o campo em toda mensagem, então false é o normal. Omitido quando a Meta não manda o campo
disappearing_mode_initiator string Quem ligou as mensagens temporárias do chat, como a Meta classifica (ex.: "chat"; disappearingModeInitiator). Provider wwebjs (desde 2026-10-30, promovido de extras); só valores com forma de enum. Omitido quando a Meta não manda o campo
disappearing_mode_trigger string Como as mensagens temporárias foram ligadas (ex.: "chat_settings", "account_settings", "unknown"; disappearingModeTrigger). Provider wwebjs (desde 2026-10-30, promovido de extras). Omitido quando a Meta não manda o campo
disappearing_mode_initiated_by_me bool true quando foi esta conta que ligou as mensagens temporárias do chat (disappearingModeInitiatedByMe). Provider wwebjs (desde 2026-10-30, promovido de extras); false vem explícito. Omitido quando a Meta não manda o campo
is_broadcast bool true quando a mensagem chegou por uma lista de transmissão (broadcast da Meta). Provider wwebjs (desde 2026-11-02, promovido de extras); false vem explícito e é o normal. Omitido quando a Meta não manda o campo
media_source_type string Origem da mídia de imagem/vídeo como a Meta classifica: USER_IMAGE / USER_VIDEO (capturada pelo usuário), AI_GENERATED, AI_MODIFIED (só imagem), RASTERIZED_TEXT_STATUS (status de texto virado imagem). Lido de videoSourceType / imageSourceType. Provider wwebjs (desde 2026-11-05, promovido de extras). Omitido quando a Meta não manda o campo
ephemeral_duration int Timer de mensagem temporária, em segundos, sob o qual a mensagem foi enviada (ephemeralDuration, proto ContextInfo.expiration; ex.: 86400 = 24h, 604800 = 7 dias). 0 vem explícito: enviada com o timer desligado. Provider wwebjs (desde 2026-11-07, promovido de extras). Omitido quando a Meta não manda o campo
interactive_type string Tipo da mensagem interativa como a Meta classifica (interactiveType, o oneof do proto InteractiveMessage): native_flow (botões/fluxo nativo), shop, collection, carousel. Só texto de enum. Provider wwebjs (desde 2026-11-11, promovido de extras). Omitido quando a Meta não manda o campo
extras object Campos que a Meta acrescentou e ainda não têm nome nosso, com o nome original (wwebjs e whatsmeow). Instável por contrato, sem dado sensível; os estáveis são promovidos a campo oficial pelo validador da madrugada. Ver a seção extras abaixo
is_forwarded bool true se a mensagem foi encaminhada. Omitido quando false. O WhatsApp não informa de quem a mensagem foi encaminhada — apenas a flag + o score
target_from_me bool A mensagem-alvo desta ação é sua (reaction/pin). Omitido quando false
detail object Payload do evento dedicado paralelo, na íntegra (só para as famílias que têm um: group_invite, reaction, pin_chat/unpin_chat, poll_vote, product, order, button_reply/list_reply/interactive_reply). Torna este evento um superset do dedicado — ver a nota "Um fato, um evento" na seção de webhooks
forwarding_score uint32 Profundidade da cadeia de encaminhamento (o WhatsApp mostra "Encaminhada muitas vezes" quando alto). Omitido quando 0
latitude / longitude float64 Coordenadas — presentes apenas quando type=location (localização compartilhada, ex.: resposta a um pedido de localização). O nome do lugar (quando houver) vem em content
location_address string Endereço da localização compartilhada (apenas type=location, quando informado)
timestamp int64 Unix timestamp
is_group bool Se a mensagem veio de um grupo
push_name string Nome do remetente no WhatsApp (em grupos, e o nome do participante que enviou)
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado
historical bool true quando a mensagem é antiga — importada por histórico/backfill. Omitido no tráfego normal E no backlog recente de uma reconexão (ver abaixo)
history_source string Origem do evento histórico. Hoje "history_import" quando historical=true
thread_message_id string UUID Catcher (v4) da mensagem cabeca-de-thread que este reply alveja. Vazio se a cabeca não estiver no tenant DB
verified_name string Nome comercial oficial registrado no Meta quando o remetente e um WhatsApp Business verificado. Vazio para contatos não-business
retry_count int Número de vezes que o dispositivo destino pediu reenvio (sync de sessão Signal). 0 no caminho feliz
width uint32 Largura em pixels (image, video, sticker). 0 caso contrario
height uint32 Altura em pixels (image, video, sticker). 0 caso contrario
page_count uint32 Total de páginas de um PDF/documento. 0 caso contrario
jpeg_thumbnail string (base64) Thumbnail inline pequena (4-8KB) para image/video/document, codificada em base64. Permite renderizar placeholder antes do download completo
jpeg_thumbnail_omitted bool Presente apenas em entregas webhook compactadas quando jpeg_thumbnail foi omitido para manter o payload abaixo de limites comuns de parsers HTTP
jpeg_thumbnail_size_bytes int Tamanho aproximado/decodificado da thumbnail omitida, em bytes

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

Traços aditivos dos bundles de setembro/2026 (links, association, is_ai_sticker, sticker_premium, link_preview.preview_type, ad_context.conversion_source, detail em type=group_invite) — presentes desde 2026-09-13 em ambos os providers (whatsmeow e wwebjs), sempre aditivos e omitidos quando ausentes. Nenhum campo existente mudou de nome, tipo ou presença: um consumidor que ignora as chaves novas continua funcionando byte a byte. Nasceram do shape audit dos eventos crus (o WhatsApp Web passou a carregá-los nos bundles 1046846055+); cada um tem o campo-irmão no proto do whatsmeow, então o payload é o mesmo independente do provider.

Campo Tipo Onde Quando aparece Origem (wwebjs / whatsmeow)
links []{url, suspicious?} message.received, message.sent (eco externo) texto (type=text) que contém ao menos uma URL; ordem de aparição no texto detecção de links do próprio WhatsApp Web (links[].link/isSuspicious) / URLs extraídas do texto (http(s):// e www.), sem suspicious
association {type, parent_whatsapp_id, index?} message.received, message.sent (eco externo) mensagem que pertence a uma mãe — hoje o álbum (type=media_album) parentMsgKey + associationType / MessageContextInfo.messageAssociation (index só no whatsmeow)
is_ai_sticker bool idem type=sticker gerada pela Meta AI isAiSticker / StickerMessage.isAiSticker
sticker_premium int idem type=sticker com status premium (> 0) stickerPremiumStatus / StickerMessage.premium
link_preview.preview_type string dentro de link_preview quando o cliente remetente resolveu um cartão com tipo: video, image, placeholder, payment_links, profile (none é omitido) richPreviewType / ExtendedTextMessage.previewType
ad_context.conversion_source string dentro de ad_context conversa vinda de anúncio (ex.: "FB_Ads"). O ad_context passa a existir só com este campo — é o caso mais comum de lead de anúncio, sem cartão ctwaContext.conversionSource / ContextInfo.conversionSource
detail objeto message.received/message.sent com type=group_invite sempre que o tipo é convite de grupo inviteGrp/inviteGrpName/inviteCode/inviteCodeExp/inviteGrpType / GroupInviteMessage

Exemplo 1 — texto com links e cartão. Sob EVENT_NAMING=specific o type de topo é text.received; o data é idêntico.

json
{
  "type": "message.received",
  "data": {
    "phone": "5541999998888", "from": "5541999998888@s.whatsapp.net", "chat": "5541999998888@s.whatsapp.net",
    "message_ids": ["8074ae69-9e15-40b9-8565-99d56fae9781"],
    "type": "text", "message_type": "text",
    "content": "Oi! Dá uma olhada nesse artigo: https://pt.wikipedia.org/wiki/Curitiba e depois http://www.iterfunnel.com",
    "links": [
      {"url": "https://pt.wikipedia.org/wiki/Curitiba"},
      {"url": "http://www.iterfunnel.com"}
    ],
    "link_preview": {
      "url": "https://pt.wikipedia.org/wiki/Curitiba",
      "title": "Curitiba – Wikipédia",
      "description": "Curitiba é a capital do estado do Paraná…",
      "thumbnail_url": "https://<conta>.r2.cloudflarestorage.com/…?X-Amz-Expires=86400…",
      "preview_type": "image"
    },
    "timestamp": 1789320960, "is_group": false, "push_name": "Maria", "international": false
  }
}

Um link que o WhatsApp Web classificou como suspeito (domínio parecido / homógrafo — o aviso "link suspeito" do app) vem {"url": "https://xn--pple-43d.com", "suspicious": true}; no whatsmeow a chave suspicious nunca aparece. links cobre só texto — captions de mídia não geram links (paridade com o WhatsApp Web, que também não os linka).

Exemplo 2 — foto de um álbum. Cada foto/vídeo de um post com várias mídias chega como seu próprio evento (image.received, video.received), na ordem em que o WhatsApp as entrega, carregando a chave do cabeçalho do álbum. O cabeçalho em si (type=album, sem mídia e sem texto) não é persistido nem emitido. Agrupe pelo parent_whatsapp_id; index (posição no álbum) só existe no whatsmeow e só quando > 0 — a primeira mídia chega sem index, então use a ordem de entrega como referência e index apenas como desempate.

json
{
  "type": "message.received",
  "data": {
    "phone": "5541999998888", "chat": "120363036972484891@g.us", "from": "5541999998888@s.whatsapp.net",
    "message_ids": ["c5a47367-aeff-4742-b2f7-c1e49eda3e89"],
    "type": "image", "message_type": "image",
    "media_id": "9e8282fe-02b9-4a91-bdd1-12687568be62", "mime_type": "image/jpeg", "file_size": 257663,
    "association": {"type": "media_album", "parent_whatsapp_id": "ACCF95691229D0FF56F4A5EB294DA7A0", "index": 2},
    "is_group": true, "group_name": "Turma da foto", "timestamp": 1788648120
  }
}

Outros vínculos mantêm o nome do enum em snake_case (status_add_yours, sticker_annotation, motion_photo, …) — o consumidor pode agrupar sem que a Catcher precise enumerar cada valor futuro.

Exemplo 3 — figurinha da Meta AI.

json
{"type": "sticker", "message_type": "sticker", "media_id": "…", "mime_type": "image/webp",
 "is_animated": false, "is_ai_sticker": true, "sticker_premium": 1, "accessibility_label": "gato de óculos"}

Exemplo 4 — lead de anúncio sem cartão. Muitas conversas vindas de click-to-WhatsApp chegam só com a atribuição, sem título/corpo/mídia do anúncio. Antes o ad_context era omitido nesse caso; agora ele existe só com conversion_source.

json
{"type": "text", "content": "Olá, vi o anúncio de vocês", "ad_context": {"conversion_source": "FB_Ads"}}

Quando o anúncio traz o cartão, conversion_source acompanha os campos já documentados (source_type, source_id, title, body, thumbnail_url, …).

Exemplo 5 — convite de grupo. O detail traz o cartão como chegou. Sob EVENT_NAMING=specific o convite continua chegando como message.received (o tipo group_invite fica fora da lista de nomes específicos — text, image, sticker, … — de propósito: tipo fora da lista mantém o nome genérico, que toda assinatura cobre). group_type é default ou parent (grupo-mãe de uma comunidade). invite_expiration é unix segundos.

json
{
  "type": "group_invite", "message_type": "group_invite", "content": "Turma do Curso",
  "detail": {
    "group_jid": "120363123456789012@g.us", "group_name": "Turma do Curso",
    "invite_code": "AbCdEf123456", "invite_expiration": 1790000000,
    "caption": "entra aí pessoal", "group_type": "default"
  }
}

Atenção: invite_code é o token vivo do convite (o mesmo que o destinatário já vê no cartão) — quem consome o webhook consegue montar https://chat.whatsapp.com/<invite_code> e entrar no grupo; trate como conteúdo sensível do cliente.

Lado do remetente. Os mesmos campos (links, association, is_ai_sticker, sticker_premium, link_preview.preview_type) aparecem no message.sent de ecos externos (source="external" — enviado pelo celular/WhatsApp Web) porque o eco lê o fio exatamente como o recebimento. Envios pela API (source="api") não carregam links/association hoje; ad_context nunca existe em envio.

extras — o que a Meta acrescentou e ainda não tem nome nosso (provider wwebjs, desde 2026-10-26). Todo campo simples (booleano, número ou texto curto) que o WhatsApp Web coloca na mensagem e que ainda não é mapeado com um nome nosso chega em data.extras, com o nome original da Meta, no mesmo dia em que a Meta o publica — sem esperar ninguém decidir. Vale para todo evento derivado de um evento da Meta: recebimento e envio (message.received, message.sent de eco externo), recibos (message.delivered/read/played), edição, apagar, reação, chamadas, grupos, contatos, estado de chat, presença e etiquetas. Eventos operacionais da própria Catcher (connection.*, instance.*, wwebjs.*) nunca trazem extras. Num recibo, o extras é o da mensagem a que o recibo se refere, como a Meta o mandou naquele momento.

json
"extras": { "isVoiceChat": false, "screenedElsewhere": false, "viewMode": "VISIBLE", "ephemeralDuration": 86400 }
  • É instável por contrato. Um campo de extras pode deixar de vir quando a Meta tirá-lo. Para depender de um campo, use o nome oficial depois que ele for promovido.
  • Promoção automática. O validador da madrugada analisa os campos de extras e promove os estáveis a campo oficial (nome em snake_case, documentado aqui, com o equivalente no whatsmeow quando existir). Promovido, o campo nunca mais sai do evento — se a Meta tirá-lo, ele só passa a vir omitido — e deixa de aparecer em extras.
  • Nunca carrega dado sensível. Ficam de fora, sempre: chaves e hashes de mídia (mediaKey, filehash), URLs e caminhos de CDN da Meta (directPath, deprecatedMms3Url), miniaturas em base64, tokens, JIDs/LIDs crus e IDs crus do WhatsApp — por nome e também por valor (qualquer texto com ://, @, cara de base64 ou maior que 200 caracteres). Objetos, listas e null também não entram.
  • Omitido quando não houver nenhum campo. No máximo 64 campos / 4 KB, em ordem alfabética; quando o limite corta algo, vem "_truncated": true dentro de extras.
  • Provider whatsmeow (desde 2026-10-27): mesmas regras e mesmo corte do que é sensível. Vem nos eventos de mensagem recebida (message.received e as formas específicas, como text.received), com os campos simples que a mensagem da Meta traz e que ainda não têm nome nosso — o conteúdo (ex.: ImageMessage), o contextInfo e as informações da mensagem —, com o nome do campo no protocolo (ex.: viewOnce, imageSourceType, isSpoiler, multicast). Os nomes não são os mesmos do wwebjs: cada provider repassa o que a sua fonte chama. Um campo novo da Meta chega aqui quando a versão do protocolo do whatsmeow é atualizada (o fork é sincronizado pelo robô da madrugada).
  • Só passam booleanos, números e textos curtos com cara de enum (VISIBLE, account_settings). Texto livre, qualquer coisa com ponto, barra, espaço ou @, sequências longas de dígitos e números grandes que não sejam horário ficam de fora — por segurança, não por esquecimento.

O que NÃO mudou. businessHours do perfil comercial não virou evento (o WhatsApp Web não notifica mudança de horário; continua no GET /business/profile). O campo groupHistorySentState, que sumiu do modelo de participante nos bundles novos, nunca foi exposto.

Link preview e traços de mídia (link_preview, is_animated, is_gif, accessibility_label) — presentes desde 2026-09-04 em ambos os providers (whatsmeow e wwebjs), sempre aditivos e omitidos quando ausentes:

Detalhe Comportamento
Quem resolve o preview O cliente de quem enviou. A Catcher não acessa a URL — repassa o que veio no fio (ExtendedTextMessage / matchedText). Um celular costuma mandar só url + title (o domínio); o WhatsApp Web/Desktop resolve title + description + thumbnail. Se o remetente mandou o link sem preview, o objeto não vem
thumbnail_url O thumbnail chega inline no fio (JPEG) e é gravado no R2 da Catcher (dedup por SHA-256). A URL é assinada, válida por 24h (padrão S3_PRESIGN_TTL): baixe e persista se for exibir depois. Nunca uma URL de CDN da Meta, nunca base64 no payload
is_animated Flag do remetente (isAnimated/isLottie no proto). Ausente = não animado OU o cliente remetente não sinalizou (o WhatsApp Web, por exemplo, não sinaliza). Stickers enviados pela própria Catcher (POST /messages/sticker) saem sinalizados quando o WebP é animado
is_gif Vídeo enviado como GIF (gifPlayback). O type/message_type continua video — GIF é um vídeo com a flag, não um tipo próprio no recebimento
accessibility_label Alt-text que o remetente anexou à mídia (recurso de acessibilidade do WhatsApp). Só existe se o cliente remetente o preencheu
preview_type Tipo do cartão que o cliente remetente resolveu: video, image, placeholder, payment_links ou profile (ExtendedTextMessage.previewType / richPreviewType). Omitido quando none
Nome do evento Sob EVENT_NAMING=specific estes campos chegam em text.received (link preview), sticker.received, video.received, etc. — mesmo data, só o type de topo muda; uma assinatura/filtro por message.received cobre todos
Lado do remetente Os mesmos quatro campos existem no message.sent (desde 2026-09-05): envio via API preenche o que se sabe na hora (/messages/link-preview → url/title/description; /messages/gif → is_gif; sticker WebP animado → is_animated); eco source="external" (WhatsApp Web/celular) lê o fio como o recebimento. Assim quem renderiza os DOIS lados da conversa vê o cartão/selo também nas mensagens do operador

Campos de ad_context (todos opcionais, presentes conforme disponível no proto):

Campo Tipo Descricao
source_type string Plataforma de origem (ex: "instagram", "facebook")
source_app string Nome do app de origem (ex: "Instagram")
source_id string Identificador do anuncio na plataforma
title string Titulo/headline do anuncio
body string Texto descritivo do anuncio
media_type string Tipo de mídia do anuncio: "image", "video", ou vazio
ctwa_clid string Click-to-WhatsApp Client ID (tracking)
ref string Parametro de referência/tracking (ex: UTM campaign)
conversion_source string Canal de atribuição da Meta (ex.: "FB_Ads"). Muitas vezes é o único campo que uma conversa vinda de anúncio traz — o ad_context passa a existir só com ele (ContextInfo.conversionSource / ctwaContext.conversionSource)
thumbnail_url string URL Catcher R2 da thumbnail do anuncio. O worker baixa a imagem via proxy da instância e persiste em {company}/ads/thumbs/{sha256}.{ext} no R2, retornando a URL pública. Quando o proto traz a thumbnail inline (campo Thumbnail []byte), o upload e direto — sem HTTP. Campo vazio se o cache falhou ou a instância não tem proxy bindado. Nunca será URL Meta/CDN.
media_url string URL Catcher R2 da mídia completa do anuncio (imagem/video grande). Worker baixa via proxy da instância e persiste em {company}/ads/media/{sha256}.{ext}. Campo vazio se cache falhou ou proxy indisponível. Nunca será URL Meta/CDN. Video: cap de 30 MB; excedeu, skip.

Proxy-discipline (licoes #29, #31, #35): As URLs acima (thumbnail_url, media_url) são sempre URLs Catcher — seja URL pública do R2 (quando S3_PUBLIC_URL está configurado) ou vazio. O worker NUNCA expoe URLs brutas do Meta (cdninstagram.com, fbcdn.net, scontent.*, facebook.com/*/videos/*) ao consumer. Todas as imagens/videos de anuncios são baixados pelo proxy dedicado da instância e republicados via R2 com dedup por sha256 do conteúdo (mesma thumbnail em 100 instâncias da mesma empresa = 1 objeto no R2). O campo source_url do proto Meta (permalink do post Instagram/Facebook) permanece intencionalmente removido — consumidores podem reconstruir referência via source_id + source_type quando necessário. Cache e best-effort: uma falha de rede ou ausência de binding emite campo vazio, sem quebrar o webhook.

Campos de cada item de contacts (presente apenas quando type=contact):

Campo Tipo Descricao
display_name string Nome de exibição do contato (proto DisplayName; cai no FN do vCard quando vazio)
phones []string Números de telefone extraidos do vCard, so digitos (ex: "5541988887777"). O parametro waid= (número normalizado do WhatsApp) tem prioridade sobre o valor formatado do campo TEL. Vazio se o vCard não tem linha TEL
vcard string vCard 3.0 cru, exatamente como veio no proto. Fidelidade total (email, organização, multiplos números) para quem quiser parsear

Contatos: O campo top-level phone identifica quem enviou o cartao, não o contato compartilhado. Para os números do(s) contato(s) compartilhado(s), use contacts[].phones.

Reactions: Quando type=reaction, o campo content contem o emoji (ex: "❤️"). Um content vazio indica que a reaction foi removida. O campo reaction_target_id contem o ID da mensagem que recebeu a reaction.

Replies interativos: button_reply, list_reply e interactive_reply aparecem em message.received com content preenchido pelo texto selecionado quando disponível, e a seleção estruturada (IDs selecionados, índice do botão/lista, payload native-flow) em data.detail.

Compactação de thumbnail em webhooks: se o envelope JSON completo de uma entrega webhook passar de 8KB e contiver data.jpeg_thumbnail, a entrega remove o campo inline e adiciona jpeg_thumbnail_omitted=true + jpeg_thumbnail_size_bytes. O media_id permanece disponível para download da mídia. Isso evita falhas em consumers com body parser limitado a 8KB.


message.sent#

Disparado após envio bem-sucedido via API (source=api) ou eco observado do celular/WhatsApp Web (source=external). Persistido na tabela messages. Para mensagens de mídia, inclui media_id para download via GET /v1/instances/{instanceId}/media/{mediaId}.

Transmissão paga do WhatsApp Business (wwebjs): o envelope da lista @broadcast é suprimido. Cada cópia real gera seu próprio message.sent (interactive.sent no dialeto específico), com UUID estável por destinatário. type/message_type=interactive, content é a legenda textual, header.type=image|video indica o cabeçalho, e os campos planos media_id, mime_type, file_size, duration, width, height descrevem a mídia armazenada. buttons contém {type,id,text}; broadcast_id agrupa opcionalmente as cópias. Nenhum ponteiro/chave de mídia ou URL CDN é exposto. Replay não cria novo UUID nem novo evento. status@broadcast continua no fluxo de status.

Recibos e respostas de botão usam o UUID do mesmo destinatário; button_reply.received.quoted_id e o alias quoted_msg_id apontam para esse original. Não correlacione por id nativo, pois ele pode ser compartilhado entre destinatários e direções. Referências de edit/redownload/label/forward usam a mensagem selecionada por UUID; IDs nativos ambíguos são recusados com 409. Em operações vinculadas a to/chat, um UUID existente em outro chat é recusado antes de converter para o id nativo, inclusive reaction/delete/ações/quote. Um UUID de quote realmente ausente conserva o contrato lenient documentado; um UUID reconhecido fora do chat não pode selecionar a cópia daquele chat. Se a mídia falhar, o evento fica no reconciliador durável até recuperação ou esgotamento; recibos podem chegar antes desse evento adiado. GET da mensagem usa /v1/instances/{instanceId}/message/{messageId} (singular); nele a metadata do arquivo fica em media, e header, buttons, broadcast_id preservam a identidade interativa.

Quando o mesmo ID nativo aparece nas duas direções do mesmo chat, uma operação cujo provider recebe somente chat+ID nativo (edit/delete/reaction/quote/forward/label) responde 409 CONFLICT, inclusive com UUID exato: a conversão perderia a autoria. O provider recebe ID nativo apenas após validar o alvo; UUID público não vira StanzaID. GET por UUID e operações que carregam direção explícita continuam distinguindo as mensagens.

json
{
  "phone": "554192464230",
  "to": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "type": "image",
  "message_type": "image",
  "content": "Foto do produto",
  "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mime_type": "image/jpeg",
  "file_name": "produto.jpg",
  "file_size": 123456,
  "source": "api",
  "idempotency_key": "msg-2026-03-21-0001",
  "task_id": "0efc848e-d9be-4615-8217-f1d9c40f0436",
  "quoted_msg_id": "3EB0AAA111BBB222",
  "timestamp": 1741360300,
  "is_group": false
}

Exemplo com varios contatos (type=contact):

json
{
  "phone": "554137984905",
  "to": "554137984905@s.whatsapp.net",
  "chat": "554137984905@s.whatsapp.net",
  "message_ids": ["c2b4e6f0-1234-4ab5-9c0d-fedcba987654"],
  "type": "contact",
  "content": "Suporte Catcher, Comercial",
  "contacts": [
    {
      "display_name": "Suporte Catcher",
      "phones": ["5541988887777"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Suporte Catcher\nTEL;type=CELL;type=VOICE;waid=5541988887777:+5541988887777\nEND:VCARD"
    },
    {
      "display_name": "Comercial",
      "phones": ["5541977776666"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Comercial\nTEL;type=CELL;type=VOICE;waid=5541977776666:+5541977776666\nEND:VCARD"
    }
  ],
  "source": "api",
  "idempotency_key": "msg-2026-05-18-0042",
  "timestamp": 1741360500,
  "is_group": false
}

content em type=contact: com um único contato, e o display_name. Com varios, e a juncao dos display_name separados por ", " (ex: "Suporte Catcher, Comercial"). Para os dados estruturados, sempre use contacts[].

Campo Tipo Descricao
phone string Número de telefone sem sufixo (ex: "554192464230"). Para mensagens externas com LID, resolvido do registro de identidade; pode ser vazio no primeiro contato
to string JID do destinatário (resolvido para phone JID quando possível)
chat string JID do chat (igual a to em DM, JID do grupo em grupo; resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente apenas quando o destinatário usava LID internamente. Util para correlação com receipts (ver seção 22)
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado. message_ids[0] e o mesmo UUID retornado em message_id na resposta 202 do endpoint de envio — use este valor para correlacionar o webhook com a request original.
task_id string Echo do task_id retornado na resposta 202 do endpoint de envio (correlação determinística task→mensagem, complementar ao message_ids[0]). Presente apenas em source="api"; vazio para source="external".
type string Tipo da mensagem (text, image, video, audio, document, sticker, location, contact, reaction, poll, template, button_reply, list_reply, interactive_reply). Um forward via API sai com o tipo do CONTEÚDO de origem (encaminhar um vídeo emite video.sent) — forward não é um tipo
content string Conteúdo/caption da mensagem, ou emoji (para reactions). Para type=contact, e o nome de exibição do(s) contato(s) — use contacts para os dados estruturados
contacts []object Cartoes de contato compartilhados. Presente apenas quando type=contact. Mesma estrutura de contacts em message.received (display_name, phones, vcard)
source string Origem do envio: "api" (enviado pela Catcher) ou "external" (enviado pelo WhatsApp Web, telefone ou outra API)
idempotency_key string Eco do header Idempotency-Key da request original. Presente apenas quando source="api". Util para casar o webhook com a request do cliente quando multiplas requests compartilham o mesmo destinatário no curto prazo. Ausente em outbound externo (WhatsApp Web/celular/outra API).
media_id string ID da mídia para download via API (presente para mensagens de mídia)
link_preview object Lado do remetente do cartão de link (mesma forma do message.received: url, title, description, thumbnail_url). Presente em: envio via POST /messages/link-preview (url/title/description do pedido — sem thumbnail_url, os bytes vieram de você) e em ecos source="external" (o WhatsApp Web/celular resolveu o cartão; thumb lavado pro R2). Um POST /messages/text com URL não ganha link_preview no .sent — o preview que o WhatsApp Web possa montar do lado dele não volta pelo fio do envio; use /messages/link-preview pra um cartão determinístico
is_animated bool Figurinha animada. Envio pela API: detectado no WebP (chunk ANIM); eco externo: flag do cliente remetente. Omitido quando false
is_gif bool Vídeo enviado como GIF (POST /messages/gif, ou eco externo com gifPlayback). type continua gif no envio pela API e video no eco. Omitido quando false
accessibility_label string Alt-text da mídia — só em ecos externos cujo cliente o preencheu. Omitido quando ausente
links []object Espelho de links do message.received — só em ecos externos (source="external")
association object Espelho de association do message.received — o eco de um álbum enviado pelo celular chega com a chave do álbum
is_ai_sticker bool Espelho de is_ai_sticker — eco externo de uma figurinha da Meta AI. Omitido quando false
sticker_premium int Espelho de sticker_premium. Omitido quando 0
is_view_once bool Espelho de is_view_once do message.received — provider wwebjs, eco externo
is_spoiler bool Espelho de is_spoiler do message.received — provider wwebjs, eco externo
is_ephemeral bool Espelho de is_ephemeral do message.received — provider wwebjs, eco externo
is_from_template bool Espelho de is_from_template do message.received — provider wwebjs, eco externo
is_event_canceled bool Espelho de is_event_canceled do message.received — provider wwebjs, eco externo
disappearing_mode_initiator string Espelho de disappearing_mode_initiator do message.received — provider wwebjs, eco externo
disappearing_mode_trigger string Espelho de disappearing_mode_trigger do message.received — provider wwebjs, eco externo
disappearing_mode_initiated_by_me bool Espelho de disappearing_mode_initiated_by_me do message.received — provider wwebjs, eco externo
is_broadcast bool Espelho de is_broadcast do message.received — provider wwebjs, eco externo
media_source_type string Espelho de media_source_type do message.received — provider wwebjs, eco externo
ephemeral_duration int Espelho de ephemeral_duration do message.received — provider wwebjs, eco externo
interactive_type string Espelho de interactive_type do message.received — provider wwebjs, eco externo
extras object Espelho de extras do message.received, no provider wwebjs — em ecos externos E em envios pela API (o que a Meta pôs na própria mensagem enviada). Instável por contrato; ver a seção extras
mime_type string MIME type da mídia
file_name string Nome do arquivo
file_size int64 Tamanho do arquivo em bytes
quoted_msg_id string UUID Catcher (v4) da mensagem sendo respondida. Presente apenas em respostas/reply threading. Vazio se a mensagem citada não estiver no tenant DB (ex: reply a mensagem antiga de antes da instância entrar no chat). Nunca e o hex do WhatsApp — use este campo para correlacionar com message_ids[0] de eventos anteriores.
reaction_target_id string UUID Catcher (v4) da mensagem que recebeu a reaction (apenas para type=reaction). Vazio se o alvo não estiver no tenant DB. A resolução tolera a troca de JID individual @lid↔@s.whatsapp.net durante o retry de descriptografia.
is_forwarded bool true quando a mensagem saiu com o par "Encaminhada" NO FIO: forward via API de conteúdo recebido (ou já encaminhado), OU encaminhamento feito no celular/WhatsApp Web (echo source="external"). Forward via API de mensagem PRÓPRIA sai como cópia limpa (semântica do cliente oficial) e fica omitido. O WhatsApp não informa de quem a mensagem foi encaminhada — apenas a flag + o score
forwarding_score uint32 Profundidade da cadeia de encaminhamento. 1 num forward de primeira mão. Omitido quando 0
timestamp int64 Unix timestamp do envio
is_group bool Se a mensagem foi enviada para um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado
historical bool true quando a mensagem é antiga — importada por histórico/backfill, não enviada como ação ao vivo desta instância. Omitido no tráfego normal E no backlog recente de uma reconexão (ver abaixo)
history_source string Origem do evento histórico. Hoje "history_import" quando historical=true
thread_message_id string UUID Catcher (v4) da mensagem cabeca-de-thread que este reply alveja. Vazio se a cabeca não estiver no tenant DB
retry_count int Número de vezes que a mensagem foi reconstruida antes do envio final. Diferente de 0 apenas em echo outbound de outro dispositivo que precisou retry. 0 no caminho feliz
width uint32 Largura em pixels (image, video, sticker). 0 caso contrario
height uint32 Altura em pixels (image, video, sticker). 0 caso contrario
page_count uint32 Total de páginas de um PDF/documento. 0 caso contrario
jpeg_thumbnail string (base64) Thumbnail inline pequena (4-8KB) para image/video/document, codificada em base64. Permite renderizar placeholder antes do download completo
jpeg_thumbnail_omitted bool Presente apenas em entregas webhook compactadas quando jpeg_thumbnail foi omitido para manter o payload abaixo de limites comuns de parsers HTTP
jpeg_thumbnail_size_bytes int Tamanho aproximado/decodificado da thumbnail omitida, em bytes

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

Captura de outbound externo: Mensagens enviadas por WhatsApp Web, pelo celular ou por outra API conectada ao mesmo número são capturadas automaticamente como message.sent com source: "external". Isso permite rastrear toda a comunicação outbound independente de onde foi originada. Mensagens enviadas pela própria Catcher via fila tem source: "api". A persistencia no banco também distingue: a coluna source na tabela messages armazena "api" ou "external". Em mensagens externas, quoted_msg_id e reaction_target_id também são preservados quando presentes, inclusive para message.sent de grupos (is_group=true).

Reação enviada do próprio celular (ambos os providers): uma reação que o dono do número envia pelo celular/WhatsApp Web também é capturada como message.sent com type: "reaction", source: "external", content = emoji (vazio = remoção), reaction_target_id = UUID Catcher da mensagem reagida e message_ids = UUID da linha persistida. No provider wwebjs a linha outbound usa um whats_app_id sintético determinístico por alvo, então re-reagir/remover atualiza a MESMA linha (estado final da reação) e replays de history-sync nunca duplicam; replays gravam a linha mas não re-emitem o evento.

Reação após retry de descriptografia (whatsmeow): o placeholder de uma mensagem inbound não descriptografável pode ter sido gravado com o chat em formato LID (@lid), enquanto o eco posterior da reação chega com o JID de telefone (@s.whatsapp.net). O reaction_target_id continua sendo resolvido pelo UUID Catcher da linha correta; o consumidor não precisa conhecer nem persistir o ID hexadecimal do WhatsApp.

Chave do chat em contatos LID (provider wwebjs): toda persistência (envio via API, echo externo, reação) grava remote_j_id resolvendo LID→telefone (phone-first). Quando a identidade ainda não é resolvível, a linha é gravada com o @lid (nada se perde) e um sweep periódico por instância (WWEBJS_LID_REKEY_INTERVAL_MS, default 5min; lote WWEBJS_LID_REKEY_BATCH, default 25) re-chaveia para o JID de telefone assim que a identidade aparece no registry contact_identities ou resolve ao vivo. O processor Go também faz backfill autoritativo pós-envio (media_id + remote_j_id) quando o echo do Node ganhou a corrida de persistência.

LID em mensagens externas: Quando uma mensagem e enviada por outro dispositivo (WhatsApp Web, celular) para um contato cujo chat aparece como LID, a Catcher resolve o telefone usando 3 camadas de fallback:

  1. RecipientAlt (protocolo): o WhatsApp envia peer_recipient_pn no evento, contendo o telefone do destinatário — está e a fonte primaria e mais confiavel para outbound echo.
  2. MySQL (contact_identities): registro persistido de interacoes anteriores (SenderAlt, RecipientAlt, queries de contato).
  3. SQLite (whatsmeow_lid_map): cache do whatsmeow populado por syncs de grupo, mensagens de migração LID, e operações de envio.

Se o contato já foi visto em qualquer dessas fontes, phone, to e chat conterao o telefone resolvido. Caso contrario, phone ficara vazio e chat_lid contera o LID original — quando o contato responder (trazendo SenderAlt) ou aparecer em um sync de grupo, o mapeamento LID→telefone será aprendido automaticamente para futuras consultas.

Nota: Não existe API no protocolo WhatsApp para resolver LID→telefone sob demanda. GetUserInfo(lid) não retorna o telefone (so funciona na direcao PN→LID).


message.delivered#

Disparado quando o destinatário recebe a mensagem (dois checks cinza). Atualiza status=delivered e delivered_at na tabela messages.

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "delivered",
  "timestamp": 1741360310,
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (ex: "554192464230"). Resolvido via 5 niveis de fallback: JID direto → MySQL contact_identities por chat LID → MySQL por sender LID → SQLite whatsmeow_lid_map → busca na tabela messages
message_ids []string UUIDs internos do Catcher. Identificadores únicos e estáveis.
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID de quem recebeu (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender (com sufixo de dispositivo), presente quando o WhatsApp usou LID internamente
status string Sempre "delivered"
timestamp int64 Unix timestamp da entrega
is_group bool Se o chat e um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado

message.read#

Disparado quando o destinatário le a mensagem (dois checks azuis). Atualiza status=read e read_at na tabela messages.

No wwebjs, um recibo sem mensagem persistida cuja mensagem é comprovadamente anterior à criação da instância é ignorado após a espera breve de persistência; não cria mensagem nem webhook órfão. Mensagens históricas já armazenadas recebem o recibo normalmente. Mensagens atuais ou com data desconhecida continuam sendo retentadas quando a linha ainda não existe.

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "read",
  "timestamp": 1741360350,
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo. Resolvido do registro de identidade quando o chat e um LID (mesma cadeia de fallback que message.delivered)
message_ids []string UUIDs internos do Catcher. Identificadores únicos e estáveis.
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID de quem leu (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
status string Sempre "read"
timestamp int64 Unix timestamp da leitura
is_group bool Se o chat e um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado

message.played#

Disparado quando o destinatário abre uma mídia "visualizar uma vez" (view-once). Atualiza status=played e played_at na tabela messages.

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "played",
  "timestamp": 1741360400,
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (mesma cadeia de fallback que message.delivered)
message_ids []string UUIDs internos do Catcher. Identificadores únicos e estáveis.
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID de quem abriu (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
status string Sempre "played"
timestamp int64 Unix timestamp da abertura
is_group bool Se o chat e um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado

message.deleted#

Disparado quando uma mensagem e apagada ("apagar para todos"). Atualiza status=deleted e deleted_at na tabela messages. Cobre ambas as direcoes: mensagens inbound apagadas pelo contato (is_from_me=false) e mensagens outbound apagadas pelo operador via WhatsApp phone/Web (is_from_me=true).

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "sender_lid": "216251804708983:34@lid",
  "is_from_me": false,
  "timestamp": 1741360400
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado.
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID de quem apagou (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
is_from_me bool Se foi a própria instância que apagou
is_group bool Se a mensagem apagada pertencia a um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado
timestamp int64 Unix timestamp

message.edited#

Identidade sempre resolvida (desde 2026-08-02). No provider wwebjs este evento — e o message.deleted — chegavam com o LID CRU em chat/sender e sem o campo phone (ausente, não vazio), o que fazia um consumidor indexado por telefone descartar o evento. Agora o LID é resolvido para o JID de telefone, o LID original vai em chat_lid/sender_lid, e phone/chat/sender estão sempre presentes (string vazia quando o LID é irresolúvel — nunca ausentes, nunca um número inventado).

Disparado quando uma mensagem e editada. Atualiza content na tabela messages. Cobre ambas as direcoes: mensagens inbound editadas pelo contato (is_from_me=false) e mensagens outbound editadas pelo operador via WhatsApp phone/Web (is_from_me=true).

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "sender_lid": "216251804708983:34@lid",
  "new_content": "Texto editado da mensagem",
  "is_from_me": false,
  "is_group": false,
  "push_name": "Joao",
  "timestamp": 1741360450
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado.
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID de quem editou (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
new_content string Novo conteúdo da mensagem
is_from_me bool Se foi a própria instância que editou
is_group bool Se a mensagem e de um grupo
push_name string Nome do remetente (opcional)
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado
timestamp int64 Unix timestamp

call.received#

Disparado quando a instância recebe uma chamada 1:1 (o OFFER). Persistido na tabela call_logs. (Campos enriquecidos no provider wwebjs — ver nota no início de call.accepted.)

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "from_lid": "195718102958197@lid",
  "call_id": "CALL-ABC123",
  "direction": "inbound",
  "offer_time": 1741360498,
  "is_video": false,
  "is_group": false,
  "timestamp": 1741360500
}
Campo Tipo Descricao
phone string Número de telefone do chamador (resolvido)
from string JID canônico do chamador
from_lid string @lid original do chamador (omitido quando já veio número)
call_id string ID único da chamada (correlaciona com o desfecho call.accepted/rejected/ended)
direction string inbound (recebida) ou outbound (chamada que a instância discou via POST .../calls/place)
state string (VoIP) "ringing" quando a chamada é atendível pela própria instância — instância em VOIP_MANUAL_ANSWER_INSTANCES (atender/rejeitar via POST .../calls/{callID}/answer|reject) OU chamada de saída recém-discada. Omitido para auto-answer / não-VoIP / apenas observada.
offer_time int64 Unix do offer real (Call.offerTime)
is_video bool Chamada de vídeo (sempre presente)
is_group bool false para 1:1 (sempre presente)
timestamp int64 Unix timestamp em que o worker processou

VoIP — modo manual + discagem (whatsmeow, staging). Numa instância em VOIP_MANUAL_ANSWER_INSTANCES, o OFFER de entrada vem com state:"ringing" e a instância não atende sozinha — o operador atende (.../calls/{callID}/answer → call.accepted) ou rejeita (.../calls/{callID}/reject → call.rejected); se ninguém agir em VOIP_RING_TIMEOUT (45s), é auto-rejeitada. Uma chamada de saída (POST .../calls/place) emite um call.received com direction:"outbound" + state:"ringing". As instâncias em VOIP_AUTO_ANSWER_INSTANCES seguem atendendo automaticamente. Ver seção 16 (endpoints de call).


connection.update#

Disparado quando o status da conexão WhatsApp muda. Persistido na tabela instances.

json
{
  "status": "connected",
  "reason": "",
  "previous_status": "connecting",
  "ban_expiry": null
}
Campo Tipo Descricao
status string "connected", "disconnected", "banned", "logged_out", "replaced", "connect_failure", "client_outdated", "stream_error", "keepalive_timeout", "keepalive_restored"
reason string Classifica o gatilho. Para status="disconnected": flapping (detector de flap), qr_pending_cooldown (WS fechou esperando scan de QR), silent_close (TCP EOF/RST), session_not_connected e proxy_unhealthy (provider wwebjs — ver abaixo). Para banned/logged_out/replaced/connect_failure/etc, a string do evento original
previous_status string Status que a instância tinha imediatamente antes desta transicao (ex: distinguir QR_PENDING → DISCONNECTED de CONNECTED → DISCONNECTED). Omitido quando desconhecido
ban_expiry int64/null Unix timestamp de quando o ban expira (apenas para "banned")

A queda do socket é anunciada (provider wwebjs). Antes, uma instância cujo socket do WhatsApp Web saía de CONNECTED continuava marcada como conectada: nenhum evento saía, e o consumidor só descobria pelo silêncio. Agora, um socket que continua fora depois de uma janela de graça de 60s persiste DISCONNECTED + disconnected_at e emite connection.update com:

  • reason: "proxy_unhealthy" — a sonda do túnel da instância está falhando (a queda tem causa de rede conhecida);
  • reason: "session_not_connected" — o socket caiu sem que a sonda acusasse o túnel.

A volta emite status:"connected" com previous_status:"disconnected". A graça de 60s existe porque 97% dos 185 episódios medidos em 12 dias duram menos de 10s — anunciar cada um deles seria ruído; o que importa é a queda que persiste. Enquanto o socket está fora, novos envios são segurados (não queimam tentativa e não gastam a janela de validade), e o desired_state nunca é alterado: uma queda transitória não desarma a intenção de estar conectado.

Novos status:

  • connect_failure — falha ao conectar ao servidor WhatsApp (ex: erro de rede, autenticação falhou)
  • client_outdated — versão do cliente WhatsApp está desatualizada e precisa ser atualizada
  • stream_error — erro no stream de comunicação com o servidor WhatsApp
  • keepalive_timeout — keepalive não recebeu resposta a tempo; conexão pode estar instável
  • keepalive_restored — keepalive voltou a funcionar normalmente após um timeout

presence.update#

Disparado quando um contato fica online/offline ou está digitando. Evento transiente, não persistido no banco.

Nota: Para receber presença de digitacao, a instância precisa estar com presença available. Para presença online/offline, a Catcher so passa a monitorar após POST /v1/instances/{instanceId}/contacts/{contactId}/presence/subscribe.

Snapshot opcional: GET /v1/instances/{instanceId}/contacts/{contactId}/presence le o último estado conhecido em Redis (online, last_seen, typing_state). Isso não substitui SSE/WebSocket/webhook; e apenas um read model transiente para UX.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "available": true,
  "last_seen": 1741360000,
  "state": "composing",
  "is_chat": true,
  "chat": "554192464230@s.whatsapp.net",
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos)
from string JID do contato
available bool Se está disponível/digitando
last_seen int64 Último visto (unix, 0 se oculto). Apenas para online/offline
state string "composing", "paused", "recording" (apenas para is_chat=true)
is_chat bool true = digitacao em chat, false = online/offline
chat_lid string LID original do chat, presente apenas quando o WhatsApp usou LID internamente. Até 2026-08-02 o chat vinha com o LID CRU e sem este campo; agora chat é sempre o JID de telefone e o LID original vem aqui
chat string JID do chat onde está digitando (apenas para is_chat=true)
is_group bool Se e em um grupo

group.update#

Disparado para qualquer mudanca em grupo. Persistido na tabela group_events.

json
{
  "group_jid": "120363025555555555@g.us",
  "group_name": "Vendas 2026",
  "group_subject": "Time comercial",
  "action": "participant_join",
  "sender": "554192464230@s.whatsapp.net",
  "timestamp": 1741360600,
  "value": "",
  "members": ["554199999999@s.whatsapp.net", "554188888888@s.whatsapp.net"]
}
Campo Tipo Descricao
group_jid string JID do grupo
group_name string Nome atual do grupo (cache). Em name_change reflete o novo nome já atualizado. Pode estar vazio se for a primeira vez que esse grupo aparece em um evento (ver Mensagens de Grupo)
group_subject string Topico/descricao atual do grupo (cache). Em topic_change reflete o novo topico
action string Tipo da mudanca (veja tabela abaixo)
sender string JID de quem fez a mudanca
sender_pn string JID de telefone equivalente quando sender e um LID (de events.GroupInfo.SenderPN). Vazio quando sender já e telefone ou o Meta não forneceu o par
join_reason string "invite" quando o participant_join veio de link de convite (em vez de admin-add). Vazio para admin-add e ações não-join
timestamp int64 Unix timestamp
value string Valor novo (nome, topico, picture_id)
members []string JIDs dos membros afetados

Ações possíveis:

Action Descricao value members
name_change Nome do grupo alterado Novo nome -
topic_change Descricao alterada Nova descricao -
participant_join Membros entraram - JIDs que entraram
participant_leave Membros sairam - JIDs que sairam
participant_promote Promovidos a admin - JIDs promovidos
participant_demote Rebaixados de admin - JIDs rebaixados
locked Apenas admins editam info - -
unlocked Todos editam info - -
announce Apenas admins enviam msgs - -
unannounce Todos enviam msgs - -
picture_change Foto do grupo alterada Picture ID -
picture_remove Foto do grupo removida - -
ephemeral_change Mensagens temporarias ativadas/desativadas Duração em segundos (0 = desativado) -
membership_approval_on Aprovacao de membros ativada - -
membership_approval_off Aprovacao de membros desativada - -
group_deleted Grupo foi excluido - -
group_linked Grupo foi vinculado a uma comunidade JID da comunidade -
group_unlinked Grupo foi desvinculado de uma comunidade JID da comunidade -
invite_link_reset Link de convite foi redefinido Novo link -
suspended Grupo foi suspenso pelo WhatsApp - -
unsuspended Grupo foi reativado pelo WhatsApp - -

<a id="mensagens-de-grupo"></a>

Mensagens de Grupo (semantica + cache)

Quando uma mensagem chega de um grupo, os campos do payload tem a seguinte semantica:

Campo DM (1:1) Grupo
chat JID do contato (@s.whatsapp.net) JID do grupo (@g.us)
from JID do contato JID do participante que enviou (resolvido para phone JID quando possível)
phone Telefone do contato Telefone do participante que enviou
push_name Nome do contato Nome do participante que enviou
is_group false true
group_name omitido Nome do grupo (cache, ver abaixo)
group_subject omitido Topico/descricao do grupo (cache, ver abaixo)

Padrão de renderizacao: Para mostrar uma mensagem de grupo no estilo WhatsApp Web, use group_name como titulo da conversa e push_name como autor do balao individual. chat e o identificador único da conversa de grupo (sempre termina em @g.us).

Cache de metadados de grupo (lazy):

group_name e group_subject são populados a partir de um cache em memória por instância. O cache funciona assim:

  1. Primeira mensagem de um grupo novo: o cache está vazio. O evento e emitido com group_name="" e group_subject="". Em paralelo, a Catcher dispara uma busca assincrona via GetGroupInfo para popular o cache.
  2. Mensagens subsequentes: o cache já tem o nome, entao todos os eventos do mesmo grupo virao com group_name e group_subject preenchidos.
  3. Eventos events.GroupInfo com name_change ou topic_change atualizam o cache imediatamente, antes mesmo de emitir o group.update correspondente.
  4. Logout/delete da instância limpa o cache para evitar leakage entre sessões.

Quais eventos incluem group_name / group_subject?

Evento group_name group_subject
message.received Sim Sim
message.sent Sim Sim
message.delivered Sim Sim
message.read Sim Sim
message.played Sim Sim
message.deleted Sim Sim
message.edited Sim Sim
group.update Sim Sim
group.joined Sim (group_name/group_topic já existiam) Sim

Fallback para grupos novos: Se o seu consumidor recebe um evento de grupo com group_name vazio, você pode chamar GET /v1/instances/{instanceId}/groups/{groupJid} para resolver o nome no momento (e isso já vai popular o cache para os próximos eventos).


contact.update#

Disparado quando a foto de perfil, nome ou status de um contato muda. Persistido na tabela contact_events.

Quando o contato e identificado por LID (Linked Device ID), o campo jid mostra o JID do telefone (se resolvido) e jid_lid preserva o LID original. Se o LID não puder ser resolvido, jid contera o LID e phone ficara vazio.

json
{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "action": "picture_change",
  "value": "j+rE",
  "timestamp": 1741360700
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio se LID não resolvido ou grupo)
jid string JID do contato (telefone resolvido quando possível)
jid_lid string LID original quando o JID foi resolvido de um LID (vazio se já era telefone)
action string Tipo da mudanca (veja tabela abaixo)
value string Valor novo (ID/hash da foto, novo nome, etc.)
old_value string Valor anterior (presente apenas para push_name_change e business_name_change)
timestamp int64 Unix timestamp
is_business bool O contato é uma conta comercial (WhatsApp Business; isBusiness da Meta). Provider wwebjs (desde 2026-10-31, promovido de extras), nas mudanças de nome/foto do próprio contato; false vem explícito. Omitido quando a Meta não manda o campo
is_enterprise bool O contato é uma conta comercial enterprise (API oficial; isEnterprise). Provider wwebjs (desde 2026-10-31); false vem explícito. Omitido quando a Meta não manda o campo
is_my_contact bool O contato está salvo na agenda deste número (isMyContact). Provider wwebjs (desde 2026-10-31); false vem explícito. Omitido quando a Meta não manda o campo
verified_level int Nível de verificação comercial (verifiedLevel: 0 nenhum, 1 baixo, 2 alto). Provider wwebjs (desde 2026-10-31); só inteiros 0–9. Omitido quando a Meta não manda o campo

Ações possíveis:

Action Descricao value old_value
picture_change Foto de perfil alterada Picture ID ou hash -
picture_remove Foto de perfil removida - -
about_change Status/about alterado Novo status -
push_name_change Nome de exibição alterado Novo nome Nome anterior
business_name_change Nome comercial alterado Novo nome Nome anterior

Avatar cache: Quando action e picture_change, a Catcher automaticamente baixa a nova foto do contato e armazena no S3/R2. Quando action e picture_remove, o cache e limpo. Clientes podem usar este evento para invalidar avatares em cache local e buscar a nova versão via GET /v1/instances/{instanceId}/contacts/{phone}/avatar.


instance.banned#

Disparado quando a instância recebe um ban temporario ou permanente do WhatsApp. Persistido nos campos ban_expiry e ban_reason da instância. Diferente de connection.update com status: "banned", este evento traz informações detalhadas do ban.

json
{
  "instance_id": "84c2e480-...",
  "permanent": false,
  "reason": "spam",
  "ban_expiry": 1741446000
}
Campo Tipo Descricao
instance_id string ID da instância banida
permanent bool true = ban permanente, false = temporario
reason string Motivo do ban (quando disponível)
ban_expiry int64/null Unix timestamp de quando o ban expira (null se permanente)

Nota: O evento connection.update com status: "banned" também e emitido. Use instance.banned quando precisar de detalhes do ban (permanencia, motivo, expiracao).


instance.offline / instance.critical_offline / instance.recovered#

Eventos do monitor de saúde (internal/health/monitor.go). Disparados quando uma instância cruza um dos thresholds de tempo offline:

  • instance.offline — instância desconectada ha 15min ou mais (transicao única do tier degraded para offline).
  • instance.critical_offline — instância desconectada ha 6h ou mais (transicao do tier offline para critical_offline). Também dispara email para o owner da empresa + todos os superadmins.
  • instance.recovered — instância voltou a conectar após ter ficado em offline/critical_offline (limpa o offline_alert_level).

Cada evento e disparado exatamente uma vez por transicao. O monitor armazena o nivel atual em offline_alert_level na linha da instância para evitar re-emissoes a cada scan (60s). Instâncias com desired_state=DISCONNECTED (pausadas manualmente) nunca disparam estes eventos.

json
{
  "instance_id": "84c2e480-...",
  "name": "EJ Whats",
  "phone": "554192464230",
  "tier": "critical_offline",
  "previous_tier": "offline",
  "status": "DISCONNECTED",
  "desired_state": "CONNECTED",
  "disconnected_at": "2026-04-06T21:44:00Z",
  "last_activity_at": "2026-04-06T21:42:18Z",
  "offline_duration_seconds": 158400,
  "offline_duration_human": "1d 20h",
  "reason": "",
  "timestamp": 1744156800
}
Campo Tipo Descricao
instance_id string ID da instância
name string Nome configurado da instância
phone string Telefone E.164 da instância (vazio se nunca conectou)
tier string Tier no momento da emissao: offline, critical_offline, healthy, stale, etc.
previous_tier string Tier antes da transicao (util para correlacionar)
status string Status WhatsApp bruto: CONNECTED, DISCONNECTED, etc.
desired_state string CONNECTED (queremos restaurar) ou DISCONNECTED (pausada)
disconnected_at string/null Timestamp ISO-8601 da primeira deteccao do drop. Preserva o tempo original em flapping.
last_activity_at string/null Último heartbeat (mensagem inbound, send outbound, ou receipt processado)
offline_duration_seconds int64 Duração calculada no momento da emissao
offline_duration_human string Versão formatada ("2d 4h", "30m") para display direto
reason string Conteúdo de last_error se houver
timestamp int64 Unix seconds da emissao

Configuração: Os thresholds (15min e 6h) são constantes no código (internal/health/tier.go) para garantir visibilidade em code review. Para tunar, edite OfflineThreshold e CriticalThreshold.

Endpoint relacionado: o rollup superadmin de saúde das instâncias retorna a visão cross-tenant em tempo real (usado pelo banner do dashboard, badge da sidebar, e card "Saúde das instâncias").

instance.critical_offline#

Mesmo payload de instance.offline / instance.critical_offline / instance.recovered; tier vem como critical_offline.

instance.recovered#

Mesmo payload de instance.offline / instance.critical_offline / instance.recovered; tier volta para o estado saudável/stale atual e previous_tier aponta para offline ou critical_offline.


message.undecryptable#

Disparado quando uma mensagem e recebida mas não pode ser decriptada pela instância. Isso pode acontecer quando a sessão de criptografia está dessincronizada ou quando a mensagem foi enviada para um dispositivo anterior. Não cria uma linha normal em messages, porque o conteúdo não foi aberto; o evento fica disponível em webhooks/SSE/WS e no histórico de eventos.

Correlação sem conteúdo decriptado — depende do provider: sem decriptacao não há conteúdo aberto, então a correlação e especial. No provider whatsmeow, message_ids carrega um UUID Catcher de placeholder (uma linha inbound sem conteúdo é persistida e reusada quando a mensagem se recupera), então o evento já segue o contrato UUID-only normal. No provider wwebjs, que não persiste placeholder, message_ids carrega o hex bruto do WhatsApp — este é o ÚNICO caso de hex bruto exposto na API. Nos dois, a chave nativa da mensagem não decriptada vem também em wa_message_id / wa_from_me / wa_remote_jid (ver "Id nativo do WhatsApp (wa_*)" em Identificadores).

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["af1c... (UUID placeholder no whatsmeow; hex bruto no wwebjs)"],
  "is_unavailable": true,
  "unavailable_type": "account_removed",
  "decrypt_fail_mode": "",
  "timestamp": 1741360800
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo
from string JID do remetente
chat string JID do chat
message_ids []string Array com 1 elemento. whatsmeow: UUID Catcher de placeholder (reusado no message.received quando a mensagem se recupera). wwebjs: hex bruto do WhatsApp (carve-out — sem placeholder, sem UUID).
is_unavailable bool true se a mensagem foi marcada como indisponível pelo servidor
unavailable_type string Tipo de indisponibilidade (ex: "account_removed", vazio se não aplicavel)
decrypt_fail_mode string Modo de falha da decriptacao (ex: "no_session", vazio se is_unavailable=true)
timestamp int64 Unix timestamp

message.decrypt_recovered#

Disparado quando uma mensagem que antes gerou message.undecryptable chega novamente e é decriptada com sucesso pelo retry automático do WhatsApp/whatsmeow. Exclusivo do provider whatsmeow (o wwebjs não expõe a família de recuperação de decriptacao). message_ids carrega o UUID Catcher do placeholder — o mesmo que o message.received recuperado reusa, permitindo a correlação.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["af1c8e40-1979-425e-b1ef-24ba4c9b67ad"],
  "status": "recovered",
  "recovery_ms": 831,
  "timestamp": 1741360801
}

message.decrypt_lost#

Disparado quando uma mensagem que gerou message.undecryptable não reaparece dentro da janela de retry. Esse evento indica perda real de conteúdo, não apenas ruído transitório. Exclusivo do provider whatsmeow. message_ids carrega o UUID Catcher do placeholder.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["af1c8e40-1979-425e-b1ef-24ba4c9b67ad"],
  "status": "lost",
  "ttl_secs": 300,
  "timestamp": 1741361100
}

Campos adicionais opcionais nos dois eventos: sender_name, is_group, group_name.


message.starred#

Disparado quando uma mensagem e marcada ou desmarcada com estrela. Evento de sincronização entre dispositivos; não persistido em tabela separada.

json
{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "starred": true,
  "is_from_me": false,
  "timestamp": 1741360850
}
Campo Tipo Descricao
chat string JID do chat
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado.
starred bool true = marcada com estrela, false = desmarcada
is_from_me bool Se a mensagem e da própria instância
timestamp int64 Unix timestamp

message.deleted_for_me#

Disparado quando uma mensagem e apagada localmente ("apagar para mim"), sem afetar os outros participantes. Diferente de message.deleted, que e "apagar para todos". Não persistido.

json
{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "is_from_me": false,
  "timestamp": 1741360900
}
Campo Tipo Descricao
chat string JID do chat
message_ids []string Array com 1 UUID interno do Catcher (v4) — leia message_ids[0]. Identificador único e estável, nunca reciclado.
is_from_me bool Se a mensagem era da própria instância
timestamp int64 Unix timestamp

Campos enriquecidos dos eventos call.* (provider wwebjs, 2026-06-26 — commit 567febd9). Além dos campos listados por evento, as chamadas do wwebjs carregam: from_lid (o @lid original do chamador, quando o device manda @lid), direction (inbound/outbound), outcome (string crua do WhatsApp: accepted/acceptedElsewhere/rejected/declined/missed/completed/timeout…), is_video (bool, sempre presente); e em call.received/call.group_offer: offer_time (unix do offer) + participants (grupo). A identidade do chamador resolve @lid→phone (paridade com message.received). Contrato 100% populado, exemplos por evento e caveats: docs/cartas/2026-06-26-call-events-completos.md. Caveat: chamadas atendidas num linked device não geram call.ended/duration (a conversa termina no telefone principal).

Histórico de chamadas no pareamento (wwebjs, 2026-10-06). Ao parear uma conta, o WhatsApp Web sincroniza o histórico de chamadas e cada registro antigo chega como desfecho (call.accepted/call.rejected/call.ended). Nesses eventos o timestamp é o horário real da chamada (antes era o momento da sincronização) e, quando a chamada tem mais de 6 h (WWEBJS_LIVE_BACKLOG_HORIZON_S), o evento traz historical: true + history_source: "history_sync". Chamadas recentes saem sem os dois campos, como sempre. Filtre por historical (ou pela idade do timestamp) para não tratar histórico como chamada acontecendo agora.

call.accepted#

Disparado quando uma chamada e aceita (pela parte remota ou em outro dispositivo pareado). Persistido na tabela call_logs.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "from_lid": "195718102958197@lid",
  "call_id": "CALL-ABC123",
  "direction": "inbound",
  "outcome": "accepted",
  "is_video": false,
  "timestamp": 1741360950
}
Campo Tipo Descricao
phone string Número de telefone do chamador (resolvido)
from string JID canônico do chamador
from_lid string @lid original do chamador (omitido quando já veio número)
call_id string ID único da chamada
direction string inbound (recebida) / outbound
outcome string accepted ou acceptedElsewhere
is_video bool Chamada de vídeo (sempre presente)
timestamp int64 Unix timestamp

call.rejected#

Disparado quando uma chamada e rejeitada pela parte remota. Persistido na tabela call_logs.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "from_lid": "195718102958197@lid",
  "call_id": "CALL-ABC123",
  "direction": "inbound",
  "outcome": "rejected",
  "is_video": false,
  "timestamp": 1741361000
}
Campo Tipo Descricao
phone string Número de telefone do chamador (resolvido)
from string JID canônico do chamador
from_lid string @lid original do chamador (omitido quando já veio número)
call_id string ID único da chamada
direction string inbound / outbound
outcome string rejected ou declined
is_video bool Chamada de vídeo (sempre presente)
timestamp int64 Unix timestamp

call.ended#

Disparado quando uma chamada e finalizada por qualquer motivo. Persistido na tabela call_logs.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "from_lid": "195718102958197@lid",
  "call_id": "CALL-ABC123",
  "direction": "inbound",
  "outcome": "missed",
  "reason": "missed",
  "is_video": false,
  "duration": 45,
  "timestamp": 1741361050
}
Campo Tipo Descricao
phone string Número de telefone do chamador (resolvido)
from string JID canônico do chamador
from_lid string @lid original do chamador (omitido quando já veio número)
call_id string ID único da chamada
direction string inbound / outbound
outcome string String crua do WhatsApp (espelha reason): missed/completed/timeout/busy/…
reason string Motivo do encerramento. Valores observados: "reject" (você recusou — também dispara call.declined_by_me), "timeout" (não atendeu), "" (caller desligou), "upgrade-needed" (versão do cliente desatualizada), entre outros. Lista abaixo da seção.
is_video bool Chamada de vídeo (sempre presente)
duration int Duração da chamada em segundos (0 se não atendida; omitido no wwebjs quando 0)
timestamp int64 Unix timestamp

call.declined_by_me#

Disparado quando você (instância) recusa uma chamada de entrada. Há duas origens distintas, distinguidas pelo campo source:

  1. Manual — o usuário tocou em recusar no app do WhatsApp do telefone pareado
  2. Automática — o toggle auto_reject_calls da instância estava ativo no momento da oferta

Por que existe este evento. No protocolo do WhatsApp NÃO há um frame dedicado para "usuário recusou no telefone". O sinal canônico no fio é o CallTerminate cujo atributo from flipa para o JID/LID do PRÓPRIO dispositivo que rejeitou (em vez do JID do chamador original). Em logs de produção, o reason desse terminate vem vazio ("") — não "reject" como Baileys documenta para casos legados. A Catcher detecta os dois sinais (self-JID/LID match OU reason="reject") e recupera o JID do chamador original via stash interno populado no CallOffer. O evento call.ended continua disparando em paralelo carregando o mesmo phone/from recuperado.

json
{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "source": "manual",
  "timestamp": 1741361050
}
Campo Tipo Descricao
phone string Número de telefone do chamador
from string JID do chamador
call_id string ID único da chamada
source string "manual" (recusa na UI do telefone) ou "auto" (toggle auto_reject_calls ativo)
timestamp int64 Unix timestamp

call.group_offer#

Disparado quando a instância recebe uma chamada de grupo. Persistido na tabela call_logs.

json
{
  "call_id": "CALL-GRP456",
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "from_lid": "195718102958197@lid",
  "direction": "inbound",
  "media": "audio",
  "type": "group",
  "participants": ["554191111111@c.us", "554192222222@c.us"],
  "offer_time": 1741361100,
  "is_video": false,
  "is_group": true,
  "timestamp": 1741361100
}
Campo Tipo Descricao
call_id string ID único da chamada
phone / from / from_lid string Identidade do criador da chamada (resolvida)
direction string inbound
media string Tipo de mídia: "audio" ou "video"
type string Sempre "group"
participants string[] JIDs dos participantes convidados
offer_time int64 Unix do offer
is_video / is_group bool Sempre presentes (is_group: true)
timestamp int64 Unix timestamp

group.joined#

Disparado quando a instância e adicionada a um grupo (por convite, link ou admin). Persistido na tabela group_events.

json
{
  "group_jid": "120363025555555555@g.us",
  "group_name": "Vendas 2026",
  "group_topic": "Canal de vendas da equipe",
  "reason": "invite",
  "sender": "554192464230@s.whatsapp.net",
  "timestamp": 1741361150
}
Campo Tipo Descricao
group_jid string JID do grupo
group_name string Nome do grupo
group_topic string Descricao/topico do grupo
reason string Motivo da entrada (ex: "invite", "link", "admin_add")
sender string JID de quem adicionou (quando disponível)
sender_pn string JID de telefone equivalente de sender quando ele e um LID. Vazio quando sender já e telefone ou o Meta não forneceu o par
timestamp int64 Unix timestamp

blocklist.update#

Disparado quando a lista de contatos bloqueados e alterada. Não persistido.

json
{
  "action": "modify",
  "changes": [
    {
      "phone": "554192464230",
      "jid": "554192464230@s.whatsapp.net",
      "action": "block"
    },
    {
      "phone": "554188322497",
      "jid": "554188322497@s.whatsapp.net",
      "jid_lid": "216251804708983@lid",
      "action": "unblock"
    }
  ],
  "timestamp": 1741361200
}
Campo Tipo Descricao
action string "set" (lista completa substituida) ou "modify" (alteração incremental)
changes array Lista de alterações
changes[].phone string Número de telefone sem sufixo
changes[].jid string JID do contato (telefone resolvido quando possível)
changes[].jid_lid string LID original quando resolvido de um LID
changes[].action string "block" ou "unblock"
timestamp int64 Unix timestamp

Nota: Quando action e "set", a lista changes representa a lista completa de contatos bloqueados (todos com action: "block"). Quando e "modify", cada item em changes pode ser "block" ou "unblock".


contact.identity_changed#

Disparado quando um contato troca de dispositivo principal (re-registrou o WhatsApp em outro celular). A chave de criptografia do contato mudou. Persistido na tabela contact_events.

json
{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "implicit": false,
  "timestamp": 1741361250
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo
jid string JID do contato (telefone resolvido quando possível)
jid_lid string LID original quando resolvido de um LID
implicit bool true se a mudanca foi detectada implicitamente (sem notificação do servidor), false se o servidor notificou explicitamente
timestamp int64 Unix timestamp

contact.sync#

Disparado quando um contato e sincronizado do dispositivo (agenda de contatos). Persistido na tabela contact_events.

json
{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "first_name": "Joao",
  "full_name": "Joao Silva",
  "timestamp": 1741361300
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo
jid string JID do contato
first_name string Primeiro nome do contato (da agenda)
full_name string Nome completo do contato (da agenda)
timestamp int64 Unix timestamp

chat.pin#

Disparado quando um chat e fixado ou desfixado. Evento de sincronização entre dispositivos. Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "pinned": true,
  "timestamp": 1741361350
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
pinned bool true = fixado, false = desfixado
timestamp int64 Unix timestamp

chat.archive#

Disparado quando um chat e arquivado ou desarquivado. Evento de sincronização entre dispositivos. Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "archived": true,
  "timestamp": 1741361400
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
archived bool true = arquivado, false = desarquivado
timestamp int64 Unix timestamp

chat.mute#

Disparado quando um chat e silenciado ou dessilenciado. Evento de sincronização entre dispositivos. Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "muted": true,
  "mute_end": 1741447800,
  "timestamp": 1741361450
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
muted bool true = silenciado, false = dessilenciado
mute_end int64 Unix timestamp de quando o silenciamento expira (0 se silenciado indefinidamente ou se muted=false)
timestamp int64 Unix timestamp

chat.read_state#

Disparado quando um chat e marcado como lido ou não lido. Emitido tanto por sincronização entre dispositivos (AppState) quanto pelas APIs POST /v1/instances/{id}/mark-read (com mark_all: true) e POST /v1/instances/{id}/mark-unread. Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "marked_as_read": false,
  "timestamp": 1741361500
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
marked_as_read bool true = marcado como lido, false = marcado como não lido
timestamp int64 Unix timestamp

Nota: Quando disparado via API (mark-read / mark-unread), o evento e emitido imediatamente após o SendAppState bem-sucedido, sem esperar o echo de sincronização do WhatsApp.


chat.clear#

Disparado quando um chat e limpo (histórico apagado). Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": false,
  "timestamp": 1741361550
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
delete_media bool true se a mídia também foi apagada
timestamp int64 Unix timestamp

chat.delete#

Disparado quando um chat e apagado completamente. Não persistido.

json
{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": true,
  "timestamp": 1741361600
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (vazio para grupos ou LID não resolvido)
chat string JID do chat (telefone resolvido quando possível)
chat_lid string LID original quando o chat foi resolvido de um LID
delete_media bool true se a mídia também foi apagada
timestamp int64 Unix timestamp

privacy.update#

Disparado quando as configurações de privacidade da instância são alteradas. Não persistido.

json
{
  "settings": {
    "group_add": "contacts",
    "last_seen": "everyone",
    "online": "match_last_seen",
    "profile": "contacts",
    "status": "contacts",
    "read_receipts": "enabled",
    "call_add": "known"
  },
  "changed_fields": ["group_add", "profile"],
  "timestamp": 1741361650
}
Campo Tipo Descricao
settings object Mapa de configurações de privacidade atuais (nome_config -> valor)
changed_fields []string Lista dos campos que foram alterados nesta atualização
timestamp int64 Unix timestamp

Configurações possíveis: group_add, last_seen, online, profile, status, read_receipts, call_add. Os valores dependem da configuração (ex: "everyone", "contacts", "nobody", "match_last_seen", "enabled", "disabled", "known").


history.sync#

Disparado quando uma sincronização de histórico e recebida do servidor WhatsApp (tipicamente após conectar um novo dispositivo ou após POST /history/import). As mensagens do blob são persistidas no histórico de conversas; o evento abaixo e o resumo da importação. Mensagens novas importadas também emitem message.received/message.sent por padrão, com historical=true e history_source="history_import".

json
{
  "sync_type": "RECENT",
  "conversation_count": 42,
  "message_count": 1500,
  "pushname_count": 38,
  "imported_count": 1480,
  "duplicate_count": 20,
  "skipped_count": 0,
  "failed_count": 0,
  "timestamp": 1741361700
}
Campo Tipo Descricao
sync_type string Tipo de sincronização (ex: "RECENT", "FULL", "PUSH_NAME")
conversation_count int Número de conversas sincronizadas
message_count int Número de mensagens sincronizadas
pushname_count int Número de push names sincronizados
imported_count int Mensagens históricas gravadas em messages
duplicate_count int Mensagens já existentes ignoradas por dedupe
skipped_count int Itens sem mensagem/chave válida ou ignorados
failed_count int Itens que falharam ao converter ou persistir
timestamp int64 Unix timestamp

Para importar sem eventos por mensagem, envie suppress_events=true em POST /history/import. Sem esse opt-out, o histórico entra no mesmo pipeline durável de eventos/webhooks das mensagens ao vivo.


sync.preview#

Disparado quando um preview de sincronização offline e recebido, indicando quantos eventos estão pendentes. Não persistido.

json
{
  "total": 250,
  "messages": 180,
  "receipts": 45,
  "notifications": 25,
  "timestamp": 1741361750
}
Campo Tipo Descricao
total int Total de eventos pendentes
messages int Número de mensagens pendentes
receipts int Número de receipts (entrega/leitura) pendentes
notifications int Número de notificações pendentes
timestamp int64 Unix timestamp

sync.app_state_error#

Disparado quando o whatsmeow reporta erro ao sincronizar uma coleção de AppState. E evento operacional para observabilidade: não cria mensagem, não representa perda confirmada de conversa e deve ser correlacionado com connection.update, métricas de AppState e logs do worker.

json
{
  "collection": "regular_high",
  "full_sync": false,
  "error": "failed to sync app state collection regular_high: ...",
  "timestamp": 1741361760
}
Campo Tipo Descricao
collection string Nome da coleção AppState reportada pelo whatsmeow
full_sync bool true quando o erro ocorreu durante full sync
error string Erro resumido e truncado para no máximo 512 caracteres
timestamp int64 Unix timestamp

media.retry_result#

Disparado quando o resultado de um retry de download de mídia e recebido. Quando a mídia de uma mensagem recebida não pode ser baixada inicialmente, o WhatsApp pode reenviar os bytes — este evento indica o resultado dessa tentativa. Não persistido.

json
{
  "message_ids": ["3EB0ABC123DEF456"],
  "chat": "554192464230@s.whatsapp.net",
  "success": true,
  "timestamp": 1741361800
}
Campo Tipo Descricao
message_ids []string Array com 1 elemento (message_ids[0]) contendo o UUID Catcher da mensagem cuja mídia foi retentada
chat string JID do chat
success bool true se o retry foi bem-sucedido
error_code int Código de erro (presente apenas quando success=false)
timestamp int64 Unix timestamp

label.edit#

Disparado quando uma etiqueta e criada, editada ou removida. Etiquetas são um recurso do WhatsApp Business. Não persistido.

json
{
  "label_id": "5",
  "name": "Urgente",
  "color": 1,
  "deleted": false,
  "timestamp": 1741361850
}
Campo Tipo Descricao
label_id string ID da etiqueta
name string Nome da etiqueta
color int Índice de cor da etiqueta (0-19 no WhatsApp Business)
deleted bool true se a etiqueta foi removida
timestamp int64 Unix timestamp

label.chat_association#

Disparado quando um chat e associado ou desassociado de uma etiqueta. Não persistido.

json
{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "phone": "554192464230",
  "associated": true,
  "timestamp": 1741361900
}
Campo Tipo Descricao
label_id string ID da etiqueta
chat string JID do chat
phone string Número de telefone sem sufixo (vazio para grupos)
associated bool true = chat etiquetado, false = chat desetiquetado
timestamp int64 Unix timestamp

label.message_association#

Disparado quando uma mensagem e associada ou desassociada de uma etiqueta. Não persistido.

json
{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "associated": true,
  "timestamp": 1741361950
}
Campo Tipo Descricao
label_id string ID da etiqueta
chat string JID do chat
message_ids []string Array com 1 elemento (message_ids[0]) contendo o UUID Catcher da mensagem etiquetada
associated bool true = mensagem etiquetada, false = mensagem desetiquetada
timestamp int64 Unix timestamp

message.acked#

Disparado quando outro dispositivo seu (sync multi-device) confirma recebimento de uma mensagem que você enviou. Distinto de message.delivered — aquele e o contato confirmando entrega; este e o seu próprio segundo aparelho. Não persistido (não carimba delivered_at na tabela messages).

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "acked",
  "timestamp": 1741360305,
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (mesma cadeia de fallback que message.delivered)
message_ids []string UUIDs internos do Catcher (v4) das mensagens outbound confirmadas
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID do dispositivo que confirmou (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
status string Sempre "acked"
timestamp int64 Unix timestamp
is_group bool Se o chat e um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.


message.read_other_device#

Disparado quando você le uma mensagem inbound em outro dispositivo seu. O contato não leu nada — e o seu próprio estado de leitura multi-device. Util para evitar re-notificar o operador de algo que ele já viu em outro aparelho. Não persistido (não carimba read_at, que e reservado para o receipt de leitura do contato sobre suas mensagens outbound).

json
{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "read_other_device",
  "timestamp": 1741360360,
  "is_group": false
}
Campo Tipo Descricao
phone string Número de telefone sem sufixo (mesma cadeia de fallback que message.delivered)
message_ids []string UUIDs internos do Catcher (v4) das mensagens inbound lidas
chat string JID do chat (resolvido para phone JID quando possível)
sender string JID do remetente da mensagem inbound (resolvido para phone JID quando possível)
chat_lid string LID original do chat, presente quando o WhatsApp usou LID internamente
sender_lid string LID original do sender, presente quando o WhatsApp usou LID internamente
status string Sempre "read_other_device"
timestamp int64 Unix timestamp
is_group bool Se o chat e um grupo
group_name string Nome do grupo. Presente apenas quando is_group=true e o cache já foi populado (ver Mensagens de Grupo)
group_subject string Topico/descricao do grupo. Presente apenas quando is_group=true e o cache já foi populado

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.


connection.diagnostic#

Timeline fina do ciclo de conexão — emitido em pontos-chave do ConnectInstance do worker (dialing, QR emitido, WebSocket fechado, etc.). Usado pela modal de QR do frontend para mostrar exatamente o que está acontecendo em tempo real. Não persistido. Carrega apenas dados seguros (IP do proxy, sinais de ciclo de vida do whatsmeow, mensagens curtas) — nunca URLs de CDN do Meta, telefones de terceiros ou conteúdo de mensagem.

json
{
  "step": "qr_emitted",
  "level": "info",
  "message": "QR Code gerado, aguardando leitura",
  "detail": {
    "proxy_city": "sao-paulo"
  },
  "timestamp": 1741360100
}
Campo Tipo Descricao
step string Slug estável do momento do ciclo de vida. Vocabulario: connect_start, proxy_bound, dialing, websocket_opened, qr_emitted, pair_device_received, pair_success, pair_error, connected, disconnected, websocket_closed, logged_out, connect_failure, stream_replaced, temp_ban, keepalive_timeout, keepalive_restored, reconnecting, flap_detected, manual_disconnect, quarantine_applied
level string info, success, warning ou error — controla a cor do badge na UI
message string Resumo de uma linha em pt-BR, legivel por humano
detail object Contexto estruturado opcional (IP do proxy, motivo da falha, etc.)
timestamp int64 Unix timestamp

contacts.bulk_imported#

Disparado quando o worker absorve um roster de contatos em massa de uma so vez — hoje apenas no HistorySync de INITIAL_BOOTSTRAP que segue um pareamento novo. CRMs podem usar isso como um único sinal "usuário acabou de parear, aqui estão os contatos" em vez de esperar o registro preencher incrementalmente. Não persistido como evento (os contatos em si vao para a tabela contacts).

json
{
  "source": "history_sync_initial_bootstrap",
  "imported": 312,
  "skipped": 4,
  "timestamp": 1741361000
}
Campo Tipo Descricao
source string Caminho do bulk-import. Hoje sempre "history_sync_initial_bootstrap"; reservado para caminhos futuros
imported int Quantidade de contatos absorvidos
skipped int Quantidade de contatos ignorados (já conhecidos ou inválidos). Omitido quando 0
timestamp int64 Unix timestamp

sync.offline_completed#

Disparado quando o whatsmeow termina de absorver eventos perdidos que chegaram durante uma janela de Disconnected. count > 0 significa que houve um gap real de entrega — a instância agora tem dados novos que o consumer não viu em tempo real. count == 0 significa que a reconexao cobriu o gap sem tráfego perdido (saudável). Não persistido.

json
{
  "count": 7,
  "timestamp": 1741361050
}
Campo Tipo Descricao
count int Número de eventos perdidos absorvidos. 0 = reconexao sem gap
timestamp int64 Unix timestamp

connection.recovered_quick#

Disparado quando um Connected segue um Disconnected dentro de uma janela curta (~60s). Distinto de instance.recovered, que exige >=15min de offline observavel. Util para dashboards que querem rastrear ruido de estabilidade de conexão separadamente de outages reais. Não persistido.

json
{
  "duration_seconds": 12.4,
  "timestamp": 1741361080
}
Campo Tipo Descricao
duration_seconds float64 Quanto tempo a instância ficou desconectada antes de voltar
timestamp int64 Unix timestamp

Payloads adicionais de eventos#

Os eventos abaixo também fazem parte de AllEventTypes. Os exemplos usam o envelope real {type,data} e os campos vêm dos *Data structs em whats-shared/pkg/realtime/event.go.

status.received#

Campos: phone, from, status_message_id, type, content, media_id, mime_type, has_media, timestamp. media_id só vem com status_media_download=true; senão has_media: true indica mídia a baixar sob demanda (POST .../status/{statusId}/media).

json
{ "type": "status.received", "data": { "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "status_message_id": "3EB0STATUS", "type": "text", "content": "Aberto hoje", "timestamp": 1741361650 } }

status.viewed#

Campos: phone, from, status_message_id, status_type, receipt_type, timestamp.

json
{ "type": "status.viewed", "data": { "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "status_message_id": "550e8400-e29b-41d4-a716-446655440000", "status_type": "image", "receipt_type": "read", "timestamp": 1741361650 } }

status.reaction#

Campos: phone, from, push_name, status_message_id, status_type, emoji, removed, timestamp.

json
{ "type": "status.reaction", "data": { "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "push_name": "Joao", "status_message_id": "550e8400-e29b-41d4-a716-446655440000", "status_type": "image", "emoji": "👍", "removed": false, "timestamp": 1741361650 } }

status.reply#

Campos: phone, from, push_name, status_message_id, status_type, reply_message_id, reply_type, content, media_id, timestamp.

json
{ "type": "status.reply", "data": { "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "push_name": "Joao", "status_message_id": "550e8400-e29b-41d4-a716-446655440000", "reply_message_id": "550e8400-e29b-41d4-a716-446655440001", "reply_type": "text", "content": "Gostei", "timestamp": 1741361650 } }

message.pin_sent#

Campos: chat, phone, target_message_id, pin, duration_seconds, target_from_me, timestamp.

json
{ "type": "message.pin_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "target_message_id": "550e8400-e29b-41d4-a716-446655440000", "pin": true, "duration_seconds": 86400, "target_from_me": true, "timestamp": 1741361650 } }

message.poll_vote_sent#

Campos: chat, phone, poll_message_id, selected_options, poll_from_me, timestamp.

json
{ "type": "message.poll_vote_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "poll_message_id": "550e8400-e29b-41d4-a716-446655440000", "selected_options": ["sim"], "poll_from_me": false, "timestamp": 1741361650 } }

message.star_sent#

Campos: chat, phone, message_id, starred, from_me, timestamp.

json
{ "type": "message.star_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "message_id": "550e8400-e29b-41d4-a716-446655440000", "starred": true, "from_me": true, "timestamp": 1741361650 } }

message.read_sent#

Campos: chat, phone, message_ids, count, timestamp.

json
{ "type": "message.read_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "count": 1, "timestamp": 1741361650 } }

Reply interativo recebido (button_reply.received / list_reply.received / interactive_reply.received)#

Contato clicou em botão, lista ou native-flow. É o message.received da família correspondente, com a seleção estruturada em data.detail (reply_type, selected_id, selected_display_text, selected_index, selected_carousel_card_index, title, description, native_flow_name, native_flow_params_json). O antigo evento dedicado message.interactive_reply_received foi aposentado em 2026-08-02.

json
{ "type": "button_reply.received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "message_type": "button_reply", "content": "Agendar avaliacao", "detail": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "reply_type": "button_reply", "selected_id": "schedule", "selected_display_text": "Agendar avaliacao", "selected_index": 1, "timestamp": 1741361650 }, "is_group": false, "timestamp": 1741361650 } }

message.interactive_reply_sent#

Eco outbound de clique interativo feito pela instância/outro dispositivo. Mesmos campos do detail do reply interativo recebido, trocando sender por to.

json
{ "type": "message.interactive_reply_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "to": "554137984905@s.whatsapp.net", "reply_type": "list_reply", "selected_id": "hifu-face", "title": "Hifu facial", "timestamp": 1741361650 } }

instance.no_proxy_blocked#

Campos: reason, detail, blocked_at, desired_state.

json
{ "type": "instance.no_proxy_blocked", "data": { "reason": "proxy_required", "detail": "instance has no proxy binding", "blocked_at": "2026-05-21T12:00:00Z", "desired_state": "DISCONNECTED" } }

instance.no_proxy_available#

O sibling NÃO-terminal do instance.no_proxy_blocked. Dispara quando uma instância NÃO-pareada chega no connect sem um IP saudável (o IP bindado está morto-pra-Meta, OU não há binding e o pool está vazio). Diferente do no_proxy_blocked, desired_state permanece connected: a plataforma auto-provisiona um IP novo validado (broker + WA-probe) e re-enfileira o connect automaticamente — gerou QR → mantém; não gerou → descarta e provisiona outro (budget-limitado). Uma instância pareada NUNCA dispara isso (o IP é fixo pela vida da sessão). Campos: reason (proxy_unhealthy | pool_exhausted), detail, phone (opcional), requested_at, desired_state (sempre connected).

json
{ "type": "instance.no_proxy_available", "data": { "reason": "proxy_unhealthy", "detail": "Sem IP saudável pra parear — aguardando provisionamento automático de um IP novo validado (WA-probe).", "phone": "554199998888", "requested_at": 1782000000, "desired_state": "connected" } }

contact.block_sent#

Campos: phone, jid, timestamp.

json
{ "type": "contact.block_sent", "data": { "phone": "554137984905", "jid": "554137984905@s.whatsapp.net", "timestamp": 1741361650 } }

contact.saved_sent#

Emitido depois de PUT .../contacts/{phone} salvar ou renomear um contato na agenda (wwebjs). Não é emitido quando o nome já era o mesmo (unchanged). Campos: phone, jid, first_name, last_name (ausente se vazio), full_name, sync_to_phone, existed, timestamp.

json
{ "type": "contact.saved_sent", "data": { "phone": "554137984905", "jid": "554137984905@s.whatsapp.net", "first_name": "Ana", "last_name": "Souza", "full_name": "Ana Souza", "sync_to_phone": true, "existed": true, "timestamp": 1741361650 } }

contact.deleted_sent#

Emitido depois de DELETE .../contacts/{phone} apagar um contato da agenda (wwebjs). phone é o número apagado (sempre o pedido). Campos: phone, jid, timestamp.

json
{ "type": "contact.deleted_sent", "data": { "phone": "554137984905", "jid": "554137984905@s.whatsapp.net", "timestamp": 1741361650 } }

sticker.favorite_sent#

Emitido depois de PUT/DELETE .../stickers/{stickerId}/favorite mudar o estado (wwebjs). Não sai quando já estava nesse estado. Campos: sticker_id, favorite, timestamp.

json
{ "type": "sticker.favorite_sent", "data": { "sticker_id": "u54VDNCJI_CFB-v0h6TIIvmiRoeLnlGCT_TPv9IHVSI", "favorite": true, "timestamp": 1741361650 } }

quick_reply.saved_sent#

Emitido depois de POST .../quick-replies (created: true) ou PATCH .../quick-replies/{quickReplyId} (created: false) salvar uma resposta rápida pela tela do WhatsApp Web (wwebjs). Não sai quando nada mudou. Campos: quick_reply_id, shortcut, message, created, timestamp.

json
{ "type": "quick_reply.saved_sent", "data": { "quick_reply_id": "1794852243", "shortcut": "horario", "message": "Atendemos de segunda a sexta, das 9h às 18h.", "created": true, "timestamp": 1741361650 } }

quick_reply.deleted_sent#

Emitido depois de DELETE .../quick-replies/{quickReplyId} (wwebjs). Campos: quick_reply_id, shortcut, timestamp.

json
{ "type": "quick_reply.deleted_sent", "data": { "quick_reply_id": "1794852243", "shortcut": "horario", "timestamp": 1741361650 } }

contact.unblock_sent#

Campos: phone, jid, timestamp.

json
{ "type": "contact.unblock_sent", "data": { "phone": "554137984905", "jid": "554137984905@s.whatsapp.net", "timestamp": 1741361650 } }

contact.presence_subscribed#

Campos: phone, jid, timestamp.

json
{ "type": "contact.presence_subscribed", "data": { "phone": "554137984905", "jid": "554137984905@s.whatsapp.net", "timestamp": 1741361650 } }

profile.name_changed_sent#

Campos: new_name, timestamp.

json
{ "type": "profile.name_changed_sent", "data": { "new_name": "Empresa LTDA", "timestamp": 1741361650 } }

profile.picture_changed_sent#

Campos: bytes_uploaded, timestamp.

json
{ "type": "profile.picture_changed_sent", "data": { "bytes_uploaded": 43821, "timestamp": 1741361650 } }

chat.unread_sent#

Campos: chat, phone, timestamp.

json
{ "type": "chat.unread_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "timestamp": 1741361650 } }

chat.archive_sent#

Arquivei/desarquivei o chat via API. Campos: chat, phone, archived, timestamp.

json
{ "type": "chat.archive_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "archived": true, "timestamp": 1741361650 } }

chat.pin_sent#

Fixei/desfixei o chat via API. Campos: chat, phone, pinned, timestamp.

json
{ "type": "chat.pin_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "pinned": true, "timestamp": 1741361650 } }

chat.mute_sent#

Silenciei/dessilenciei o chat via API. Campos: chat, phone, muted, mute_end, timestamp. mute_end=0 significa mute indefinido ou chat dessilenciado.

json
{ "type": "chat.mute_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "muted": true, "mute_end": 1741966450, "timestamp": 1741361650 } }

chat.disappearing_timer_sent#

Defini o timer de mensagens temporárias do chat (0/24h/7d/90d). Campos: chat, phone, duration_seconds, timestamp.

json
{ "type": "chat.disappearing_timer_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "duration_seconds": 604800, "timestamp": 1741361650 } }

chat.disappearing_timer#

WhatsApp sinalizou alteração do timer de mensagens temporárias em um chat. Campos: chat, chat_lid, phone, sender, sender_lid, is_group, duration_seconds, ephemeral_setting_timestamp, source, timestamp.

json
{ "type": "chat.disappearing_timer", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "duration_seconds": 604800, "ephemeral_setting_timestamp": 1741361650, "source": "protocol", "timestamp": 1741361650 } }

chat.clear_sent#

Limpei as mensagens do chat (mantendo o chat na lista). Campos: chat, phone, timestamp.

json
{ "type": "chat.clear_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "timestamp": 1741361650 } }

chat.delete_sent#

Deletei o chat inteiro (removido da lista). Campos: chat, phone, timestamp.

json
{ "type": "chat.delete_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "timestamp": 1741361650 } }

status.reply_sent#

Respondi (comentei) o status de um contato. Campos: chat (1:1 do autor, onde caiu a resposta), phone, status_message_id (hex WhatsApp do status respondido), type (text), timestamp.

json
{ "type": "status.reply_sent", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "status_message_id": "3EB0STATUS", "type": "text", "timestamp": 1741361650 } }

presence.broadcast_sent#

Campos: presence_type, chat, phone, timestamp.

json
{ "type": "presence.broadcast_sent", "data": { "presence_type": "available", "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "timestamp": 1741361650 } }

settings.unarchive_chats#

Configuração global "manter chats arquivados" alterada em outro dispositivo. Campos: unarchive_chats, timestamp.

json
{ "type": "settings.unarchive_chats", "data": { "unarchive_chats": true, "timestamp": 1741361650 } }

group.create_sent#

Campos: group_jid, name, participants_jids, participant_count, timestamp.

json
{ "type": "group.create_sent", "data": { "group_jid": "120363012345678901@g.us", "name": "Equipe Vendas", "participants_jids": ["554137984905@s.whatsapp.net"], "participant_count": 1, "timestamp": 1741361650 } }

group.name_changed_sent#

Campos: group_jid, new_name, timestamp.

json
{ "type": "group.name_changed_sent", "data": { "group_jid": "120363012345678901@g.us", "new_name": "Novo Nome", "timestamp": 1741361650 } }

group.description_changed_sent#

Campos: group_jid, new_description, timestamp.

json
{ "type": "group.description_changed_sent", "data": { "group_jid": "120363012345678901@g.us", "new_description": "Nova descricao", "timestamp": 1741361650 } }

group.picture_changed_sent#

Campos: group_jid, bytes_uploaded, timestamp.

json
{ "type": "group.picture_changed_sent", "data": { "group_jid": "120363012345678901@g.us", "bytes_uploaded": 43821, "timestamp": 1741361650 } }

group.participants_add_sent#

Campos: group_jid, action, requested_jids, successful_jids, failed_jids, timestamp.

json
{ "type": "group.participants_add_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "add", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.participants_remove_sent#

Campos iguais a group.participants_add_sent, com action="remove".

json
{ "type": "group.participants_remove_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "remove", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.participants_promote_sent#

Campos iguais a group.participants_add_sent, com action="promote".

json
{ "type": "group.participants_promote_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "promote", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.participants_demote_sent#

Campos iguais a group.participants_add_sent, com action="demote".

json
{ "type": "group.participants_demote_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "demote", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.participants_approved_sent#

Campos iguais a group.participants_add_sent, com action="approve".

json
{ "type": "group.participants_approved_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "approve", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.participants_rejected_sent#

Campos iguais a group.participants_add_sent, com action="reject".

json
{ "type": "group.participants_rejected_sent", "data": { "group_jid": "120363012345678901@g.us", "action": "reject", "requested_jids": ["554137984905@s.whatsapp.net"], "successful_jids": ["554137984905@s.whatsapp.net"], "failed_jids": [], "timestamp": 1741361650 } }

group.settings_sent#

Campos: group_jid, announce, locked, timestamp.

json
{ "type": "group.settings_sent", "data": { "group_jid": "120363012345678901@g.us", "announce": true, "locked": false, "timestamp": 1741361650 } }

Campos: group_jid, new_link, timestamp.

json
{ "type": "group.invite_link_revoked_sent", "data": { "group_jid": "120363012345678901@g.us", "new_link": "https://chat.whatsapp.com/AbCdEfGhIjKl", "timestamp": 1741361650 } }

group.join_sent#

Campos: group_jid, invite_code, timestamp.

json
{ "type": "group.join_sent", "data": { "group_jid": "120363012345678901@g.us", "invite_code": "AbCdEfGhIjKl", "timestamp": 1741361650 } }

group.leave_sent#

Campos: group_jid, timestamp.

json
{ "type": "group.leave_sent", "data": { "group_jid": "120363012345678901@g.us", "timestamp": 1741361650 } }

instance.deleted#

Campos: instance_id, phone, timestamp.

json
{ "type": "instance.deleted", "data": { "instance_id": "84c2e480-...", "phone": "554137984905", "timestamp": 1741361650 } }

history.import_started#

Disparado quando uma importação de histórico foi solicitada e os pedidos de sincronização foram enviados ao servidor WhatsApp. O conteúdo chega depois, de forma assíncrona, via history.sync. Payload = o resumo da solicitação (HistoryImportResponse). Campos: instance_id, status (requested), chat_jid (omitido = todos os chats), limit, requested_chats, requested_messages.

json
{ "type": "history.import_started", "data": { "instance_id": "84c2e480-...", "status": "requested", "chat_jid": "5511999999999@s.whatsapp.net", "limit": 500, "requested_chats": 12, "requested_messages": 6000 } }

history.import_skipped#

Disparado quando a importação solicitada NÃO pôde ser enviada: nenhum âncora de mensagem encontrado para os chats alvo, ou todos os pedidos de sincronização falharam. Mesmo shape do history.import_started, com status = skipped e message explicando o motivo. Campos: instance_id, status (skipped), chat_jid, limit, requested_chats, skipped_chats, message.

json
{ "type": "history.import_skipped", "data": { "instance_id": "84c2e480-...", "status": "skipped", "limit": 500, "requested_chats": 0, "skipped_chats": 0, "message": "no stored message anchors found for history import" } }

history.import_completed#

Campos: imported_count, limit, duration_ms, timestamp.

json
{ "type": "history.import_completed", "data": { "imported_count": 342, "limit": 500, "duration_ms": 1842, "timestamp": 1741361650 } }

Pin recebido (pin_chat.received / unpin_chat.received)#

Contato fixou/desafixou uma mensagem. É o message.received da família pin_chat/unpin_chat, com target_from_me achatado no topo e a estrutura em data.detail (target_message_id = UUID Catcher da mensagem fixada, sender_timestamp_ms). Os antigos dedicados message.pinned/message.unpinned foram aposentados em 2026-08-02.

json
{ "type": "pin_chat.received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "message_type": "pin_chat", "content": "", "target_from_me": true, "detail": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "target_message_id": "0d1f6f2a-6a3b-4b0e-9a6a-2f9f2b7c1234", "target_from_me": true, "sender_timestamp_ms": 1741361650123, "timestamp": 1741361650 }, "is_group": false, "timestamp": 1741361650 } }

Voto de enquete recebido (poll_vote.received)#

É o message.received da família poll_vote (sem linha de mensagem — message_ids: []), com target_from_me = "a enquete é sua?" achatado no topo e a estrutura em data.detail (poll_message_id = UUID Catcher da enquete, poll_from_me, voter; no provider wwebjs também selected_options com os nomes das opções decriptadas). O antigo dedicado message.poll_vote_received foi aposentado em 2026-08-02.

json
{ "type": "poll_vote.received", "data": { "chat": "120363012345678901@g.us", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": [], "message_type": "poll_vote", "content": "", "detail": { "chat": "120363012345678901@g.us", "phone": "554137984905", "voter": "554137984905@s.whatsapp.net", "is_group": true, "poll_message_id": "0d1f6f2a-6a3b-4b0e-9a6a-2f9f2b7c1234", "timestamp": 1741361650 }, "is_group": true, "timestamp": 1741361650 } }

Reação recebida (reaction.received)#

É o message.received da família reaction, totalmente achatado — sem detail: content = emoji (vazio = reação removida), reaction_target_id = UUID Catcher da mensagem reagida, target_from_me. O antigo dedicado message.reaction_received foi aposentado em 2026-08-02. No canal oficial (Meta Cloud) a reação não vira linha de mensagem, então message_ids vem [].

json
{ "type": "reaction.received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": ["a1939ba6-df53-4db5-adcd-e50f6a72a14e"], "message_type": "reaction", "content": "👍", "reaction_target_id": "616b9be1-334c-4c8e-bbda-41c1f8c029bf", "target_from_me": true, "is_group": false, "timestamp": 1741361650 } }

Produto recebido (product.received)#

É o message.received da família product, com a estrutura em data.detail (product_id, business_owner_jid, title). O antigo dedicado message.product_received foi aposentado em 2026-08-02.

json
{ "type": "product.received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "message_type": "product", "content": "", "detail": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "product_id": "prod_123", "business_owner_jid": "554100000000@s.whatsapp.net", "title": "Produto", "timestamp": 1741361650 }, "is_group": false, "timestamp": 1741361650 } }

Pedido recebido (order.received)#

O cliente montou o carrinho no catálogo e enviou o pedido. É o message.received da família order (evento operacional — sem linha de mensagem armazenada, message_ids: []), com content = a nota do comprador e a estrutura em data.detail. O antigo dedicado message.order_received foi aposentado em 2026-08-02.

Campos do detail: chat, phone, sender, is_group, order_id, catalog_id, merchant_jid, title, status, catalog_type, thumbnail_media_id, text, items[], item_count, total_amount_1000, currency, timestamp. Cada item de items[] traz product_retailer_id, product_id, name, quantity, item_price_1000, currency e image_media_id (foto do produto como Media — GET /v1/instances/{id}/media/{mediaId}; só wwebjs) (todos opcionais exceto product_retailer_id, que pode vir vazio). Campo ausente = o canal não entregou; nunca inventado (total 0 = preço oculto no catálogo → omitido).

  • title — título do carrinho (OrderMessage.orderTitle, normalmente o nome do catálogo da empresa). Não-oficial (whatsmeow + wwebjs).
  • status — inquiry | accepted | declined (OrderMessage.status). Não-oficial.
  • catalog_type — tipo do catálogo no WA Web (ex.: native). Só wwebjs.
  • thumbnail_media_id — a imagem do carrinho (vem como bytes JPEG no fio) guardada como Media da BiaZap; baixe por GET /v1/instances/{id}/media/{mediaId}. Nunca uma URL da Meta. Só wwebjs.
  • items[] no wwebjs: ao receber o pedido o worker faz UMA consulta de detalhes (orderId + token, a mesma que o WhatsApp Web faz quando a empresa toca "Ver pedido"; sai pela sessão da instância, dentro do túnel). UMA consulta, timeout 6s, só no caminho ao vivo: se falhar, o evento sai com o rollup e sem items. Preço oculto no catálogo → item_price_1000 omitido (o item vem com name + quantity).
  • items[].image_media_id no wwebjs: a consulta devolve a foto do produto como URL do CDN da Meta; o worker a baixa pelo proxy da instância (200×200, até 10 itens, 15s no total por pedido), confere que é imagem e guarda como Media. A URL da Meta nunca cruza o fio. Foto que falha = item sem a chave. image_url do produto NÃO é repassado (URL da Meta). O token do pedido nunca cruza o fio.
  • No wwebjs o pedido tem linha de mensagem: message_ids traz o UUID Catcher (o exemplo abaixo é do canal oficial).
json
{ "type": "order.received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "from": "554137984905@s.whatsapp.net", "message_ids": [], "message_type": "order", "content": "quero esses dois", "detail": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "catalog_id": "CAT77", "text": "quero esses dois", "items": [ { "product_retailer_id": "SKU-CAMISA-M", "quantity": 2, "item_price_1000": 19900, "currency": "BRL" }, { "product_retailer_id": "SKU-BONE", "quantity": 1, "item_price_1000": 5000, "currency": "BRL" } ], "item_count": 2, "total_amount_1000": 44800, "currency": "BRL", "timestamp": 1741361650 }, "is_group": false, "timestamp": 1741361650 } }

Exemplo real (provider wwebjs, pedido de 2026-09-26 na EJ Estética; preço oculto no catálogo, por isso sem total_amount_1000/item_price_1000):

json
{ "type": "order.received", "data": { "chat": "557999957289@s.whatsapp.net", "phone": "557999957289", "from": "557999957289@s.whatsapp.net", "sender_lid": "115951282458861@lid", "push_name": "Vanuza", "message_ids": ["d1fe2b7d-b4bf-4823-b74c-eb37c3d5fcb4"], "message_type": "order", "content": "", "detail": { "chat": "557999957289@s.whatsapp.net", "phone": "557999957289", "sender": "557999957289@s.whatsapp.net", "is_group": false, "order_id": "2035317233795658", "title": "Franciele - EJ Estética Avançada", "status": "inquiry", "catalog_type": "native", "item_count": 1, "merchant_jid": "273293080838230@lid", "thumbnail_media_id": "<uuid da Media>", "items": [ { "product_retailer_id": "", "product_id": "6996377647114372", "name": "Sulco Nasogeniano - Bigode Chinês", "quantity": 1, "image_media_id": "<uuid da Media>" } ], "timestamp": 1790414541 }, "is_group": false, "timestamp": 1790414541 } }

Diferenças entre os canais (honestidade de contrato):

  • items[]: canal oficial sempre; wwebjs quando a consulta de detalhes responde; whatsmeow nunca. O proto OrderMessage carrega apenas o rollup — order_id, item_count, total_amount_1000 — e não tem a lista de itens no fio (Baileys: mesma limitação; os itens exigem a consulta getOrderDetails(orderId, token), que o worker whatsmeow ainda não faz).
  • order_id só existe no canal NÃO-oficial. O webhook order da Cloud API não traz identidade própria de pedido (só o wamid da mensagem, que nunca cruza o fio pelo contrato UUID-only). No canal oficial, correlacione por (phone, timestamp, items).
  • catalog_id vem do canal oficial. Antes desta versão ele era emitido erroneamente dentro de order_id — se você usava order_id como chave de deduplicação no canal oficial, migre para catalog_id + items.

message.decrypt_retry_pending#

Campos: chat, phone, sender, is_group, message_id, is_unavailable, unavailable_type, decrypt_fail_mode, started_at, retry_deadline, retry_window_seconds.

Exclusivo do provider whatsmeow. message_id e o UUID Catcher do placeholder persistido quando a mensagem chegou indecriptável — o mesmo UUID que o message.received recuperado reusa, permitindo a correlação (contrato UUID-only, lições #22/#30). O wwebjs não expõe esta família de recuperação.

json
{ "type": "message.decrypt_retry_pending", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "message_id": "af1c8e40-1979-425e-b1ef-24ba4c9b67ad", "is_unavailable": true, "unavailable_type": "unavailable", "decrypt_fail_mode": "retry", "started_at": "2026-05-21T12:00:00Z", "retry_deadline": "2026-05-21T12:02:00Z", "retry_window_seconds": 120 } }

session.recreated#

Campos: peer_jid, phone, retry_count, reason, timestamp.

json
{ "type": "session.recreated", "data": { "peer_jid": "554137984905@s.whatsapp.net", "phone": "554137984905", "retry_count": 2, "reason": "retry_count_high", "timestamp": 1741361650 } }

message.delivery_failed#

Campos: chat, phone, message_ids, message_id, idempotency_key, task_id, message_type, reason, wire_state, last_error, attempt_count, timestamp.

wire_state responde a única pergunta que o consumidor não consegue responder sozinho: "não saiu" é FATO ou é o nosso melhor palpite?

wire_state Significado O que fazer
not_sent (padrão) Provado: o envio nunca chegou ao WhatsApp. O destinatário não tem a mensagem. Reenviar é seguro.
unknown Não sabemos: a tentativa terminou sem resposta conclusiva e a mensagem PODE ter chegado. Reconcilie antes de reenviar (GET /v1/instances/{instanceId}/message/{messageId}). sent é estado local e não prova saída no wwebjs; recibo delivered/read/played ou confirmação no destinatário prova recebimento. Sem essa evidência, o resultado continua desconhecido.

unknown também vem com reason=send_not_confirmed (provider wwebjs): o ack da mensagem no chat continua em 0 após a janela de observação e a linha vira failed. A checagem padrão é de 3 minutos; mídia espera duas observações sem avanço de estágio (normalmente 6 minutos), e upload ativo pode aguardar até 20 minutos. Proxy/socket indisponível e reconexão recente adiam a decisão. Se a página não puder ser lida, o worker tenta novamente dentro da janela; ao esgotá-la consulta primeiro o recibo durável da mesma mensagem outbound no mesmo destinatário. Entrega/leitura já confirmada encerra a observação, mesmo após exclusão; deleted sem recibo não presume entrega. Sem prova durável, emite connection.diagnostic com step=send_confirmation_unknown, sem declarar falha nem reciclar a página por essa incerteza. Se um recibo chegar depois, a linha volta a avançar normalmente. Fora esse caso, unknown é raro e tem exatamente duas origens, ambas do transporte interno (worker), nunca do WhatsApp: (a) o worker parou de esperar uma chamada in-page e não conseguiu abortá-la (SEND_OUTCOME_UNKNOWN); (b) a nossa própria chamada HTTP ao worker estourou o timeout enquanto ele ainda podia estar enviando. Todo o resto é not_sent — inclusive reason=timeout de origem WhatsApp, porque a chamada in-page é abortada antes de poder despachar.

reason diz POR QUE falhou; wire_state diz O QUE o consumidor pode assumir sobre o chat do destinatário. Os dois são independentes: o mesmo reason=timeout pode vir com wire_state=not_sent (abortado in-page) ou unknown (o nosso transporte desistiu primeiro). message_ids (array de UUID Catcher) é a forma canônica — a MESMA de todo evento de mensagem; use-a para correlacionar. message_id (singular) permanece com o mesmo valor por compatibilidade. Quando o id não pôde ser resolvido, message_ids vem vazio ([]) — nunca [""]. Toda falha terminal deixa a linha em messages com status=failed e o fail_reason, sob o MESMO UUID que o 202 devolveu — inclusive um envio que nunca chegou a ser despachado (expiração da janela de validade, retry esgotado). Ou seja: GET /v1/instances/{instanceId}/chats/{chatId}/messages e GET /v1/instances/{instanceId}/message/{messageId} sempre reconciliam o evento. message_type reflete o tipo REAL da mensagem quando ela existe (o tipo derivado da task é só fallback: msg:forward diria "forward" para uma imagem). Operações que apenas MUTAM uma mensagem existente (delete/edit) não criam linha nova — a falha delas se resolve pelo message_id alvo que o chamador já tinha. A expiração da fila pode reconciliar para sent uma linha com id do WhatsApp já gravado, evitando reenviar uma tentativa cujo resultado é desconhecido. Esse id é evidência de criação local e, no wwebjs, não prova saída nem entrega; a observação do ack continua necessária. reason ∈ send_not_confirmed | retry_exhausted | permanent_4xx | instance_banned | throttle_hard_paused | timeout | reach_out_timelock | capability_unsupported | instance_not_connected | unsupported_media | invalid_recipient | recipient_not_on_whatsapp | forward_source_media_unavailable | forward_source_not_found | forward_source_deleted | forward_unavailable | sticker_not_found | sticker_premium | sticker_chat_not_found | quick_reply_changed | quick_reply_not_found | quick_replies_not_supported. sticker_not_found / sticker_premium / sticker_chat_not_found = envio de figurinha salva (sticker_id) recusado antes de tocar a página (a figurinha não está entre as que a gaveta mostra; é premium; ainda não há conversa com o número) — terminais, nada saiu (wire_state: not_sent), o código também vem em last_error. quick_reply_changed / quick_reply_not_found / quick_replies_not_supported = envio de resposta rápida (messages/quick-reply) recusado antes de digitar: a resposta foi editada ou apagada depois do 202, ou a conta não é WhatsApp Business — terminais, nada saiu, nunca com outro texto. reach_out_timelock = NACK 463 da Meta (envio a contato frio numa conta com time-lock de "reaching out"); NÃO é retentado (retry pioraria a restrição) — trate o contato como bloqueado até ele iniciar conversa. Os quatro últimos são falhas NÃO-transientes (não passaram por retry — attempt_count baixo): capability_unsupported = a capacidade atual da instância não suporta esse tipo de envio; instance_not_connected = instância desconectada/deslogada no momento do envio; unsupported_media = MIME de mídia não suportado (ex.: áudio com codec inválido); invalid_recipient = JID/telefone mal-formado; recipient_not_on_whatsapp = número bem-formado mas NÃO é um usuário WhatsApp registrado (o worker wwebjs confirma via getNumberId antes de falhar — distinto de um "No LID" transitório, que é retentado). É fast-failado (sem retry) e um envio subsequente ao MESMO número recebe 422 RECIPIENT_NOT_ON_WHATSAPP síncrono. forward_source_media_unavailable = o encaminhamento foi RECUSADO porque a mídia da mensagem de origem já saiu do store do WhatsApp Web (o worker prefere falhar visível a encaminhar um arquivo vazio). Também é fast-failado: os bytes não voltam, então retentar só adia a falha — a correção é reenviar a mídia, não retentar o forward. forward_source_not_found / forward_source_deleted = a mensagem de ORIGEM do encaminhamento não existe mais no WhatsApp deste aparelho (apagada para todos, reportada como enviada mas nunca existiu, ou fora do histórico do aparelho vinculado) — fast-failados, nada saiu (wire_state: not_sent); o caso já conhecido pela API (origem com *.deleted) nem chega a gerar evento: é recusado síncrono com 422 FORWARD_SOURCE_DELETED. forward_unavailable = o módulo de encaminhamento do WhatsApp Web não carregou nesta sessão; é retentado e só vira delivery_failed se a validade do envio esgotar. Uma falha de encaminhamento sai na família do conteúdo de ORIGEM (image.delivery_failed para uma imagem), com message_type da origem — igual ao evento de sucesso (se a origem nem está mais no histórico, message_type: "forward"). Uma origem apagada para todos DEPOIS do 202 também é recusada antes do despacho, com forward_source_deleted.

json
{ "type": "message.delivery_failed", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "message_id": "550e8400-e29b-41d4-a716-446655440000", "idempotency_key": "send-001", "task_id": "asynq:task:abc", "message_type": "text", "reason": "retry_exhausted", "wire_state": "not_sent", "last_error": "timeout", "attempt_count": 5, "timestamp": 1741361650 } }

send.outbox_stuck / send.outbox_recovered#

Um par. send.outbox_stuck avisa que a fila de envio de uma instância parou de andar — attempts>=3 (loop de retry) ou linhas em pending há mais de 10min sem sair (fila segurada: a sessão não subiu, então attempts nem incrementa e só a idade denuncia). send.outbox_recovered é o all-clear: aquela mesma instância não tem mais envio travado.

Ambos são edge-triggered e pareados 1:1 — o all-clear só existe para quem recebeu o alerta, e sai exatamente uma vez por episódio, no mesmo ponto do código em que o alerta é limpo (assim "destravou" e "o consumidor foi avisado" não podem divergir). Um consumidor que pausa envios ao ver stuck sabe o instante exato em que pode voltar, em vez de descobrir por polling.

stuck_seconds mede o tempo desde o alerta neste processo: um restart do worker limpa o estado em memória, então um episódio que atravessa restart é re-anunciado como um stuck novo e a recuperação reporta a duração a partir dele — nunca um número inflado.

json
{ "type": "send.outbox_stuck", "data": { "instance_id": "9c8ffc46-...", "stuck_count": 7, "timestamp": 1741361650 } }
{ "type": "send.outbox_recovered", "data": { "instance_id": "9c8ffc46-...", "stuck_seconds": 412, "timestamp": 1741362062 } }

media.moderation_blocked#

A sonda usa o MIME real da mensagem no download. Erros de transporte ou de MIME deixam o resultado desconhecido: não significam bloqueio nem aprovação de moderação. Um recibo de entrega, sozinho, não comprova reprodução no destinatário.

Provider wwebjs. Emitido quando a moderação de mídia da Meta ("Kaleidoscope") sinaliza uma mídia que NÓS enviamos: a mensagem é entregue (e até transcrita), mas o destinatário não consegue reproduzi-la ("este áudio/mídia não está mais disponível"). O worker re-baixa a própria mídia após o envio (probe, atraso default 60s, flag WWEBJS_MODERATION_PROBE=on) e lê o "dangerous score" — score ≥ 90 = bloqueada. Campos: message_ids (UUID Catcher), media_type, score (numérico da Meta), direction (outbound), source (kaleidoscope), phone, from, chat, timestamp. A mensagem também recebe moderation_status=blocked + moderation_score (visíveis em GET .../messages e no inspector do Console). Causa comum: metadata adulterada na mídia (jitter — por isso áudio nunca é jitterado, lesson #60). Sem URL de CDN da Meta no payload.

json
{ "type": "media.moderation_blocked", "data": { "phone": "554196332719", "from": "554196332719@s.whatsapp.net", "chat": "554196332719@s.whatsapp.net", "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "media_type": "ptt", "score": 90, "direction": "outbound", "source": "kaleidoscope", "timestamp": 1741361650 } }

instance.qr_scanned#

Campos: phone, device_jid, business_name, platform_name, timestamp.

json
{ "type": "instance.qr_scanned", "data": { "phone": "554137984905", "device_jid": "554137984905:1@s.whatsapp.net", "business_name": "Empresa LTDA", "platform_name": "smbi", "timestamp": 1741361650 } }

instance.proxy_changed#

Campos públicos: old_ip, new_ip, reason, old_city, new_city, timestamp.

json
{ "type": "instance.proxy_changed", "data": { "old_ip": "198.51.100.10", "new_ip": "198.51.100.11", "reason": "health_replace", "old_city": "br-saopaulo", "new_city": "br-saopaulo", "timestamp": 1741361650 } }

instance.provider_changed#

Campos: from, to, previous_device_unlinked, timestamp. A instância espera um novo pareamento por QR Code.

json
{ "type": "instance.provider_changed", "data": { "from": "whatsmeow", "to": "wwebjs", "previous_device_unlinked": true, "timestamp": 1793810000 } }

contact.temperature_changed#

Campos: remote_jid, phone, old_tier, new_tier, old_score, new_score, direction, trigger, timestamp.

json
{ "type": "contact.temperature_changed", "data": { "remote_jid": "554137984905@s.whatsapp.net", "phone": "554137984905", "old_tier": "cold", "new_tier": "warm", "old_score": 25, "new_score": 42, "direction": "inbound", "trigger": "message.received", "timestamp": 1741361650 } }

anti_spam.blocked#

Campos: remote_jid, phone, rule, detail, message_type, bypass_available, bypass_quota_left, content_hash, timestamp.

json
{ "type": "anti_spam.blocked", "data": { "remote_jid": "554137984905@s.whatsapp.net", "phone": "554137984905", "rule": "duplicate_content", "detail": "same content sent in rolling 24h", "message_type": "text", "bypass_available": true, "bypass_quota_left": 2, "content_hash": "sha256:abc", "timestamp": 1741361650 } }

whatsapp.policy_warning#

Campos: warning_code, category, message, expires_at, severity_hint, recommended_action, timestamp.

json
{ "type": "whatsapp.policy_warning", "data": { "warning_code": "rate_limit", "category": "anti_abuse", "message": "rate limit warning", "expires_at": "2026-05-21T13:00:00Z", "severity_hint": "warn", "recommended_action": "slow_down", "timestamp": 1741361650 } }

instance.send_locked / instance.send_unlocked / send.paced#

A trava anti-spam por conta (ver GET /v1/instances/{id}/account-pressure). Só envios iniciados por nós — para contatos que não escreveram nas últimas 72h — são afetados.

json
{ "type": "send.paced", "data": { "message_ids": ["7f0c2d4e-…"], "phone": "5541999990001", "chat": "5541999990001@s.whatsapp.net", "message_type": "video", "reasons": ["quota_10m"], "scheduled_for": 1761056580, "timestamp": 1761055800 } }
{ "type": "instance.send_locked", "data": { "reasons": ["template_burst"], "locked_by": "account_pressure", "held_count": 12, "timestamp": 1761055842 } }
{ "type": "instance.send_unlocked", "data": { "unlocked_by": "user:7", "held_resumed": 12, "held_discarded": 0, "timestamp": 1761059000 } }

scheduled_for é estimativa (unix), não promessa. locked_by é account_pressure (automático) ou user:<id>. Um envio segurado descartado no destrave gera message.delivery_failed com reason="account_pressure_discarded" e wire_state="not_sent".

account.restricted / account.restriction_cleared#

Campos: enforcement_type, active, ends_at (unix), ends_in_seconds, timestamp.

O WhatsApp avisa a restrição da conta por um canal próprio, antes de derrubar a sessão — em produção o aviso chegou 151 ms antes do LoggedOut 401 que encerrou a sessão. Diferente de instance.banned (que a gente INFERE depois que a sessão morre), aqui é o WhatsApp informando diretamente, com o tipo de restrição e o instante exato em que ela expira. ends_in_seconds já vem calculado e nunca é negativo, então dá pra renderizar contagem regressiva sem fazer conta de relógio.

json
{ "type": "account.restricted", "data": { "enforcement_type": "RESTRICT_ALL_COMPANIONS", "active": true, "ends_at": 1785022787, "ends_in_seconds": 522787, "timestamp": 1784500000 } }

O mesmo aviso com active: false é a liberação:

json
{ "type": "account.restriction_cleared", "data": { "active": false, "timestamp": 1785600000 } }

O estado também fica na instância (GET /v1/instances/{id}): account_restricted_at, account_restriction_type e account_restriction_ends_at — presentes só enquanto a restrição está ativa. O Console usa esse prazo real no lugar da estimativa de 6h que o last_logged_out_401_at obrigava a assumir.

Métricas: biazap_account_restriction_events_total{instance_id,enforcement_type,state} e o gauge biazap_account_restriction_active{instance_id} (1 enquanto restrita).


Persistencia de eventos#

Eventos são persistidos no histórico operacional do tenant quando passam pelo pipeline de realtime/webhooks. Eventos transientes (chat., label., privacy.update, blocklist.update, sync.*, media.retry_result, message.starred, message.deleted_for_me, message.undecryptable, message.decrypt_recovered, message.decrypt_lost) não criam/alteram linhas de mensagem em messages — são entregues via webhook/SSE/WebSocket e consultáveis pelo histórico de eventos quando habilitado.

Ciclo de vida da mensagem na tabela messages:

text
queued → sent → delivered → read
                    ↓
                 deleted (se revogada)
Campo Preenchido quando
queued_at Mensagem entra na fila
sent_at Enviada com sucesso ao WhatsApp
delivered_at Destinatário recebeu (receipt type=delivered)
read_at Destinatário leu (receipt type=read)
deleted_at Mensagem apagada (ProtocolMessage REVOKE)
failed_at Falha no envio

Tabelas de eventos:

Tabela Evento Descricao
messages message.received, message.sent, message.delivered, message.read, message.played, message.deleted, message.edited Todas as mensagens inbound/outbound com tracking completo
call_logs call.received, call.accepted, call.rejected, call.ended, call.group_offer Histórico de chamadas
group_events group.update, group.joined Auditoria de mudancas em grupos
contact_events contact.update, contact.identity_changed, contact.sync Mudancas em contatos