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#

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:

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

Como remote_jid funciona por direcao:

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#

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:

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

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.

Nota: message.undecryptable e o único evento onde message_ids[0] contem o ID do WhatsApp (não o UUID), pois a mensagem não pode ser persistida no banco.

Diferenciacao: 1:1 vs grupo#

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

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#