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.

POST/v1/webhooks#

Cria um novo webhook.

Auth: Owner, Admin

Request:

{
  "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"
}

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.

Eventos disponíveis:

Resposta 201:

{
  "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:

GET/v1/webhooks#

Lista todos os webhooks da empresa.

Auth: Owner, Admin

Query Parameters:

Resposta 200:

[
  {
    "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:

{
  "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:

Resposta 200:

{
  "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:

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

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):

Resposta 200:

{
  "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,
      "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 permanent_4xx após 3 tentativas — provavelmente um bug de configuração (URL errada, secret expirado, parser quebrado). has_payload_raw=false indica que o payload_raw foi redatado ou nunca foi salvo, e não da pra reenviar via API.

POST/v1/webhooks/retry-bulk#

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

Modo 1 — explicito por log IDs:

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

Modo 2 — por filtro:

{
  "webhook_id": 7,
  "event_type": "message.received",
  "class": "transient_5xx",
  "since": "2026-04-07T00:00:00Z"
}

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:

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

Estrategia de retry e classificação de erros#

Quando uma entrega falha, o Catcher classifica o erro e aplica a estrategia de retry adequada:

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

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 permanent_4xx) 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.

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:

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):

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):

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:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "message.received",
  "instance_id": "84c2e480-...",
  "timestamp": "2026-03-07T15:30:45.123Z",
  "data": { ... }
}

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).

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.

{
  "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"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "type": "audio",
  "content": "",
  "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mime_type": "audio/ogg; codecs=opus",
  "file_size": 34567,
  "duration": 15,
  "quoted_msg_id": "d28b6749-0a5c-47bc-9c12-fd4537a5d149",
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Joao Silva"
}

Exemplo de mensagem de grupo:

{
  "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):

{
  "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"
  },
  "is_forwarded": false,
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Patricia"
}

Exemplo de contato compartilhado (type=contact):

{
  "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.

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

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

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):

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.

message.sent#

Disparado após envio bem-sucedido de qualquer mensagem via API. Persistido na tabela messages. Para mensagens de mídia, inclui media_id para download via GET /v1/instances/{instanceId}/media/{mediaId}.

{
  "phone": "554192464230",
  "to": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "whatsapp_message_ids": ["3EB0DEF456ABC123"],
  "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",
  "quoted_msg_id": "3EB0AAA111BBB222",
  "timestamp": 1741360300,
  "is_group": false
}

Exemplo com varios contatos (type=contact):

{
  "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[].

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).

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.

{
  "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",
  "whatsapp_message_ids": ["3EB0DEF456ABC123", "3EB0DEF456ABC124"],
  "status": "delivered",
  "timestamp": 1741360310,
  "is_group": false
}

message.read#

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

{
  "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",
  "whatsapp_message_ids": ["3EB0DEF456ABC123"],
  "status": "read",
  "timestamp": 1741360350,
  "is_group": false
}

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.

{
  "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",
  "whatsapp_message_ids": ["3EB0DEF456ABC123"],
  "status": "played",
  "timestamp": 1741360400,
  "is_group": false
}

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).

{
  "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",
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "is_from_me": false,
  "timestamp": 1741360400
}

message.edited#

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).

{
  "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",
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "new_content": "Texto editado da mensagem",
  "is_from_me": false,
  "is_group": false,
  "push_name": "Joao",
  "timestamp": 1741360450
}

call.received#

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

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741360500
}

connection.update#

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

{
  "status": "connected",
  "reason": "",
  "previous_status": "connecting",
  "ban_expiry": null
}

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.

{
  "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
}

group.update#

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

{
  "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"]
}

Ações possíveis:

<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:

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?

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.

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "action": "picture_change",
  "value": "j+rE",
  "timestamp": 1741360700
}

Ações possíveis:

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.

{
  "instance_id": "84c2e480-...",
  "permanent": false,
  "reason": "spam",
  "ban_expiry": 1741446000
}

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.

{
  "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
}

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.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "is_unavailable": true,
  "unavailable_type": "account_removed",
  "decrypt_fail_mode": "",
  "timestamp": 1741360800
}

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.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "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.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "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.

{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "starred": true,
  "is_from_me": false,
  "timestamp": 1741360850
}

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.

{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "is_from_me": false,
  "timestamp": 1741360900
}

call.accepted#

Disparado quando uma chamada feita pela instância e aceita pela parte remota. Persistido na tabela call_logs.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741360950
}

call.rejected#

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

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741361000
}

call.ended#

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

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "reason": "normal",
  "duration": 45,
  "timestamp": 1741361050
}

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.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "source": "manual",
  "timestamp": 1741361050
}

call.group_offer#

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

{
  "call_id": "CALL-GRP456",
  "media": "audio",
  "type": "group",
  "timestamp": 1741361100
}

group.joined#

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

{
  "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
}

blocklist.update#

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

{
  "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
}

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.

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "implicit": false,
  "timestamp": 1741361250
}

contact.sync#

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

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "first_name": "Joao",
  "full_name": "Joao Silva",
  "timestamp": 1741361300
}

chat.pin#

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

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "pinned": true,
  "timestamp": 1741361350
}

chat.archive#

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

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "archived": true,
  "timestamp": 1741361400
}

chat.mute#

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

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "muted": true,
  "mute_end": 1741447800,
  "timestamp": 1741361450
}

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.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "marked_as_read": false,
  "timestamp": 1741361500
}

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.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": false,
  "timestamp": 1741361550
}

chat.delete#

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

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": true,
  "timestamp": 1741361600
}

privacy.update#

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

{
  "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
}

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.

{
  "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
}

Histórico importado não emite message.received/message.sent por mensagem, para evitar que consumidores processem mensagens antigas como tráfego novo. Use history.sync para progresso/resumo e GET /chats/{chatId}/messages para ler o conteúdo salvo.

sync.preview#

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

{
  "total": 250,
  "messages": 180,
  "receipts": 45,
  "notifications": 25,
  "timestamp": 1741361750
}

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.

{
  "message_ids": ["3EB0ABC123DEF456"],
  "chat": "554192464230@s.whatsapp.net",
  "success": true,
  "timestamp": 1741361800
}

label.edit#

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

{
  "label_id": "5",
  "name": "Urgente",
  "color": 1,
  "deleted": false,
  "timestamp": 1741361850
}

label.chat_association#

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

{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "phone": "554192464230",
  "associated": true,
  "timestamp": 1741361900
}

label.message_association#

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

{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "associated": true,
  "timestamp": 1741361950
}

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).

{
  "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
}

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).

{
  "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
}

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.

{
  "step": "qr_emitted",
  "level": "info",
  "message": "QR Code gerado, aguardando leitura",
  "detail": {
    "proxy_city": "sao-paulo"
  },
  "timestamp": 1741360100
}

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).

{
  "source": "history_sync_initial_bootstrap",
  "imported": 312,
  "skipped": 4,
  "timestamp": 1741361000
}

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.

{
  "count": 7,
  "timestamp": 1741361050
}

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.

{
  "duration_seconds": 12.4,
  "timestamp": 1741361080
}

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, timestamp.

{ "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, whatsapp_status_id, status_type, receipt_type, timestamp.

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

status.reaction#

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

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

status.reply#

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

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

message.pin_sent#

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

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

message.poll_vote_sent#

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

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

message.star_sent#

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

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

message.read_sent#

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

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

instance.no_proxy_blocked#

Campos: reason, detail, blocked_at, desired_state.

{ "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" } }

contact.block_sent#

Campos: phone, jid, timestamp.

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

contact.unblock_sent#

Campos: phone, jid, timestamp.

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

contact.presence_subscribed#

Campos: phone, jid, timestamp.

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

profile.name_changed_sent#

Campos: new_name, timestamp.

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

profile.picture_changed_sent#

Campos: bytes_uploaded, timestamp.

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

chat.unread_sent#

Campos: chat, phone, timestamp.

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

chat.archive_sent#

Campos: chat, phone, archived, timestamp. Disparado quando você arquiva/desarquiva um chat. É uma mutação de AppState que não gera self-echo, então este é o único sinal de que você fez a ação.

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

chat.pin_sent#

Campos: chat, phone, pinned, timestamp. Disparado quando você fixa/desfixa um chat.

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

chat.mute_sent#

Campos: chat, phone, muted, mute_end (opcional), timestamp. Disparado quando você muta/desmuta um chat. mute_end é o unix de expiração do mute (ausente ou 0 = indefinido / desmutado).

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

chat.clear_sent#

Campos: chat, phone, timestamp. Disparado quando você limpa as mensagens de um chat MANTENDO o chat na lista (distinto de chat.delete_sent).

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

chat.delete_sent#

Campos: chat, phone, timestamp. Disparado quando você deleta um chat (remove da lista de conversas).

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

chat.disappearing_timer_sent#

Campos: chat, phone, duration_seconds, timestamp. Disparado quando você define o timer de mensagens temporárias do chat. duration_seconds ∈ 0 (desligado) | 86400 (24h) | 604800 (7 dias) | 7776000 (90 dias).

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

status.reply_sent#

Campos: chat, phone, status_message_id, type, timestamp. Disparado quando você responde ao status de um contato (lado executor; a contraparte inbound no autor do status é status.reply). chat = JID 1:1 do autor (onde a resposta cai); status_message_id = id WhatsApp do status respondido; type ∈ text | image | video | sticker.

{ "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.

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

group.create_sent#

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

{ "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.

{ "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.

{ "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.

{ "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.

{ "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".

{ "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".

{ "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".

{ "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".

{ "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".

{ "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.

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

group.invite_link_revoked_sent#

Campos: group_jid, new_link, timestamp.

{ "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.

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

group.leave_sent#

Campos: group_jid, timestamp.

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

instance.deleted#

Campos: instance_id, phone, timestamp.

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

history.import_started#

Campos: oldest_message_id, limit, timestamp.

{ "type": "history.import_started", "data": { "oldest_message_id": "3EB0OLD", "limit": 500, "timestamp": 1741361650 } }

history.import_completed#

Campos: imported_count, limit, duration_ms, timestamp.

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

message.pinned#

Campos: chat, phone, sender, is_group, envelope_whatsapp_message_id, target_whatsapp_message_id, target_from_me, sender_timestamp_ms, timestamp.

{ "type": "message.pinned", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "envelope_whatsapp_message_id": "3EB0PIN", "target_whatsapp_message_id": "3EB0TARGET", "target_from_me": true, "timestamp": 1741361650 } }

message.unpinned#

Mesmo payload de message.pinned, para unpin.

{ "type": "message.unpinned", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "envelope_whatsapp_message_id": "3EB0PIN", "target_whatsapp_message_id": "3EB0TARGET", "target_from_me": true, "timestamp": 1741361650 } }

message.poll_vote_received#

Campos: chat, phone, voter, is_group, envelope_whatsapp_message_id, poll_whatsapp_message_id, poll_from_me, timestamp.

{ "type": "message.poll_vote_received", "data": { "chat": "120363012345678901@g.us", "phone": "554137984905", "voter": "554137984905@s.whatsapp.net", "is_group": true, "envelope_whatsapp_message_id": "3EB0VOTE", "poll_whatsapp_message_id": "3EB0POLL", "poll_from_me": false, "timestamp": 1741361650 } }

message.reaction_received#

Campos: chat, phone, sender, is_group, envelope_whatsapp_message_id, target_whatsapp_message_id, target_from_me, emoji, timestamp.

{ "type": "message.reaction_received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "envelope_whatsapp_message_id": "3EB0REACTION", "target_whatsapp_message_id": "3EB0TARGET", "target_from_me": true, "emoji": "👍", "timestamp": 1741361650 } }

message.product_received#

Campos: chat, phone, sender, is_group, envelope_whatsapp_message_id, product_id, business_owner_jid, title, timestamp.

{ "type": "message.product_received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "envelope_whatsapp_message_id": "3EB0PROD", "product_id": "prod_123", "business_owner_jid": "554100000000@s.whatsapp.net", "title": "Produto", "timestamp": 1741361650 } }

message.order_received#

Campos: chat, phone, sender, is_group, envelope_whatsapp_message_id, order_id, merchant_jid, item_count, total_amount_1000, currency, timestamp.

{ "type": "message.order_received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "envelope_whatsapp_message_id": "3EB0ORDER", "order_id": "order_123", "merchant_jid": "554100000000@s.whatsapp.net", "item_count": 2, "total_amount_1000": 9900000, "currency": "BRL", "timestamp": 1741361650 } }

message.decrypt_retry_pending#

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

{ "type": "message.decrypt_retry_pending", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "is_group": false, "whatsapp_message_id": "3EB0BAD", "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.

{ "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_id, whatsapp_message_id, idempotency_key, task_id, message_type, reason, last_error, attempt_count, timestamp.

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

instance.qr_scanned#

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

{ "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: old_ip, new_ip, reason, old_city, new_city, provider, timestamp.

{ "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", "provider": "brightdata", "timestamp": 1741361650 } }

contact.temperature_changed#

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

{ "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.

{ "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.

{ "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 } }

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:

queued → sent → delivered → read
                    ↓
                 deleted (se revogada)

Tabelas de eventos: