Identificadores e Correlação de Eventos

22. Identificadores e Correlação de Eventos#

Está seção explica como JIDs, LIDs e números de telefone fluem pelo sistema, e como correlacionar eventos a conversas e mensagens.

Glossario de Identificadores#

Termo Formato Exemplo O que e
Phone JID <phone>@s.whatsapp.net 554196332719@s.whatsapp.net Identificador de contato individual
Group JID <id>@g.us 120363012345678901@g.us Identificador de grupo
LID <id>:<device>@lid 216251804708983:34@lid Linked ID — formato interno do WhatsApp para dispositivos vinculados
Base LID <id>@lid 216251804708983@lid LID sem sufixo de dispositivo, usado como chat JID
chat_lid <id>@lid 42812401807390@lid Campo auxiliar nos eventos — LID original do chat antes da resolução para phone JID
sender_lid <id>:<device>@lid 42812401807390:77@lid Campo auxiliar nos eventos — LID original do sender antes da resolução para phone JID
RemoteJID Phone JID ou Group JID — Campo no banco que identifica a conversa
WhatsAppID string alfanumerica 3EB0A1B2C3D4E5F6 ID único da mensagem atribuido pelo WhatsApp
ExternalID UUID v4 a1b2c3d4-e5f6-... ID da mensagem na API Catcher
InstanceID UUID v4 84c2e480-... Qual instância WhatsApp (número conectado)
SenderJID Phone JID 554196332719@s.whatsapp.net Quem enviou a mensagem (util em grupos)

Normalizacao automática#

A API normaliza automaticamente todos os identificadores:

  1. LID → Phone JID: O WhatsApp pode enviar identificadores no formato LID (@lid). A API tenta resolver LIDs para Phone JID (@s.whatsapp.net) usando: campo SenderAlt do protocolo, registro de identidade de contatos (tabelas contacts/contact_identities), e busca na tabela messages como último fallback. Os campos principais (phone, chat, from, to, sender) sempre contem o phone JID quando a resolução e possível. Quando o LID original estava presente, ele e exposto nos campos auxiliares chat_lid e sender_lid para correlação.

  2. BR 13→12 digitos: Números brasileiros com 13 digitos (55XX9XXXXXXXX) são normalizados para 12 digitos (55XXXXXXXXXX), removendo o 9 extra. Isso e aplicado em todas as direcoes (inbound e outbound).

  3. Formato consistente: O campo chat em todos os eventos e identico ao campo remote_jid no banco. Você pode agrupar eventos em conversas usando instance_id + chat.

Campos LID auxiliares (chat_lid, sender_lid)#

Quando o WhatsApp usa internamente um LID para identificar um contato ou chat, a API expoe o LID original nos campos opcionais chat_lid e sender_lid (omitidos quando vazios). Esses campos são uteis para:

  • Correlação de eventos: Quando phone está vazio (primeiro contato via LID, sem mapeamento no registro), use chat_lid para agrupar message.sent + message.delivered + message.read + message.played da mesma conversa.
  • Correlação retroativa: Quando um message.received chega com phone preenchido e chat_lid presente, você pode retroativamente associar eventos anteriores que tinham phone vazio mas o mesmo chat_lid.
  • Debug: Os campos auxiliares permitem diagnosticar quando o WhatsApp opera em modo LID e verificar se a resolução de identidade está funcionando.

Disponibilidade dos campos LID por evento:

Evento chat_lid sender_lid
message.received Sim Sim
message.sent Sim —
message.delivered Sim Sim
message.read Sim Sim
message.played Sim Sim
message.deleted Sim Sim
message.edited Sim Sim

Aprendizado automático: A API aprende mapeamentos LID→telefone conforme interage com contatos. Quando um contato responde (message.received com SenderAlt), o mapeamento e salvo no registro de identidade. A partir dai, todos os eventos futuros para esse LID terao phone preenchido automaticamente.

Modelo de dados da mensagem#

A tabela messages no banco de cada tenant armazena todas as mensagens (inbound e outbound):

Campo Tipo Descricao
id (UUID) UUID ID público na API (exposto como elemento de message_ids nos eventos)
instance_id string Qual instância WhatsApp
direction string "inbound" ou "outbound"
remote_jid string A conversa. Phone JID (1:1) ou Group JID (grupo)
sender_jid string Quem enviou. Phone JID do remetente. Util para mensagens de grupo, onde remote_jid e o JID do grupo
message_type string text, image, video, audio, document, sticker, location, contact, reaction, poll, interactive, button_reply
content string Texto ou caption
status string queued → sent → delivered → read / failed / deleted
whatsapp_id string Coluna interna: ID hex da mensagem no WhatsApp. Exposta (desde 2026-10-21) como wa_message_id, sempre junto de wa_from_me + wa_remote_jid — reciclável (lição #22), então nunca é chave sozinha; o identificador primário segue sendo o UUID em id/message_ids
source string "api" (fila Catcher), "external" (WhatsApp Web/celular)
media_id string Referência a mídia no S3

Como remote_jid funciona por direcao:

Cenario Inbound remote_jid Outbound remote_jid Mesmo valor?
Chat 1:1 com 5541... 554196332719@s.whatsapp.net 554196332719@s.whatsapp.net Sim
Grupo 120363... 120363012345678901@g.us 120363012345678901@g.us Sim

Não existe tabela Chat. Conversas são derivadas agrupando mensagens por remote_jid. O endpoint GET /v1/instances/{instanceId}/chats faz isso automaticamente.

Como sender_jid funciona#

Cenario sender_jid remote_jid
Inbound 1:1 554196332719@s.whatsapp.net (quem mandou) 554196332719@s.whatsapp.net (a conversa)
Inbound grupo 554196332719@s.whatsapp.net (quem mandou) 120363012345678901@g.us (o grupo)
Outbound (API) vazio (a instância e o remetente) JID do destinatário
Outbound (externo) vazio (a instância e o remetente) JID do destinatário

Para mensagens de grupo, sender_jid e essencial para saber quem disse cada coisa dentro do grupo.

Correlação: como agrupar eventos em conversas#

Chave primaria da conversa: instance_id + campo chat do evento (ou remote_jid no banco)

Chave secundaria (quando chat e um LID não resolvido): instance_id + campo chat_lid do evento

Todos os eventos de mensagem incluem o campo chat, que corresponde exatamente ao remote_jid no banco:

Evento Campo de conversa Campo auxiliar LID Campo de mensagem (UUID Catcher)
message.received chat chat_lid message_ids (array)
message.sent chat chat_lid message_ids (array)
message.delivered chat chat_lid message_ids (array)
message.read chat chat_lid message_ids (array)
message.played chat chat_lid message_ids (array)
message.deleted chat chat_lid message_ids (array)
message.edited chat chat_lid message_ids (array)

Padronizacao: todos os eventos de mensagem usam message_ids (array). Para a maioria, o array tem exatamente 1 elemento; apenas message.delivered, message.read e message.played podem trazer multiplos quando o WhatsApp agrega confirmacoes em batch. Consumers leem event.data.message_ids[0] na maioria dos casos e iteram o array nos eventos de status.

Cenario LID (APIs externas): Quando outra API envia mensagens via LID e a Catcher ainda não conhece o telefone associado, os eventos message.sent e message.delivered terao phone vazio e chat com o LID. Use chat_lid como chave de agrupamento. Quando o contato responder, a Catcher aprendera o mapeamento, e a partir dai os eventos passarao a ter phone e chat com o phone JID. Você pode correlacionar retroativamente comparando o chat_lid dos novos eventos com os anteriores.

Correlação: como rastrear o lifecycle de uma mensagem#

O ciclo de vida de uma mensagem outbound e rastreado pelo message_ids[0] (UUID do Catcher):

text
message.sent (message_ids = ["550e8400-e29b-41d4-a716-..."])
    ↓
message.delivered (message_ids = ["550e8400-e29b-41d4-a716-..."])
    ↓
message.read (message_ids = ["550e8400-e29b-41d4-a716-..."])
    ↓ (se view-once)
message.played (message_ids = ["550e8400-e29b-41d4-a716-..."])

No banco, os timestamps são atualizados conforme os eventos chegam:

text
queued_at → sent_at → delivered_at → read_at → played_at (view-once)
                           ↓
                       deleted_at (se revogada)

message_ids — UUIDs do Catcher#

O campo message_ids em todos os eventos de mensagem contem um array de UUIDs internos do Catcher (v4, 36 chars cada). Este identificador e:

  • Garantido único — nunca reciclado, mesmo quando o WhatsApp reutiliza IDs após delecao
  • Estável — o mesmo UUID persiste em todos os eventos do ciclo de vida da mensagem (received → delivered → read → played → deleted)
  • Aceito nos endpoints da API — os endpoints de delete, edit, react, forward e mark-read aceitam tanto o UUID do Catcher quanto o ID do WhatsApp (hex)

Para a maioria dos eventos (message.received, message.sent, message.deleted, message.edited, message.starred, message.deleted_for_me, media.retry_result, label.message_association), o array tem exatamente 1 elemento — leia event.data.message_ids[0]. Apenas message.delivered, message.read e message.played podem trazer multiplos elementos quando o WhatsApp agrega receipts.

Use message_ids (o UUID Catcher) como id primário para correlacionar. Desde 2026-10-21 os eventos e as respostas REST também trazem a chave nativa do WhatsApp nos campos wa_* — para deduplicar entre transportes, usada sempre inteira (linha + wa_remote_jid + wa_from_me + wa_message_id), nunca o id sozinho (o WhatsApp recicla ids). Ver "Id nativo do WhatsApp (wa_*)" abaixo. Os nomes antigos (whatsapp_message_ids etc.) não voltam: o id nativo vive sob wa_*. Única exceção: o message.undecryptable do wwebjs, que sempre trouxe whatsapp_message_ids e continua trazendo como alias legado (eventos só crescem).

Carve-out (a família de decriptacao): message.undecryptable e — só no provider whatsmeow — message.decrypt_recovered / message.decrypt_lost / message.decrypt_retry_pending. Como a mensagem não foi decriptada, o whatsmeow persiste uma linha placeholder e emite o UUID Catcher dela em message_ids / message_id (reusado no message.received recuperado) — ou seja, segue o contrato UUID-only normal. O wwebjs não persiste placeholder, então o message.undecryptable do wwebjs carrega o hex bruto em message_ids (o ÚNICO hex bruto exposto na API); o wwebjs não emite a família de recuperação.


Id nativo do WhatsApp (wa_*)#

Desde 2026-10-21 (carta gmia "wa-native-message-id"). Aditivo: nenhum campo existente mudou de nome ou de significado.

O UUID Catcher continua sendo o id primário (message_ids, quoted_id, reaction_target_id, message_id dos 202). Ao lado dele, todo evento cujo objeto é uma mensagem passa a carregar a chave nativa do WhatsApp — a mesma que o WhatsApp usa internamente (key.id + fromMe + remoteJid). Ela existe para deduplicar entre transportes: quando a mesma linha chega por dois caminhos (ex.: Cloud API oficial em coexistência + Catcher), o wamid da Meta embute exatamente esse key.id.

Use a chave inteira, nunca o id sozinho. O WhatsApp recicla key.id (lição #22: o mesmo id já apareceu numa mensagem enviada e, depois, numa recebida de outro contato). A chave única é linha + chat + wa_from_me + wa_message_id. O chat de wa_remote_jid é o do protocolo e pode vir como @lid num chat endereçado por LID; o chat do mesmo evento traz a forma telefone (e chat_lid o LID). Para casar com a Cloud API, cujo wamid embute o telefone, compare o chat pela forma telefone (chat / phone) ou trate @lid e telefone do mesmo contato como alias.

Campo Tipo Quando Descrição
wa_message_id string sempre que a mensagem tem id nativo key.id puro (ex.: 3EB0854C03F146EB37CF2D)
wa_from_me bool junto de wa_message_id (sempre presente, false é significativo) direção da chave
wa_remote_jid string junto de wa_message_id chat da chave, na forma do provider (wwebjs: @c.us/@lid/@g.us; whatsmeow: @s.whatsapp.net/@lid/@g.us). Compare normalizando @c.us ≡ @s.whatsapp.net
wa_participant string grupo, quando houver autor da mensagem no grupo
wa_serialized string junto de wa_message_id <fromMe>_<remote_jid>_<id>[_<participant>] — a forma _serialized do whatsapp-web.js
wa_message_ids []string eventos que nomeiam mensagens paralelo a message_ids, mesma ordem — exceto nos recibos (delivered/read/played/acked/read_other_device): ali lista todos os ids nativos do recibo, inclusive os que não estão no nosso histórico, e pode ser mais longo que message_ids
quoted_wa_message_id, quoted_wa_from_me, quoted_wa_remote_jid, quoted_wa_participant resposta/citação chave da mensagem citada — preenchida do protobuf mesmo quando a citada não está no nosso histórico (nesse caso quoted_id vem vazio, mas a chave nativa vem)
target_wa_message_id, target_wa_from_me, target_wa_remote_jid, target_wa_participant reação, pin, voto de enquete, edição, revogação chave da mensagem-alvo

Semântica: wa_* descreve a mesma mensagem de message_ids — em *.received/*.sent a própria mensagem; em delivered/read/played/acked/delivery_failed/edited/deleted/starred a mensagem afetada. Numa reação (*.received/*.sent com type: reaction) e no pin, wa_* é a mensagem de reação/pin e target_wa_* é a mensagem reagida/fixada. Em edited/deleted, target_wa_* é igual a wa_*.

json
{
  "type": "text.received",
  "data": {
    "message_ids": ["95feff86-b411-44ce-baff-2702d853d1c8"],
    "wa_message_id": "3EB0854C03F146EB37CF2D",
    "wa_message_ids": ["3EB0854C03F146EB37CF2D"],
    "wa_from_me": false,
    "wa_remote_jid": "554163475715@c.us",
    "wa_serialized": "false_554163475715@c.us_3EB0854C03F146EB37CF2D",
    "quoted_id": "1c747b77-0d1f-4d43-9a43-2f0f4c3d9a10",
    "quoted_wa_message_id": "3EB0E2029DABF33E15870A",
    "quoted_wa_from_me": true
  }
}

Respostas REST. GET /v1/instances/{id}/message/{messageId} e as linhas de GET .../chats/{chatJID}/messages trazem wa_message_id/wa_from_me/wa_remote_jid/wa_serialized (+ wa_participant em grupo) e, quando houver, quoted_wa_* / target_wa_*. GET .../message/{messageId} aceita também a chave serializada no lugar do UUID.

Ack de envio. O 202 de um envio assíncrono não traz o id nativo: o worker envia depois da resposta, e inventar um id seria mentir. O id chega no *.sent correspondente (casado pelo message_id/idempotency_key do 202). Um replay do mesmo Idempotency-Key depois do envio devolve wa_message_id/wa_from_me/wa_remote_jid.

Mirar uma mensagem pela chave nativa#

Todo campo que referencia uma mensagem existente (quoted_id dos envios, message_id de reaction/delete/forward/pin/star/vote, os message_ids do mark-read, o {messageId} do edit) aceita, além do UUID, a chave serializada true|false_<chat>_<id>[_<participant>]. Alternativa em campos explícitos:

Operação Campos
Citação em qualquer send/* (inclusive multipart; no envio agendado, só a forma serializada em quoted_id) quoted_wa_message_id + quoted_wa_from_me (+ quoted_wa_remote_jid, padrão = to; + quoted_wa_participant)
reaction, delete, forward, edit target_wa_message_id + target_wa_from_me (+ target_wa_remote_jid, padrão = to — no forward forward_chat_id; obrigatório no edit, que não tem to; + target_wa_participant)
json
POST /v1/instances/{id}/messages/reaction
{ "to": "554163475715", "target_wa_message_id": "3EB0854C03F146EB37CF2D", "target_wa_from_me": false, "emoji": "👍" }
  • A chave funciona mesmo para mensagem que não está no nosso histórico (ex.: conhecida só pela Cloud API): reaction e delete seguem para o provider com a chave completa; mark-read usa o id + a direção da chave. A citação de mensagem fora do histórico segue a regra "inteiro ou nada": sem o conteúdo citado guardado, o whatsmeow envia sem citação; o wwebjs cita se a mensagem estiver no store do WhatsApp Web.
  • Mensagem de outra pessoa num grupo (from_me=false em @g.us) exige *_wa_participant (o autor) — sem ele o WhatsApp descartaria a ação em silêncio → 400 INVALID_MESSAGE_KEY. Se a mensagem estiver no histórico, o participante é preenchido dele.
  • *_wa_from_me resolve a ambiguidade do id nativo compartilhado entre direções (que, com o id sozinho, responde 409 CONFLICT).
  • Chave malformada, sem *_wa_from_me, de outro chat, ou com direção que a operação não aceita (apagar/editar só from_me=true, mark-read só from_me=false) → 400 INVALID_MESSAGE_KEY, nada enfileirado.
  • forward, edit e label precisam do conteúdo/elegibilidade da mensagem guardada: chave fora do histórico → 404 TARGET_NOT_FOUND síncrono.
  • Se o provider não encontrar o alvo, o envio falha de forma terminal e tipada: *.delivery_failed com reason: "target_not_found". Nunca 500, nunca descarte silencioso. No wwebjs isso vale para reaction, delete e edit (o alvo precisa estar no store do WhatsApp Web). No whatsmeow o protocolo não exige a mensagem localmente: reaction e delete por chave são enviados direto ao WhatsApp, que não confirma a existência do alvo — uma chave inexistente simplesmente não produz efeito.

Lookup em lote — POST /v1/instances/{id}/messages/native-ids#

Mapeia UUID ↔ chave nativa (backfill histórico). Leitura apenas; mesmo escopo de autenticação das leituras de mensagem. Exatamente uma das formas por chamada, no máximo 500 itens.

json
POST /v1/instances/{id}/messages/native-ids
{ "message_ids": ["95feff86-b411-44ce-baff-2702d853d1c8", "00000000-0000-4000-8000-0000000000ff"] }

200
{
  "items": [{
    "message_id": "95feff86-b411-44ce-baff-2702d853d1c8", "direction": "inbound",
    "wa_message_id": "3EB0854C03F146EB37CF2D", "wa_from_me": false,
    "wa_remote_jid": "554163475715@s.whatsapp.net",
    "wa_serialized": "false_554163475715@s.whatsapp.net_3EB0854C03F146EB37CF2D"
  }],
  "not_found": ["00000000-0000-4000-8000-0000000000ff"],
  "invalid": []
}

Inverso: { "wa_keys": [{ "wa_message_id": "3EB0…", "wa_from_me": false, "wa_remote_jid": "554163475715@c.us" }] } → items com o message_id; chaves ausentes (ou ambíguas) voltam em not_found. Um message_id malformado (vazio ou com mais de 64 caracteres) não derruba o lote: volta em invalid (sempre presente, [] quando não há nenhum) e os demais são resolvidos normalmente. 400 para corpo vazio, as duas formas juntas, mais de 500 itens, ou wa_key inválida (INVALID_MESSAGE_KEY) — a chave nativa é montada pelo cliente e um wa_from_me ausente não pode ser adivinhado; 404 para instância de outra empresa.


Diferenciacao: 1:1 vs grupo#

O campo is_group está disponível nos seguintes eventos:

Evento is_group Como identificar se ausente
message.received Sim —
message.sent Sim —
message.delivered Sim —
message.read Sim —
message.played Sim —
message.deleted Não chat termina com @g.us
message.edited Sim —

Quando is_group não estiver presente, você pode inferir pelo sufixo do campo chat: @g.us = grupo, @s.whatsapp.net = individual.

Endpoints de busca por identificador#

Preciso de... Endpoint Parametro
Listar conversas GET /v1/instances/{id}/chats —
Mensagens de uma conversa GET /v1/instances/{id}/chats/{chatJID}/messages chatJID = remote_jid = chat dos eventos
Uma mensagem especifica GET /v1/instances/{id}/message/{messageId} messageId = UUID do Catcher (elemento de message_ids do evento), prioritário; id nativo somente quando único na instância, senão 409 CONFLICT
Mídias de uma conversa GET /v1/instances/{id}/media?remote_jid={chatJID} remote_jid = chat dos eventos
UUID ↔ chave nativa do WhatsApp (lote, até 500) POST /v1/instances/{id}/messages/native-ids message_ids OU wa_keys — ver "Id nativo do WhatsApp (wa_*)"