Identificadores e Correlação de Eventos

21. Identificadores e Correlação de Eventos#

Está seção explica como JIDs 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 os identificadores:

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

O campo phone sempre traz o número puro (sem sufixo) e o message_ids sempre traz o UUID Catcher da mensagem.

Modelo de dados da mensagem#

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

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

Correlação: como agrupar eventos em conversas#

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

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.

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-..."])
    ↓
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

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
• Estável — o mesmo UUID persiste em todos os eventos do ciclo de vida da mensagem (received → delivered → read → played)
• Aceito nos endpoints da API — os endpoints que operam sobre uma mensagem (react, mark-read) aceitam tanto o UUID do Catcher quanto o ID do WhatsApp (hex)

Para a maioria dos eventos (message.received, message.sent), 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.

O campo whatsapp_message_ids aparece nos eventos de mensagem como trilha forense: ele carrega o(s) ID(s) bruto(s) do WhatsApp. Para operações da API e integrações de negócio, continue usando message_ids.

Endpoints de busca por identificador#