LID no WhatsApp: o que é, por que aparece e como tratar nos webhooks do Z-API

LID no WhatsApp. Se você integra essa plataforma no seu produto, existe um tipo de bug que é traiçoeiro porque não parece bug até estourar em produção: identificação de contato quebrando.

Você recebe um webhook, tenta amarrar aquela mensagem ao usuário certo e… de repente, o campo que “sempre foi um número” vem com outra coisa. O histórico do contato não bate, o CRM duplica registro, o suporte não encontra a conversa, e o time começa a suspeitar de “instabilidade” quando o problema, na verdade, é mudança de identificação.

Nos últimos updates de privacidade do WhatsApp, isso virou mais comum por um motivo específico: o @lid.

A documentação oficial do Z-API explica que o @lid é “um identificador único e privado criado pelo WhatsApp para representar contatos sem expor diretamente o número de telefone”, e que essa mudança faz parte das atualizações de privacidade do WhatsApp para permitir que o usuário oculte o número em determinados contextos.

E tem um detalhe que pega muita integração de surpresa: em alguns casos, “o WhatsApp está enviando o @lid como identificação primária do usuário, mesmo que ele não tenha ativado nenhuma opção para esconder o número.”

Neste artigo, você vai entender o que é @lid, por que ele aparece, como isso aparece nos webhooks do Z-API (com exemplos oficiais) e qual é o erro mais comum que faz integrações quebrarem tudo com base na documentação do Z-API.

Veja mais detalhes em nossa documentação.

O que é o @lid e por que ele existe

De forma direta: o @lid é um identificador criado pelo WhatsApp para representar um contato sem expor o número de telefone. Ele é descrito na doc como “único e privado”, e faz parte de atualizações de privacidade que permitem ocultar o número em determinados contextos.

Esse ponto é importante porque muda um pressuposto antigo de integrações: durante muito tempo, identificar o usuário pelo número parecia “natural”. Com o @lid, o WhatsApp passa a ter um modo de representar o contato que não depende do número aparecer da mesma forma em todos os cenários.

E o alerta principal (que é o motivo deste artigo) é explicitado pela doc: o WhatsApp pode enviar @lid como identificação primária, mesmo sem o usuário ter “ativado” nada para esconder o número.

Ou seja: você não pode tratar isso como “um caso raro”. Você precisa estar preparado para receber esse formato em produção.

Veja também: ANPD conclui análise sobre compartilhamento de dados entre WhatsApp e Meta

Diferença entre @lid e phone no retorno do WhatsApp

A documentação do Z-API descreve que o WhatsApp pode retornar identificadores “de diferentes formas”, e que isso varia conforme o “tipo de conversa, grupo ou configuração de privacidade.”

Na prática, a doc explica dois pontos que você precisa memorizar:

1) phone pode vir como número real ou como @lid

O campo phone pode conter o número real, por exemplo “554499999999”, ou pode conter o próprio @lid, por exemplo “999999999999999@lid”.

Esse é o motivo clássico de “identificação quebrando”: se sua lógica assume que phone é sempre um número em formato E.164 (ou algo próximo disso), você vai falhar quando o valor vier com sufixo @lid.

2) chatLid é o identificador “mais estável”

A doc é bem direta: chatLid é o “identificador único mais estável.”

Isso não significa que você tem que abandonar o número. Significa que, quando a conversa envolve privacidade/contexto, chatLid se torna uma referência mais confiável para identificar o contato ao longo do tempo (especialmente em cenários em que o phone pode “trocar de formato”).

Como isso aparece nos webhooks do Z-API

A doc descreve exatamente esse cenário:

“Nos webhooks do Z-API, o WhatsApp pode retornar o identificador do contato de diferentes formas, dependendo do tipo de interação e das configurações de privacidade do usuário.”

E ela fornece dois exemplos que já resolvem grande parte da confusão em integrações.

Exemplo 1 — Retorno completo com número e @lid

Neste cenário, chatLid vem com @lid e phone vem com o número:

{

 “chatLid”: “999999999999999@lid”,

 “phone”: “554499999999”

}

Esse caso costuma ser o “melhor dos mundos”: você recebe o @lid e o número real. Mas ainda assim, se você estiver usando apenas phone como chave primária no seu banco, você não está protegendo sua integração para o segundo cenário.

Exemplo 2 — Retorno apenas com o @lid

Aqui, o WhatsApp retorna chatLid e phone ambos como @lid:

{

 “chatLid”: “65998849469@lid”,

 “phone”: “65998849469@lid”

}

Esse é o cenário que quebra integrações “na unha”: o seu sistema procura um número, não encontra, cria um “novo contato” e de repente você tem duplicidade, perda de histórico e bagunça de atendimento.

Perceba que o Z-API não está dizendo “talvez isso aconteça”. Ele está documentando como o WhatsApp pode retornar em webhooks ou seja, é um comportamento real que precisa ser suportado.

O erro mais comum (e por que isso quebra integrações)

O erro mais comum é simples: tratar phone como sinônimo de número de telefone e usar esse valor como chave primária para identificar o contato.

Enquanto phone vier sempre como “5544…”, isso “funciona”. Mas a doc deixa explícito que phone pode virar @lid.

A consequência prática é previsível:

• você perde vínculo entre mensagem e contato existente
  
• você cria contato duplicado sem perceber
  
• sua camada de atendimento perde histórico
  
• seus relatórios “somem” conversas (porque foram para outro identificador)
  
• e o time acha que o problema é instabilidade ou webhook “bugado”, quando na verdade é regra de identificação
  

A documentação do Z-API não entrega um “passo a passo de arquitetura”, mas ela dá o direcionamento mais importante: chatLid é o identificador “mais estável”.

Então, no mínimo, você precisa garantir que o seu parsing e a sua lógica de identificação considerem que:

• phone pode vir como número ou como @lid
  
• e que chatLid existe justamente como identificador estável
  

Só isso já evita grande parte das “quebras invisíveis”.

Um detalhe importante: dá para enviar mensagens usando @lid

Muita gente acha que @lid é um “problema para receber” e não pode ser usado para enviar. A documentação do Z-API diz o contrário.

Ela afirma que é possível enviar mensagens diretamente para um @lid, “substituindo o número de telefone no corpo da requisição”, e mostra um exemplo em que phone recebe um valor @lid.

Exemplo oficial:

{

 “phone”: “999999999999999@lid”,

 “message”: “Olá! Essa mensagem foi enviada usando o identificador @lid.”

}

A doc ainda reforça: “O envio funciona normalmente, pois o @lid já é suportado pela API da Z-API na maioria dos endpoints.”

Esse trecho é valioso por dois motivos:

1. confirma que @lid não é “exceção” ele já é suportado de forma ampla na API;
   
2. mostra que você pode tratar o @lid como um identificador operacional (quando ele for o que você tem disponível) sem ficar travado esperando o número real aparecer.
   

Conclusão (prática)

Em 3 linhas, como a própria documentação permite resumir:

O @lid existe e pode aparecer como identificação primária.
O campo phone pode vir como número real ou como @lid.
E o chatLid é descrito como o identificador único mais estável.

Se você integra WhatsApp e consome webhooks, isso não é “curiosidade”: é parte do contrato do mundo real. A melhor hora para ajustar sua identificação é antes do dia em que o histórico do cliente “some” e você precisa explicar por que o sistema perdeu rastreabilidade.

Takeaways rápidos

• O @lid é um identificador único e privado criado pelo WhatsApp.
  
• Em alguns casos, o WhatsApp envia @lid como identificação primária mesmo sem o usuário ativar nada.
  
• phone pode conter o número real ou o próprio @lid.
  
• chatLid é descrito como o identificador único mais estável.
  

Veja a documentação oficial do Z-API sobre LID.