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:
-
LID → Phone JID: O WhatsApp pode enviar identificadores no formato LID (
@lid). A API tenta resolver LIDs para Phone JID (@s.whatsapp.net) usando: campoSenderAltdo protocolo, registro de identidade de contatos (tabelascontacts/contact_identities), e busca na tabelamessagescomo ú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 auxiliareschat_lidesender_lidpara correlação. -
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). -
Formato consistente: O campo
chatem todos os eventos e identico ao camporemote_jidno banco. Você pode agrupar eventos em conversas usandoinstance_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
phoneestá vazio (primeiro contato via LID, sem mapeamento no registro), usechat_lidpara agruparmessage.sent+message.delivered+message.read+message.playedda mesma conversa. - Correlação retroativa: Quando um
message.receivedchega comphonepreenchido echat_lidpresente, você pode retroativamente associar eventos anteriores que tinhamphonevazio mas o mesmochat_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.receivedcomSenderAlt), o mapeamento e salvo no registro de identidade. A partir dai, todos os eventos futuros para esse LID teraophonepreenchido 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 porremote_jid. O endpointGET /v1/instances/{instanceId}/chatsfaz 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_jide 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; apenasmessage.delivered,message.reademessage.playedpodem trazer multiplos quando o WhatsApp agrega confirmacoes em batch. Consumers leemevent.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):
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:
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.undecryptablee — 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 emmessage_ids/message_id(reusado nomessage.receivedrecuperado) — ou seja, segue o contrato UUID-only normal. O wwebjs não persiste placeholder, então omessage.undecryptabledo wwebjs carrega o hex bruto emmessage_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_*.
{
"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) |
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=falseem@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_meresolve a ambiguidade do id nativo compartilhado entre direções (que, com o id sozinho, responde409 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_FOUNDsíncrono. - Se o provider não encontrar o alvo, o envio falha de forma terminal e tipada:
*.delivery_failedcomreason: "target_not_found". Nunca500, 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.
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_groupnão estiver presente, você pode inferir pelo sufixo do campochat:@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_*)" |