LID no app de mensageria: o que é, como funciona e o que muda nas integrações com o Z-API

Durante muito tempo, o número de telefone foi tratado como a principal identidade de um contato no LID no app de mensageria. Para localizar uma conversa, registrar um cliente, criar um ticket ou enviar uma mensagem, bastava guardar uma sequência numérica como: 5511999999999.

Esse modelo está mudando. Em determinadas situações, o aplicativo de mensagens pode retornar um identificador no formato @lid em vez de expor diretamente o número de telefone. Para quem utiliza API, webhooks, CRM ou automações, essa mudança exige uma revisão importante na forma de armazenar, consultar e enviar mensagens.

O LID, sigla associada a Local Identifier, é um identificador privado utilizado para representar um usuário sem revelar necessariamente o número real. Ele permite que a integração continue reconhecendo o contato e encaminhando mensagens, enquanto reduz a exposição do telefone em payloads, logs e bases técnicas.

Isso não significa que o número deixou de existir ou que todos os fluxos agora funcionarão exclusivamente com LID. O telefone ainda pode aparecer em determinados eventos e continuar sendo necessário em processos específicos. A mudança principal é que o número não deve mais ser tratado como a única chave possível.

Neste artigo, você vai entender:

• o que é LID e por que o app de mensageria utiliza esse identificador;
• a diferença entre phone, lid, @lid e chatLid;
• como interpretar os retornos dos webhooks;
• como enviar mensagens usando um LID;
• quando utilizar LID ou telefone;
• como adaptar CRM, banco de dados e automações;
• por que chatLid: null pode ser um retorno normal;
• quais conversões são possíveis ou limitadas;
• como o Z-API ajuda a manter a integração estável.

O que é o LID no app de mensageria?

O LID é um identificador associado ao usuário em uma determinada interação do app de mensageria do Meta. Ele funciona como uma referência técnica para que sistemas reconheçam o contato sem depender da exposição do telefone.

Um retorno pode apresentar um valor semelhante a:

5511999999999

Ou, em outro cenário:

g1ff3a2d@lid

O segundo valor não deve ser validado como se fosse um número. Ele é um identificador que precisa ser armazenado e utilizado de acordo com as regras da integração.

A adoção desse modelo está relacionada a uma direção mais ampla de privacidade. Ao reduzir a circulação de números em integrações, a plataforma dificulta a cópia indiscriminada de bases de telefone e diminui a exposição de um dado pessoal em logs, filas e sistemas de terceiros.

Para desenvolvedores, a consequência é direta: o parser, o banco de dados e as regras de envio precisam aceitar mais de um formato de identificação.

O LID não é um telefone mascarado para ser convertido livremente. Ele é um identificador operacional que pode permitir a continuidade da conversa sem expor o número.

O LID substitui o número de telefone?

Não em todos os contextos. O LID substitui a dependência exclusiva do telefone em determinados eventos, mas o número pode continuar disponível em outros fluxos.

• Em uma integração, você pode encontrar situações como:
• phone com um número tradicional;
• phone contendo um valor terminado em @lid;
• campo lid preenchido separadamente;
• chatLid disponível para identificar uma conversa;
• chatLid com valor null;
• telefone e LID disponíveis no mesmo evento.

Por isso, não é seguro escrever uma regra que aceite apenas dígitos. Uma validação como esta pode quebrar quando o sistema de mensagens retornar um LID:

JavaScript if (!/^\d+$/.test(phone)) {   throw new Error(‘Telefone inválido’); }

A aplicação precisa reconhecer os dois cenários e encaminhar cada valor para o campo apropriado. Uma validação mais adequada seria separar o identificador do tipo de contato:

JavaScript function identify(value) {   if (!value) return { type: ‘unknown’, value: null };   if (value.endsWith(‘@lid’)) return { type: ‘lid’, value };   if (/^\d+$/.test(value)) return { type: ‘phone’, value };   return { type: ‘other’, value }; }

O exemplo é conceitual. Os campos exatos dependem do payload recebido e do endpoint utilizado, mas o princípio é o mesmo: não confunda número com identificador privado.

Aproveite e fique por dentro também do que é Sistema de Mensageria Coexistence: aprenda como usar o app com o mesmo número via API.

Diferença entre phone, lid e chatLid

A interpretação correta dos campos evita erros de busca, contatos duplicados e mensagens enviadas para o destino errado.

Campo	O que representa	Como tratar
phone	Número do usuário quando disponível; em alguns retornos pode carregar um LID	Não presuma que sempre terá apenas dígitos
lid ou @lid	Identificador privado do usuário	Armazene em campo próprio e utilize como identificador de contato
chatLid	Identificador relacionado ao chat ou à conversa	Trate como opcional e aceite null
from	Origem do evento ou remetente, conforme o payload	Analise junto aos demais campos de identidade
messageId	Identificador da mensagem	Use para rastreamento, idempotência e auditoria

O que é phone?

O campo phone costuma representar o número do contato quando o aplicativo de mensagens o disponibiliza. Porém, em algumas versões ou eventos, ele pode retornar um identificador no formato @lid.

Portanto, o nome do campo não é suficiente para determinar o tipo do valor. O conteúdo precisa ser analisado.

O que é lid?

O lid representa o usuário por meio de um identificador privado. Ele pode ser o valor mais adequado para localizar e manter o relacionamento técnico com o contato quando o número não estiver disponível.

Não utilize o LID como se fosse um telefone em relatórios, integrações de SMS ou validações que exigem país e DDD.

O que é chatLid?

O chatLid está relacionado à identificação do chat ou da conversa. Ele não deve ser confundido com o identificador individual do usuário.

Pode haver eventos em que chatLid esteja preenchido e outros em que ele seja null. Esse retorno não deve quebrar o fluxo automaticamente. A aplicação precisa saber se está processando uma mensagem individual, um grupo, uma conversa ainda não persistida ou um evento que não possui um chat associado naquele momento.

Por que chatLid pode vir como null?

chatLid: null não significa necessariamente que o webhook esteja inválido. O campo pode não estar disponível em todos os tipos de evento ou em todas as etapas da conversa.

Trate o valor nulo como uma possibilidade válida:

JavaScript const chatId = payload.chatLid || null; const contactId = payload.contact?.lid || payload.from || null; if (!contactId) {   // Envie o evento para uma fila de análise ou registre a falha. }

A regra prática é:

• use o LID do contato quando a tarefa for identificar o usuário;
• use chatLid quando a operação precisar identificar a conversa;
• aceite null quando a conversa não estiver disponível no evento;
• utilize messageId para rastrear a mensagem;
• não descarte automaticamente o webhook inteiro porque chatLid veio vazio.

Você viu? App de mensageria testa chamadas para usuários sem conta: veja possíveis impactos.

Como o Z-API trata o LID nos webhooks?

O Z-API trabalha com retornos que podem conter número, LID e informações relacionadas ao chat. Em vez de construir uma integração dependente de um único formato, sua aplicação deve consultar os campos de contato disponibilizados no payload e manter o identificador recebido.

Exemplos conceituais de eventos:

JSON {   “from”: “5511999999999”,   “messageId”: “ABCD1234”,   “contact”: {     “phone”: “5511999999999”,     “lid”: null   } }

Em outro evento:

JSON {   “from”: “g1ff3a2d@lid”,   “messageId”: “EFGH5678”,   “chatLid”: null,   “contact”: {     “phone”: “g1ff3a2d@lid”,     “lid”: “g1ff3a2d@lid”   } }

Os nomes e a composição exata podem variar conforme o endpoint e o tipo de mensagem. O ponto central é que o sistema deve procurar o identificador privado no objeto de contato e preservar o valor recebido.

Ao receber um webhook, uma rotina recomendada é:

1. validar a origem e a estrutura do evento;
2. extrair messageId, from, phone, lid e chatLid;
3. identificar se cada valor é telefone, LID ou nulo;
4. localizar o contato pelo LID quando disponível;
5. atualizar o telefone somente se ele estiver presente;
6. registrar a origem e a data da informação;
7. processar a mensagem apenas uma vez;
8. responder utilizando o identificador aceito pelo endpoint.

Posso enviar mensagens utilizando o LID?

Sim. Quando o endpoint utilizado aceitar o identificador, você pode utilizar o LID no campo to em vez de enviar o número.

Exemplo conceitual:

JSON {   “to”: “g1ff3a2d@lid”,   “message”: “Olá! Como podemos ajudar?” }

O valor deve ser exatamente o identificador recebido e armazenado pela integração. Não tente criar um LID manualmente a partir do telefone e não altere caracteres para “padronizar” o identificador como se fosse um número.

O fluxo recomendado é:

Webhook recebido ↓ Salvar contact.lid ↓ Associar ao contato interno ↓ Recuperar o LID no momento do envio ↓ Enviar para o endpoint do Z-API ↓ Registrar messageId e status

Se houver erro e o telefone estiver disponível, a aplicação pode aplicar uma regra de fallback conforme o endpoint, a causa da falha e a política operacional da empresa. O fallback não deve ser automático em qualquer erro, porque uma falha de validação, autorização ou destinatário inválido não será resolvida apenas trocando o identificador.

Quando usar LID e quando usar phone?

A decisão depende do objetivo da operação.

Prefira LID para identificar o contato

Use o LID como identificador preferencial quando ele estiver disponível no webhook e cadastrado no sistema. Ele reduz a dependência do número e mantém a integração preparada para eventos em que o telefone não aparece.

O LID é especialmente útil para:

• localizar o contato no CRM;
• associar mensagens ao mesmo usuário;
• responder a uma conversa iniciada pelo cliente;
• evitar que o sistema descarte eventos sem telefone;
• manter a operação alinhada ao modelo de privacidade do canal de mensagem.

Use o telefone quando a finalidade exigir o número

O telefone pode ser necessário para:

• exibir o contato em uma tela administrativa;
• enviar SMS ou realizar chamada fora do aplicativo de mensagens;
• validar um cadastro externo;
• integrar com sistemas que ainda não aceitam LID;
• executar uma etapa de autenticação que dependa do número.

A recomendação não é apagar o telefone. É separar finalidade e identidade. O telefone pode continuar como dado complementar, enquanto o LID funciona como chave preferencial da relação dentro do sistema de mensagens.

Como modelar o banco de dados?

Evite definir phone como a única chave primária do contato. Crie um identificador interno próprio e armazene os valores do aplicativo em campos independentes.

Um modelo possível seria:

contacts – id                  identificador interno – lid                 identificador privado – phone               telefone, quando disponível – chat_lid            identificador do chat, quando disponível – phone_verified_at   data de validação do telefone – lid_collected_at    data de coleta do LID – source              origem do identificador – last_message_id     última mensagem processada – created_at – updated_at

Recomendações importantes:

• crie índice para lid;
• trate o LID como texto;
• não use chatLid como identidade do usuário;
• aceite null em telefone e chatLid;
• registre a origem do dado;
• preserve histórico de alterações relevantes;
• mantenha unicidade dentro do escopo correto;
• evite logs com dados pessoais desnecessários.

Como fazer a busca?

A ordem de busca pode ser:

1. procurar pelo lid no contexto da instância;

2. se não existir, procurar pelo telefone disponível;

3. validar associação e origem;

4. criar contato somente depois dessas tentativas.

Não faça deduplicação apenas por nome de perfil. O mesmo nome pode pertencer a várias pessoas. Também não associe automaticamente um LID a um telefone somente porque os eventos ocorreram próximos no tempo.

LID e CRM: o que muda para a software house?

Sistemas que foram projetados para trabalhar apenas com números podem falhar em vários pontos:

• validações que rejeitam caracteres não numéricos;
• máscaras de telefone aplicadas sobre o LID;
• relatórios que não conseguem agrupar eventos;
• chaves estrangeiras baseadas apenas em phone;
• integrações com SMS que recebem o identificador errado;
• filtros de país e DDD aplicados ao LID;
• deduplicação que cria um novo cliente a cada webhook;
• dashboards que deixam de contabilizar contatos sem número.

Faça um inventário de todos os lugares onde o telefone aparece. Depois, classifique cada uso:

Uso do telefone	Pode migrar para LID?	Ação recomendada
Identificar contato no app de mensagem	Sim	Preferir LID quando disponível
Enviar mensagem pelo aplicativo	Em muitos fluxos	Usar o identificador aceito pelo endpoint
Enviar SMS	Não	Manter telefone validado
Exibir em tela administrativa	Não necessariamente	Mostrar telefone quando disponível e LID como referência técnica
Dedupe de contatos	Parcialmente	Usar LID, telefone e regras de associação
Relatórios de conversas	Sim	Agrupar pelo ID interno e registrar os identificadores
Autenticação externa	Depende	Seguir o requisito do sistema externo

Essa separação evita que uma mudança de privacidade em um canal quebre processos que realmente dependem do número.

Posso converter LID em número?

Não conte com uma conversão direta de LID para telefone por uma API pública. O propósito do identificador é reduzir a exposição do número, portanto a aplicação não deve presumir que terá acesso reverso.

Em alguns cenários autorizados, pode existir uma consulta de número para LID. Isso depende do endpoint, das permissões, da disponibilidade do dado e do modelo de integração. Não construa sua arquitetura supondo que essa conversão estará sempre disponível.

A orientação mais segura é:

• armazene o LID quando receber o webhook;
• armazene o telefone somente quando ele for fornecido legitimamente;
• mantenha o vínculo entre os dois quando a associação for confirmada;
• aceite que alguns registros terão apenas LID;
• não tente descobrir o número por meios não autorizados;
• não exponha o LID em URLs públicas ou logs sem necessidade.

Boas práticas de privacidade e segurança

Embora o LID não revele diretamente o telefone, ele continua sendo um identificador relacionado a uma pessoa e deve ser protegido.

Reduza dados nos logs

Registre apenas o necessário para depuração. Mascare valores em logs de produção e restrinja o acesso a payloads completos.

Proteja webhooks

Valide origem, assinatura, autenticação e estrutura do evento. Um webhook exposto pode permitir injeção de mensagens ou alteração indevida de contatos.

Separe identificador técnico de dado de exibição

O atendente pode precisar ver o nome e o telefone quando disponíveis. O sistema não precisa exibir o LID em todas as telas. Mostre o identificador apenas onde ele for necessário para suporte ou auditoria.

Controle acesso ao mapeamento

A relação entre LID e telefone pode ser sensível. Restrinja consultas, registre acessos e mantenha uma política de retenção compatível com a finalidade do sistema.

O que muda na integração com a API do Z-API?

A adaptação é principalmente de modelagem e tratamento de payload. Você não precisa reescrever toda a aplicação, mas precisa remover a suposição de que todo contato será representado por dígitos.

As mudanças mais importantes são:

1. adicionar um campo próprio para LID;
2. aceitar @lid em validações e parsers;
3. salvar contact.lid quando recebido;
4. tratar chatLid como opcional;
5. atualizar buscas para preferir LID;
6. manter telefone como informação complementar;
7. registrar messageId para idempotência;
8. adaptar relatórios e telas administrativas;
9. revisar integrações que exigem telefone;
10. testar envio com número e com LID.

O Z-API oferece uma camada de integração para conectar seu sistema ao canal de mensagens e trabalhar com webhooks, mensagens e identificadores retornados pela operação. A aplicação cliente continua responsável por salvar os dados, validar os fluxos e escolher a regra correta de fallback.

Antes de colocar a mudança em produção, consulte a documentação do endpoint utilizado e faça testes com os payloads reais da sua instância.

Confira também: Proxy Z-API: nova funcionalidade para aumentar o controle de rede para operações em escala em app de mensageria.

Plano de migração recomendado

Uma migração gradual reduz o risco de interromper o atendimento.

Etapa 1: inventário

Liste tabelas, endpoints, workers, dashboards e integrações que utilizam phone como chave.

Etapa 2: extensão do modelo

Adicione lid, chatLid e metadados sem remover o telefone existente. Crie índices e atualize as rotinas de leitura.

Etapa 3: captura

Passe a armazenar o LID em todos os webhooks que o apresentarem. Registre data, origem e mensagem associada.

Etapa 4: leitura preferencial

Atualize os lookups para procurar primeiro pelo LID e usar o telefone como fallback quando estiver disponível e for apropriado.

Etapa 5: envio controlado

Teste mensagens para contatos identificados por número e por LID. Registre status, erro, tempo e resposta.

Etapa 6: reconciliação

Crie uma rotina para identificar contatos duplicados, associações incompletas e eventos sem chave utilizável.

Etapa 7: observabilidade

Monitore falhas de parsing, mensagens sem destinatário, chatLid nulo, erros de envio e aumento de cadastros duplicados.

Etapa 8: rollout

Libere a nova lógica gradualmente e mantenha a possibilidade de voltar ao comportamento anterior para os fluxos em que o telefone ainda for necessário.

Checklist rápido

• Criar campo lid na tabela de contatos.
• Criar campo opcional para chatLid.
• Indexar o LID como texto.
• Aceitar valores com o sufixo @lid.
• Salvar contact.lid recebido nos webhooks.
• Tratar chatLid: null como retorno válido.
• Não usar phone como única chave primária.
• Atualizar buscas para preferir LID.
• Manter telefone como dado complementar.
• Implementar idempotência por messageId.
• Testar envio com número e com LID.
• Criar fallback somente quando fizer sentido.
• Revisar logs, máscaras e permissões.
• Atualizar dashboards e relatórios.
• Documentar o novo fluxo para suporte e desenvolvimento.

Conclusão

O LID representa uma mudança importante na forma como sistemas identificam contatos no aplicativo de mensageria. A plataforma pode continuar funcionando mesmo quando o número não estiver disponível, mas somente se a integração estiver preparada para lidar com identificadores privados.

O principal erro é tratar o LID como um telefone com outro formato. Ele tem finalidade, regras e limitações próprias. Armazene-o em campo dedicado, use-o para localizar o contato, aceite chatLid como opcional e mantenha o telefone apenas onde ele for realmente necessário.

A migração não precisa ser traumática. Comece pelo modelo de dados, atualize webhooks, adapte validações, teste o envio e monitore os casos em que o número não estiver presente.

Com o Z-API, sua empresa pode trabalhar com webhooks e integrações que preservam a continuidade do contato mesmo diante da variação entre telefone, LID e identificador de chat. A responsabilidade da aplicação é manter uma modelagem flexível, segura e coerente com os dados recebidos.

Recebeu um LID no webhook? Não descarte o evento. Salve o identificador, associe-o ao contato interno e adapte o fluxo de envio para usar o valor correto.

Perguntas frequentes

O que é o LID no app de mensageria da Meta?

É um identificador privado utilizado para representar um usuário sem depender da exposição direta do número de telefone em determinados eventos e integrações.

O LID é igual ao número de telefone?

Não. O LID é um identificador técnico e deve ser armazenado em campo próprio. Não aplique máscaras, validações de DDD ou regras de SMS sobre ele.

O que devo fazer quando phone retorna um valor com @lid?

Identifique o tipo do valor, salve-o como LID e não tente tratá-lo como um telefone numérico. Consulte os demais campos do payload para localizar informações complementares.

Por que chatLid vem como null?

O campo pode não estar disponível em determinados eventos ou tipos de conversa. Trate null como um retorno válido e use o LID do contato ou outro identificador disponível para processar a mensagem.

Posso enviar mensagem para um LID?

Quando o endpoint utilizado aceitar o formato, sim. Use exatamente o LID recebido no webhook e siga a documentação da integração.

Posso transformar LID em telefone?

Não presuma que essa conversão esteja disponível por API pública. O LID existe justamente para reduzir a exposição do número. Armazene o telefone somente quando ele for fornecido de forma legítima e autorizada.

Preciso remover o telefone do meu banco?

Não. O telefone pode continuar sendo necessário para SMS, autenticação, atendimento ou integrações externas. A recomendação é não utilizá-lo como única chave do relacionamento no aplicativo de mensagens.

O que muda na minha integração com o Z-API?

Você deve adaptar o tratamento dos webhooks, salvar o LID, aceitar @lid, tratar chatLid como opcional, revisar buscas e testar o envio para os identificadores disponíveis.