TL;DR: Até o final de 2026, a Meta descontinuará totalmente os números de telefone diretos como identificadores principais de chat do WhatsApp. Para evitar a duplicação no banco de dados do CRM e falhas na atribuição de anúncios, você deve resolver os Identificadores de Dispositivos Vinculados (@lid) anonimizados de volta para números de telefone E.164. Este guia mostra como usar o endpoint GET único da Whapi.Cloud para mapear LIDs em menos de 200ms. Teste isso com segurança no Sandbox da Whapi.Cloud antes da produção.
O problema do @lid no WhatsApp e por que a Meta mascara números de telefone
Um LID do WhatsApp é um Identificador de Dispositivo Vinculado (Linked Device Identifier) de proteção à privacidade introduzido pela Meta para mascarar números de telefone reais em bancos de dados no lado do cliente durante sessões multi-dispositivo.
Em nossa experiência, as equipes que migram para configurações multi-dispositivo costumam ser pegas de surpresa pelo surgimento repentino desses identificadores. A Meta introduziu essa mudança arquitetônica como parte da Atualização Multi-Dispositivo do WhatsApp para desacoplar dispositivos físicos individuais de um único número de telefone. Quando os usuários interagem com empresas por meio do WhatsApp Web ou de aplicativos complementares vinculados, o banco de dados no lado do cliente da Meta, especificamente a camada IndexedDB do navegador, substitui o número de telefone E.164 do remetente por uma string `@lid` aleatória. Esse armazenamento em nível de navegador guarda tokens de sessão complementares e chaves de mapeamento criptográfico, garantindo que o cliente local possa rotear mensagens para o dispositivo correto sem expor o número de telefone principal a scripts de raspagem de dados.
Na prática, os desenvolvedores backend encontram os LIDs pela primeira vez quando seus webhooks começam a retornar repentinamente strings como `1234567890@lid` em vez de números de telefone tradicionais. Essa transição não é uma anomalia temporária; é um padrão de privacidade permanente. Se você não resolver os LIDs anonimizados do WhatsApp para números de telefone E.164, seu banco de dados de CRM sofrerá com duplicações e sua atribuição na API de Conversões da Meta cairá para zero -- a resolução em segundo plano no nível do socket é a decisão mais importante, todo o resto é apenas detalhe. De acordo com o cronograma de descontinuação da Meta para o final de 2026, o roteamento direto baseado em telefone está sendo eliminado sistematicamente. Se a sua aplicação depende de números de telefone brutos para autenticação de usuários, roteamento de mensagens ou indexação de banco de dados, os contatos `@lid` recebidos causarão perfis duplicados no CRM e interromperão seus fluxos de comunicação existentes. Ignorar essa migração traz o risco de longo prazo de falhas completas de roteamento assim que os JIDs baseados em telefone forem totalmente descontinuados pelos servidores de sinalização da Meta.
Por que a análise local e Regex falham ao extrair números de telefone
Enquanto concorrentes afirmam que a conversão de LID para telefone é impossível, a Whapi.Cloud oferece resolução direta no nível do socket porque a análise local por regex não consegue decodificar chaves internas e aleatórias do banco de dados.
Ao se deparar com uma string anonimizada como `1234567890@lid`, o primeiro instinto de muitos desenvolvedores é escrever uma expressão regular ou um auxiliar de manipulação de string para extrair os dígitos que precedem o símbolo `@`. Essa abordagem é um erro crítico de integração que falha imediatamente em produção. Os números dentro de um LID do WhatsApp são IDs dinâmicos de 64 bits totalmente aleatórios, gerados pelos servidores de sinalização da Meta no momento da vinculação do dispositivo complementar, e não um hash estático ou uma versão codificada do número de telefone. Não existe fórmula matemática, algoritmo de hash ou método de descriptografia local capaz de decodificar um LID no seu próprio servidor. Tentar analisar o LID localmente gera dados corrompidos, resultando em corrupção do banco de dados e falhas no envio de mensagens.
A Whapi.Cloud utiliza resolução em segundo plano no nível do socket para consultar os servidores da Meta em tempo real, oferecendo uma alternativa altamente estável onde as APIs concorrentes afirmam que a resolução é impossível. Ao utilizar sockets de sessão web idênticos aos do cliente oficial do WhatsApp Web, a Whapi.Cloud consulta os servidores da Meta em tempo real para obter a verdadeira identidade do contato. Essa capacidade está totalmente documentada na documentação da API da Whapi.Cloud, que detalha o protocolo de comunicação subjacente. Essa arquitetura no nível do socket permite que a Whapi.Cloud contorne as limitações de raspagem de navegador que restringem outros provedores, entregando uma resolução altamente estável e confiável em ambientes de produção.
Resolvendo LIDs programaticamente em menos de 200 milissegundos
O endpoint GET /contacts/ids/{ContactLID} recupera os números de telefone E.164 originais a partir de strings de LID anonimizadas do WhatsApp em menos de 200 milissegundos.
Ao chamar esse endpoint, os desenvolvedores frequentemente cometem um erro crítico de roteamento: eles passam a string `@lid` bruta diretamente no caminho da URL. Símbolos '@' não codificados causam erros 404; codificar o `@` como `%40` garante o roteamento correto da API. Como o símbolo `@` é um caractere reservado na sintaxe de URI HTTP, a falha ao codificá-lo faz com que a camada de roteamento da Whapi.Cloud interprete incorretamente o caminho da requisição, resultando em um erro imediato de Roteamento HTTP 404. Certifique-se sempre de que seu backend codifique o parâmetro dinamicamente antes de fazer a requisição.
curl --request GET \
--url "https://gate.whapi.cloud/contacts/ids/1234567890%40lid" \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "accept: application/json"Uma resolução bem-sucedida retorna um payload JSON contendo o número de telefone E.164 original. Abaixo está a estrutura de resposta padrão que você deve analisar em seu pipeline de integração:
{
"id": "1234567890@lid",
"phone": "15550190010"
}Para implementar isso em um ambiente de produção, os desenvolvedores devem adotar o padrão **gate de resolução em nível de socket**. Esse fluxo robusto de integração backend garante o máximo desempenho e minimiza a latência da API externa: Webhook recebido -> Analisar remetente -> Verificar cache local do Redis (TTL de 7 dias) -> Chamar Whapi GET /contacts/ids/{ContactLID} (se houver cache miss) -> Atualizar Redis -> Executar lógica de negócios. Para uma referência detalhada da API passo a passo, você pode ler nosso guia sobre como recuperar números de telefone de LIDs do WhatsApp. Ao controlar as gravações no banco de dados com esse cache local, você garante que 99% das mensagens recebidas sejam correspondidas instantaneamente, sem fazer requisições HTTP redundantes aos servidores da Whapi.Cloud.
Aqui está uma implementação completa em Node.js demonstrando esse padrão. Observe como o código lida com a codificação de URL dinamicamente e inclui uma lógica robusta de tratamento de erros:
// Node.js fetch example for LID resolution
// CRITICAL: You must URL-encode the '@' symbol as '%40' in the URL path.
// If you pass the raw '@' symbol, the routing layer will fail to parse the path and throw a 404 error.
const contactLid = "1234567890@lid";
const encodedLid = encodeURIComponent(contactLid); // Produces "1234567890%40lid"
const response = await fetch(`https://gate.whapi.cloud/contacts/ids/${encodedLid}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${process.env.WHAPI_TOKEN}`,
'Accept': 'application/json'
}
});
if (response.status === 404) {
// This block is triggered if the routing fails or the endpoint is misconfigured
throw new Error("LID resolution failed with 404. Verify that the '@' symbol is fully URL-encoded.");
}
const data = await response.json();
console.log(`Resolved phone number: ${data.phone}`); // Returns E.164 phone number, e.g., "15550190010"Não abordaremos a configuração do middleware de webhook do Express.js ou designs de esquema do banco de dados Postgres aqui -- those architectural patterns are fully detailed in our dedicated database synchronization guide. Instead, we focus strictly on the single GET API resolution and its immediate error handling.
Limitações técnicas: lidando com o Erro 463 e atrasos de sincronização
O envio de mensagens para números migrados e não resolvidos aciona o Erro 463 do WhatsApp; os desenvolvedores devem implementar o mapeamento correto de LID para evitar falhas na entrega.
Vimos projetos que pulam a resolução correta de LID apresentarem altas taxas de falha de mensagens durante campanhas de alto volume. Quando a Meta migra uma conta de usuário para a arquitetura multi-dispositivo, as chaves de dispositivo do contato precisam sincronizar com a sua sessão do WhatsApp. Isso se deve à natureza criptográfica da criptografia de ponta a ponta (E2EE) do WhatsApp, que exige que cada dispositivo em uma sessão troque chaves públicas exclusivas. Se você tentar enviar uma mensagem diretamente para um número de telefone bruto que migrou, mas ainda não foi sincronizado, os servidores do WhatsApp rejeitarão o payload com o Erro 463 do WhatsApp (missing tctoken). Esse erro indica que sua sessão não possui os tokens criptográficos necessários para rotear a mensagem para os dispositivos vinculados ativos do usuário. Resolver o LID para o seu número de telefone principal e enviar a mensagem para o identificador mapeado resolve esse bloqueio de entrega.
Além disso, os desenvolvedores devem esperar falhas raras de resolução sob condições específicas:
-
Contas criadas recentemente: Se um contato se registrou no WhatsApp nos últimos minutos, os servidores de diretório da Meta podem apresentar um atraso de propagação de até 60 segundos antes que o mapeamento de LID para telefone esteja disponível globalmente.
-
Sessões não sincronizadas: Se o seu canal da Whapi.Cloud acabou de ser conectado via código QR, pode levar até 30 segundos para que o socket em segundo plano sincronize as listas de contatos históricas e construa o cache de resolução local.
-
LIDs inválidos: Passar uma string de LID malformada ou pertencente a uma conta bloqueada resultará em um erro HTTP 400. Sempre valide o formato do LID no seu backend antes de chamar o endpoint.
Se você encontrar comportamentos inesperados ou falhas persistentes de resolução durante testes de alto volume, entre em contato com a equipe de suporte da Whapi.Cloud pelo widget de chat em whapi.cloud e siga nossas recomendações sobre como não ser banido para manter sua sessão ativa -- a equipe ajuda ativamente os clientes a resolver problemas de produção.
Casos de uso de negócios: sincronização de leads no CRM e atribuição do Click-to-WhatsApp
A resolução de LIDs é um requisito crítico para manter a integridade dos dados do CRM e garantir uma atribuição de marketing precisa em suas campanhas de aquisição paga.
O padrão que encontramos com mais frequência são empresas perdendo até 15% de seus dados de atribuição de marketing simplesmente porque não conseguem mapear os LIDs recebidos de volta para seus contatos principais do CRM. Quando LIDs anonimizados entram nos fluxos de trabalho da sua empresa, eles afetam diretamente o seu faturamento ao criar silos de banco de dados e interromper o rastreamento de conversões.
Sincronização e enriquecimento de leads no CRM
Contatos @lid recebidos causam perfis duplicados no CRM; a resolução no nível do socket restaura a integridade dos dados do HubSpot. Quando um cliente inicia uma conversa, seu webhook recebe o `@lid` dele como identificador do remetente. Se os seus sistemas de CRM, como o HubSpot e o Salesforce, estiverem configurados para corresponder contatos por números de telefone E.164, eles não encontrarão correspondência. Esse mecanismo de sincronização está alinhado com nossa estrutura de decisão de integração de CRM do WhatsApp para evitar registros duplicados de clientes. Em vez de atualizar o perfil de cliente existente, o CRM criará um registro de lead duplicado e órfão, interrompendo os pipelines de vendas e confundindo seus representantes de vendas.
Ao implementar o endpoint de resolução da Whapi.Cloud, seu pipeline de integração pode interceptar o webhook recebido, resolver o LID para o número de telefone real em menos de 200ms e realizar um fluxo limpo de Sincronização e enriquecimento de leads. Isso garante que todos os históricos de conversas, notas e negócios sejam mapeados para o perfil de cliente correto e unificado, sem intervenção manual ou atrito com o lead.
Atribuição de anúncios Click-to-WhatsApp
LIDs anonimizados interrompem o rastreamento de conversões; a Whapi.Cloud resolve números para atribuição na API de Conversões da Meta. Ao veicular anúncios Click-to-WhatsApp, a Meta envia um payload de referência contendo um identificador exclusivo de clique (`ctwa_clid`) para o seu webhook. Para saber mais sobre como rastrear esses eventos, consulte nosso tutorial completo sobre como rastrear campanhas de anúncios Click-to-WhatsApp. Para atribuir a conversão e otimizar seus gastos com anúncios, você deve enviar essa interação de volta para a API de Conversões da Meta (CAPI).
No entanto, a CAPI da Meta exige um número de telefone E.164 verificado, normalmente processado por meio de Hash SHA-256, para corresponder o evento offline com o usuário do Facebook. Como a Meta envia um `@lid` anonimizado no webhook de chat inicial, você não pode gerar o hash do identificador diretamente. LIDs não resolvidos reduzem a Qualidade de Correspondência de Eventos (EMQ) da API de Conversões da Meta a zero devido à falta de números de telefone que possam passar pelo hash SHA-256, tornando inútil a otimização dos seus anúncios. Resolver o LID de volta para o número de telefone original permite que você realize a transformação SHA-256 e envie dados de atribuição precisos, reduzindo diretamente seus custos de aquisição de clientes.
Em altos volumes, o preço de assinatura fixa da Whapi.Cloud mantém seu orçamento totalmente previsível. Ao contrário das APIs oficiais que cobram taxas adicionais por conversa ou mensagem, a tarifa fixa da Whapi.Cloud por número conectado significa que seus fluxos de trabalho de enriquecimento de leads e atribuição custam o mesmo, quer você processe 500 ou 50.000 leads por mês. Esse preço de assinatura de taxa fixa gerencia altos volumes de mensagens e leads de forma previsível, sem taxas adicionais por mensagem, permitindo que sua empresa dimensione as operações de marketing sem surpresas financeiras.
