Resumo: O WhatsApp substitui números de telefone por BSUIDs (Business-Scoped User IDs) em junho de 2026. Armazene ambos os campos no seu banco de dados, implemente o padrão de fallback de 3 camadas para resolução de identificadores, e espere que o campo from nos webhooks torne-se nulo. Formato BSUID: país.alfanumérico — ex.: US.13491208655302741918.
Junho de 2026 vai quebrar chatbots baseados em números de telefone. O WhatsApp está lançando nomes de usuário e um novo sistema de identificação chamado BSUID (Business-Scoped User ID). Os números de telefone desaparecem; os BSUIDs permanecem. Se sua integração armazena apenas números de telefone, envia mensagens para endereços E.164, ou assume que o campo from sempre contém um número de telefone, você está construindo sobre uma base que desmoronará em semanas.
Este guia é para desenvolvedores backend que executam automação do WhatsApp em produção: criadores de chatbots, fundadores de SaaS com sistemas de notificação, e engenheiros de integração que mantêm stacks de mensageria empresarial. Você precisa entender o que é BSUID, por que quebra sistemas existentes, e exatamente como migrar antes de junho de 2026.
O que é BSUID e por que junho de 2026 muda tudo
Formato BSUID: código de país mais entropia que você deve armazenar. Um Business-Scoped User ID combina um código de país com uma string alfanumérica: {país}.{alfanumérico}. Exemplo: US.13491208655302741918. Este identificador substitui o número de telefone como o endereço principal para interações com WhatsApp Business API.
A mudança não é cosmética. O WhatsApp está introduzindo nomes de usuário que os usuários podem configurar para ocultar seus números de telefone dos contatos comerciais. Quando um usuário oculta seu número de telefone, o BSUID torna-se o único identificador disponível. Isso é conceitualmente o mesmo que LID (Line Identity), para o qual o WhatsApp tem migrado desde 2024. A diferença: LID foi uma transição interna; BSUID é a realidade voltada ao público que seu código deve lidar.
A fonte autoritativa confirma o cronograma: Nomes de usuário do WhatsApp e BSUID serão lançados em junho de 2026. Conforme observado no FAQ da Whapi.Cloud sobre nomes de usuário do WhatsApp, BSUID é conceitualmente o mesmo que LID — é o novo identificador principal para trabalho com API. Sistemas que não se adaptarem experimentarão falhas silenciosas indistinguíveis de envios bem-sucedidos.
Vimos este padrão de migração antes. Quando o WhatsApp mudou a infraestrutura interna de endereçamento baseado em telefone para roteamento baseado em LID, bibliotecas open-source enfrentaram mudanças disruptivas. Os mesmos padrões se repetem com BSUID — exceto que desta vez, o impacto é voltado para fora. Sua mensagem pode ser reportada como enviada enquanto nunca chega ao usuário.
O cenário de falha: quando números de telefone se tornam fantasmas
Chats fantasmas: mensagens enviadas para números que ninguém recebe. Esta é a falha concreta que seus usuários experimentarão se você não migrar. Quando o WhatsApp habilitar completamente a privacidade de nomes de usuário, usuários que ocultaram seus números de telefone não receberão mais mensagens enviadas para seu endereço E.164. Sua chamada à API retorna sucesso — HTTP 200, ID de mensagem atribuído — mas a mensagem entra em um vazio de entrega.
Assim é como o cenário de chat fantasma parece na prática. Seu sistema armazena o número de telefone de um cliente: +12025551234. Você envia uma mensagem usando esse número como destino. A API aceita a solicitação. Mas o usuário habilitou a privacidade de nome de usuário, então seu cliente do WhatsApp não roteia mais mensagens endereçadas por número de telefone. A mensagem é descartada silenciosamente. Os payloads de webhook que você recebe também podem mudar quando usuários ocultam seus números.
// CENÁRIO DE CHAT FANTASMA — Este código vai quebrar em junho de 2026
// Enviar para número de telefone quando o usuário o ocultou = falha silenciosa
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WHAPI_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+12025551234', // Número de telefone — PODE NÃO SER ENTREGUE
body: 'Seu pedido foi enviado!'
})
});
// HTTP 200 retornado, mensagem aparece como enviada
// Mas o usuário nunca a recebe — chat fantasma criado
console.log('Mensagem enviada:', response.data);
O fenômeno de chat fantasma já é observável na fase de migração LID. Desenvolvedores relatam números de telefone válidos retornando null de APIs de lookup, e mensagens enviadas para esses números criando conversas não entregues. Quando a transição para BSUID completar em junho de 2026, isso se tornará o comportamento padrão para usuários com privacidade habilitada — não um caso extremo.
Considerações típicas: Chats fantasmas são piores que erros visíveis. Uma entrega falhada com código de erro aciona lógica de retry e alertas. Um chat fantasma parece sucesso em seus logs enquanto o cliente não recebe nada. Suas métricas mostram 98% de entrega enquanto o alcance real pode ser 60% ou menos para usuários com privacidade habilitada.
Como a API quebra: de webhooks a chaves de banco de dados
Campo from nulo: suas suposições de banco de dados morrem. A mudança mais disruptiva está nos payloads de webhook. Quando um usuário oculta seu número de telefone, o campo from em webhooks de mensagens recebidas pode estar vazio ou nulo. Sistemas construídos em torno da suposição de que cada mensagem tem um número de telefone válido como remetente falharão na etapa de parsing.
Conforme documentado pela Azure Communication Services (2024): "O campo from agora pode estar vazio ou nulo quando um usuário oculta seu número de telefone." Isso não é um risco teórico. É uma mudança de comportamento documentada que afeta como você analisa webhooks, armazena histórico de conversação, e vincula mensagens recebidas a registros de clientes.
O impacto no banco de dados é igualmente severo. E.164 era para sempre até o WhatsApp mudar para sempre. Sistemas existentes frequentemente usam números de telefone como chaves estrangeiras vinculando tabelas de conversação a tabelas de clientes. Quando BSUIDs substituem números de telefone como identificadores principais, essas relações de chave estrangeira quebram. Uma consulta de banco de dados usando WHERE phone = '+12025551234' não retorna resultados quando o identificador agora é US.13491208655302741918.
Incompatibilidade de modelo de dados é o custo oculto desta migração. Sistemas que assumem que campos to e from sempre contêm números de telefone E.164 experimentarão quebra de chave estrangeira, registros de clientes duplicados criados sob BSUIDs, e perda de threading de conversação. A migração requer mudanças de esquema, não apenas atualizações de código.
Comparação de Número de Telefone vs LID vs BSUID:
| Atributo | Número de Telefone (E.164) | LID (Line Identity) | BSUID (Business-Scoped User ID) |
| Formato | +{país}{número} ex.: +12025551234 |
{alfanumérico} ex.: [email protected] |
{país}.{alfanumérico} ex.: US.13491208655302741918 |
| Visibilidade | Público (se o usuário permitir) | Interno | Voltado à API |
| Disponibilidade | Diminuindo — usuários podem ocultar | Transicionando para BSUID | Principal a partir de junho de 2026 |
| Confiabilidade de lookup | Ainda funciona (por enquanto) | Retorna null para usuários válidos | Direta — sem lookup necessário |
| Requisito de armazenamento | Manter para compatibilidade retroativa | Obsoleto | Chave primária obrigatória |
O padrão de fallback de três camadas
Lookup LID falha; fallbacks salvam produção. APIs de lookup que resolvem números de telefone para LIDs já estão retornando null para usuários válidos do WhatsApp. O evento webhook lid-mapping.update dispara inconsistentemente, impedindo mapeamento LID-para-telefone confiável. Um sistema de produção não pode depender apenas de lookup. Ele precisa de uma estratégia de fallback quando a resolução falha.
O padrão de fallback de 3 camadas emergiu da migração LID e aplica-se diretamente à adaptação BSUID. Observamos este padrão em sistemas de produção processando milhões de mensagens. As camadas operam em sequência: BSUID primeiro, lookup LID segundo, retry por telefone terceiro. Cada camada lida com o modo de falha da anterior.
Camada 1 — Envio direto por BSUID: Se você tem o BSUID de uma interação anterior ou webhook, envie diretamente usando-o. Este é o caminho mais confiável — sem lookup necessário, sem ambiguidade de resolução. O formato BSUID é previsível: país.alfanumérico.
Camada 2 — Lookup LID com cache: Se você tem um número de telefone mas não BSUID, tente lookup LID via endpoint /contacts/lids. Armazene mapeamentos bem-sucedidos em Redis ou seu banco de dados com TTL. O lookup pode retornar null — isso é esperado. Vá para a camada 3 quando isso acontecer.
Camada 3 — Retry por telefone com detecção de fantasmas: Envie para o número de telefone como fallback. Monitore recibos de entrega. Se uma mensagem para um usuário conhecido como ativo não mostrar confirmação de entrega dentro de 24 horas enquanto outras mensagens são entregues, marque para revisão manual. Este é seu detector de chats fantasmas.
// PADRÃO DE FALLBACK DE TRÊS CAMADAS para migração BSUID
// Tenta BSUID → Lookup LID → Telefone com detecção de fantasmas
async function sendWithFallback(phoneNumber, messageBody) {
// Camada 1: Tenta BSUID em cache primeiro
const cachedBSUID = await db.get(`bsuid:${phoneNumber}`);
if (cachedBSUID) {
return await sendMessage(cachedBSUID, messageBody, 'bsuid');
}
// Camada 2: Tenta lookup LID com caching
try {
const lidResponse = await fetch(
`https://gate.whapi.cloud/contacts/lids/${phoneNumber}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const lidData = await lidResponse.json();
if (lidData.lid) {
// Converte LID para formato BSUID e armazena em cache
const bsuid = `${lidData.country}.${lidData.identifier}`;
await db.setex(`bsuid:${phoneNumber}`, 86400, bsuid);
return await sendMessage(bsuid, messageBody, 'bsuid');
}
} catch (e) {
// Lookup falhou — registra e continua para fallback
logger.warn(`Lookup LID falhou para ${phoneNumber}`);
}
// Camada 3: Fallback por telefone com flag de detecção de fantasmas
// Sem este fallback, usuários válidos não recebem nada
const result = await sendMessage(phoneNumber, messageBody, 'phone');
await db.sadd('ghost-watch', phoneNumber); // Monitora entrega
return result;
}
Projetos que pulam o padrão de 3 camadas tendem a ver quedas súbitas na entrega quando o WhatsApp lança privacidade de nomes de usuário em novas regiões. O padrão de fallback não é codificação defensiva — é a arquitetura mínima viável para junho de 2026.
O que seu esquema de banco de dados deve armazenar agora
Quebra de chave estrangeira de banco de dados é a dor de migração que desenvolvedores relatam mais frequentemente. Sistemas que assumem números de telefone E.164 como identificadores imutáveis falharão. Você precisa de um esquema que trate números de telefone como um de múltiplos identificadores possíveis, não a chave primária.
Mudanças de esquema necessárias:
-
Campo de identificador primário: Adicione
bsuid VARCHAR(50)como a chave de lookup principal para operações do WhatsApp. Formato:XX.XXXXXXXXXXXXXXXXXXX(código de país + ponto + 17-20 dígitos numéricos). -
Campo de telefone secundário: Mantenha
phone VARCHAR(20)para compatibilidade retroativa e exibição legível, mas remova restrições de chave estrangeira apontando para ele. -
Cache de resolução de identificadores: Adicione uma tabela de lookup
identifier_mappings (phone, bsuid, lid, last_updated, source)para cachear resultados de resolução e rastrear proveniência. -
Parser de webhook null-seguro: Atualize handlers de webhook para aceitar campos
fromanuláveis. Quando nulo, extraia identidade do remetente dos campos BSUID se presentes. -
Timestamp de migração: Adicione
bsuid_migrated_atpara rastrear quais registros foram atualizados com BSUIDs.
O padrão que encontramos mais frequentemente em migrações: equipes tentam manter números de telefone como chaves primárias e armazenar BSUID como um campo secundário opcional. Isso falha quando um usuário oculta seu número de telefone — você cria um registro de cliente duplicado sob o BSUID, fragmentando histórico de conversação e dados de pedidos. BSUID deve ser o identificador canônico; telefone é metadata de exibição.
Impacto na indústria: exemplos de e-commerce e saúde
70% de automação significa zero por cento se identificadores quebrarem. A migração BSUID não é apenas uma refatoração técnica — ameaça o valor operacional. Empresas de e-commerce que automatizam 70% das consultas de suporte via WhatsApp verão essa automação cair para zero se sua resolução de identificadores falhar. Clínicas de saúde que conseguem redução de 40-65% em faltas através de lembretes de consultas perderão essa eficiência se mensagens se tornarem chats fantasmas.
Caso de uso de e-commerce: Rastreamento de pedidos, recuperação de carrinhos abandonados e automação de suporte ao cliente dependem de entrega confiável de mensagens. Uma configuração típica envia milhares de mensagens diariamente. Se 30% vão para usuários que habilitaram privacidade de nome de usuário, e o sistema não migrou para tratamento BSUID, isso representa centenas de mensagens não entregues por dia. Clientes não recebem notificações de envio. O volume de tickets de suporte aumenta.
Caso de uso de saúde: Bots de lembrete de consultas conseguem redução de 40-65% em faltas quando mensagens chegam confiavelmente aos pacientes. A automação depende de mensagens enviadas agendadas para números de telefone confirmados. Se o sistema de lembretes não armazenou BSUIDs e o lookup LID retorna null, o lembrete torna-se um chat fantasma. O paciente perde a consulta. A clínica perde receita.
Ambos os setores dependem de roteamento previsível de mensagens. A migração BSUID introduz imprevisibilidade exatamente onde esses fluxos de trabalho requerem confiabilidade. A migração não é manutenção opcional — é preservação de valor operacional.
Checklist de migração para junho de 2026
Migre agora ou migre em emergência depois. O checklist abaixo cobre os passos essenciais para preparar sua integração do WhatsApp para a transição BSUID. Complete estes antes de junho de 2026 para evitar chats fantasmas e falhas de entrega.
Pré-migração (Complete até maio de 2026):
-
Auditar o esquema atual do banco de dados — identificar todas as tabelas usando números de telefone como chaves estrangeiras
-
Implementar coluna BSUID junto a números de telefone em tabelas de clientes e conversações
-
Implantar padrão de fallback de 3 camadas na lógica de envio de mensagens
-
Atualizar parsers de webhook para lidar com campos
fromnulos graciosamente -
Testar o comportamento do endpoint de lookup LID — documentar o tratamento de respostas null
Migração (Complete até 1º de junho de 2026):
-
Povoar BSUIDs em lote para contatos existentes via API de lookup LID
-
Mudar a lógica de envio principal para usar BSUID como identificador de primeira prioridade
-
Habilitar monitoramento de chats fantasmas — rastrear mensagens sem confirmação de entrega dentro de 24 horas
-
Atualizar documentação de suporte ao cliente para referir-se a BSUID em vez de número de telefone
Monitoramento pós-migração: Fique atento a registros de clientes duplicados — um sinal de que lookups baseados em telefone estão perdendo registros migrados de BSUID. Monitore taxas de entrega por tipo de identificador. Espere 95%+ de entrega via BSUID, 80-90% via fallback por telefone, com a diferença representando o risco de chat fantasma.
Por que a Whapi.Cloud lida com BSUID sem quebrar
Baileys quebrou; Whapi.Cloud se preparou. O ecossistema de bibliotecas open-source tem lutado com as migrações de identidade do WhatsApp. Desenvolvedores relatam erros Bad MAC, falhas No Session, e exceções Invalid PreKey quando transições LID ocorrem. Estes não são bugs de camada de aplicação — são fraturas de camada de protocolo que requerem correções em nível de infraestrutura.
A Whapi.Cloud absorve mudanças de protocolo a montante para que sua superfície de API permaneça estável. A arquitetura de socket de sessão web — o mesmo mecanismo que o WhatsApp Web usa — fornece uma base mais estável que abordagens de emulação de navegador. Quando o WhatsApp muda formatos de identificador, a equipe de infraestrutura da Whapi.Cloud lida com a adaptação de protocolo. Suas chamadas HTTP à API permanecem inalteradas.
Integrações open-source quebram às 3h da manhã sem parte responsável. A Whapi.Cloud tem uma equipe de suporte ao vivo que ajuda ativamente os clientes a resolver problemas de produção — incluindo orientação de migração para preparação BSUID. Guiamos centenas de integrações através de mudanças de protocolo. O reconhecimento de padrões dessa história operacional alimenta melhorias de infraestrutura que previnem quebras. Para equipes decidindo entre bibliotecas auto-hospedadas e gateways gerenciados, a migração BSUID é um ponto de decisão. Stacks auto-hospedados requerem que você monitore issues do GitHub, aplique patches, teste mudanças de protocolo, e lidere o tempo de migração você mesmo. Infraestrutura gerenciada transfere essa carga operacional para o provedor. Dado que o WhatsApp faz mudanças de protocolo sem aviso, o caminho gerenciado oferece previsibilidade que o auto-hospedado não pode igualar em escala pequena a média.
Se você encontrar comportamento inesperado durante sua migração BSUID, entre em contato com a equipe de suporte da Whapi.Cloud via widget de chat em whapi.cloud — a equipe ajuda ativamente os clientes a resolver problemas de produção.
Não cobriremos o caminho de migração da API oficial do WhatsApp Business aqui — isso requer verificação de negócio Meta, fluxos de trabalho de aprovação de templates, e tiers de preços por mensagem que são incompatíveis com a arquitetura de API não oficial. Para equipes comprometidas com a API oficial, consulte a documentação BSP da Meta diretamente.
