Usernames do WhatsApp e BSUID: o Que Muda na API Oficial

Os usernames do WhatsApp vão quebrar uma premissa que quase todo sistema de atendimento assume sem perceber: a de que o número de telefone identifica o cliente. Quando o usuário adotar um nome de usuário, o telefone pode simplesmente deixar de chegar no webhook. Neste guia eu mostro o que muda na API oficial, o que a Meta já confirmou, o que ainda está em aberto e como preparar CRM, automações e campanhas antes que o primeiro contato "sem número" apareça na sua fila.

TL;DR

• Desde abril de 2026 todo webhook de mensagem traz o BSUID (user_id), um identificador do usuário restrito ao seu portfólio de negócios.
• Quando o cliente adotar username, o campo wa_id (o telefone) pode vir vazio. Ele só continua chegando se houve troca de mensagem ou ligação com aquele número nos últimos 30 dias ou se o contato está no contact book.
• Suportar BSUID é obrigatório para parceiros, empresas integradas direto na Cloud API e anunciantes de Click-to-WhatsApp.
• A data de lançamento dos usernames para o público não foi confirmada: a Meta fala apenas em liberação "gradual em 2026".
• Preparação mínima: CRM aceitando user_id como chave, nenhuma mensagem descartada por falta de telefone e um fluxo com o botão REQUEST_CONTACT_INFO para pedir o número quando ele for indispensável.

O que são os usernames do WhatsApp e o BSUID

O username é um nome de usuário público, no estilo das outras redes da Meta, que a pessoa pode usar no lugar do número para ser encontrada no WhatsApp. A adoção é opcional tanto para usuários quanto para empresas, segundo a documentação oficial de BSUID. O efeito colateral para quem integra a API é a privacidade: quem adota username passa a ter o telefone protegido, inclusive da empresa com quem conversa.

Para não deixar as integrações sem chave quando os usernames do WhatsApp chegarem ao público, a Meta criou o BSUID (business-scoped user ID, ou ID de usuário restrito ao negócio). Pense nele como um "CPF do cliente dentro do seu portfólio": é estável enquanto o usuário mantiver o mesmo número, mas não serve para nada fora do seu portfólio de negócios.

Como é o formato do BSUID

• Começa com o código do país em duas letras (ISO 3166) e um ponto, seguido de até 128 caracteres alfanuméricos. Um exemplo do formato brasileiro: BR.1234....
• É restrito ao portfólio de negócios. O mesmo cliente tem BSUIDs diferentes em portfólios diferentes.
• É regenerado se o usuário trocar de número. A Meta envia um webhook de mensagem de sistema avisando a troca.
• Existe ainda o parent BSUID (com ENT depois do código do país), que vale para um conjunto de portfólios inscritos. A elegibilidade é definida pelo contato da Meta com a empresa; para a maioria das PMEs ele não se aplica.

Os campos novos que chegam no webhook

Campo	O que traz	Quando aparece
user_id	O BSUID do cliente	Sempre, em todo webhook de mensagens
username	O nome de usuário do cliente	Só se ele ativou o recurso
wa_id	O telefone, como sempre foi	Omitido quando a Meta não pode incluir o número
parent_user_id	O parent BSUID	Só se o recurso estiver habilitado para o portfólio

A linha que importa é a do wa_id. Todo sistema que usa esse campo como chave primária do contato vai precisar de outro caminho.

Cronologia dos usernames do WhatsApp: o que já está confirmado

Esta mudança não caiu de uma vez. Ela veio em etapas ao longo de 2026, e a parte que mais preocupa ainda não tem data.

Quando	O que aconteceu	Status
Início de abril/2026	BSUID passa a vir em todos os webhooks	Confirmado pela Meta
05/05/2026	Envio para BSUID no endpoint de Marketing Messages	Confirmado (changelog)
29/06/2026	Empresas podem reservar username (WhatsApp Manager, Meta Business Suite, app Business ou Username API)	Confirmado
Início de julho/2026	Botão REQUEST_CONTACT_INFO disponível	Confirmado
Julho/2026	Envio de mensagens para BSUID pela API	Confirmado
15/09/2026	Webhook business_username_updates ganha o contexto revoked	Confirmado (changelog)
"Gradualmente em 2026"	Usernames liberados para os usuários finais	Sem data confirmada

Usernames de empresa aprovados ficam com status reserved até o recurso ser liberado para todos. Ou seja: a infraestrutura técnica já está no ar, e a única variável é o dia em que os seus clientes começam a ativar o recurso. Quem deixar a adaptação para "quando lançar" vai descobrir o problema pelo relatório de leads sem telefone.

Vale registrar outra mudança recente: a Política de Mensagens do WhatsApp Business, atualizada em 23/09/2026, passou a dizer que a empresa só pode contatar quem forneceu o número ou o username e deu opt-in. O username virou, oficialmente, um dado de contato.

O que os usernames do WhatsApp mudam para quem usa o telefone como chave

Na Agathas, eu integro a API oficial do WhatsApp com sistemas que nasceram assumindo o telefone como identidade: plataformas Moodle que localizam o aluno pelo celular, sistemas de cobrança que cruzam número com cadastro, CRMs que deduplicam leads pelo DDD + número. Os usernames do WhatsApp afetam cada um desses pontos de um jeito diferente.

Quando o telefone continua chegando

A Meta mantém o número no webhook em três situações, todas confirmadas na documentação:

1. A empresa enviou mensagem ou ligou para aquele número nos últimos 30 dias.
2. A empresa recebeu mensagem ou ligação daquele número nos últimos 30 dias.
3. O usuário está no contact book da empresa.

Um detalhe que pega muita gente: a janela de 30 dias é contada por número comercial. Se a sua empresa tem um número de vendas e outro de suporte, o histórico de um não protege o outro.

O contact book da Meta

O contact book é um registro mantido pela própria Meta, no nível do portfólio de negócios, que guarda automaticamente as informações de contato depois das interações. Ele tem duas limitações: só armazena interações que acontecerem depois do lançamento do recurso, e pode ser desativado nas configurações do Meta Business Suite. Desativar sem entender o impacto, justamente quando os usernames do WhatsApp começarem a se espalhar, é uma forma rápida de perder telefones.

Quando o telefone some

O cenário crítico dos usernames do WhatsApp é o cliente novo, ou o cliente antigo que ficou mais de 30 dias sem falar com aquele número, e que já usa username. Nesse caso, a mensagem chega com user_id, talvez com username, e sem wa_id. Se o seu sistema rejeita o evento, a conversa some. Se ele cria o contato com telefone vazio, você ganha duplicatas e perde o histórico.

Usernames do WhatsApp no CRM e nos webhooks: como adaptar a integração

A própria Meta resume a tarefa em três frentes: atualizar os webhooks para suportar BSUID, construir lógica para lidar com múltiplos identificadores e atualizar os sistemas internos e externos ligados à integração. Traduzindo para o dia a dia de uma operação:

O checklist técnico

• Nova coluna de identidade. O contato precisa ter bsuid (e parent_bsuid, se você usar) além do telefone. O telefone vira um atributo opcional, não a chave.
• Busca em cascata. Ao receber um webhook, procure o contato primeiro pelo user_id; se não achar, pelo wa_id; só então crie um novo. Quando os dois vierem juntos, grave a associação. É assim que você constrói a ponte enquanto o telefone ainda chega.
• Nunca descarte evento sem wa_id. Validação que exige telefone precisa cair.
• Troca de número. Trate o webhook de mensagem de sistema que avisa a mudança: o BSUID antigo deixa de valer e um novo é gerado. Atualize o vínculo em vez de criar outro contato.
• Envio. A documentação pede que BSUIDs sejam enviados em campos dedicados das requisições de envio, não no mesmo campo que aceita telefone. Revise a camada que monta o payload.
• Autenticação. Templates de autenticação one-tap, zero-tap e copy code exigem telefone. Se você manda código de login pelo WhatsApp, guarde o número desses usuários.

Quando NÃO vale reescrever tudo

Se a sua operação é pequena, com um atendente e poucas centenas de conversas por mês, você não precisa reconstruir o CRM por causa dos usernames do WhatsApp em si. Basta garantir que a plataforma de atendimento aceite contatos identificados por BSUID e que nenhuma automação dependa do telefone para funcionar. Reescrever integrações por precaução, sem saber se elas de fato usam o wa_id, é gasto sem retorno. Comece mapeando onde o telefone é lido.

Armadilhas que eu já vejo no mapeamento

• Planilha exportada como "CRM". Se o time exporta conversas para planilha e cruza por telefone, contatos sem número vão sumir da análise.
• Integrações em cadeia. O webhook entra numa ferramenta de automação, que repassa para o CRM, que repassa para o ERP. Basta um elo exigir telefone para a cadeia inteira quebrar.
• Deduplicação agressiva. Rotinas que mesclam contatos "sem telefone" num registro genérico vão juntar clientes diferentes.

Click-to-WhatsApp e atribuição de anúncios

Os usernames do WhatsApp afetam também quem compra mídia. Anunciantes de Click-to-WhatsApp (CTWA) estão explicitamente na lista de quem precisa suportar BSUID. Faz sentido: o lead que chega de um anúncio é, por definição, um contato novo, exatamente o perfil que tem menos chance de ter histórico de 30 dias com o seu número.

Isso importa ainda mais depois de 28/09/2026, quando a janela gratuita aberta por anúncio CTWA passou de 72 horas para até 7 dias, segundo a página de preços da Meta. Mais tempo de conversa gratuita com o lead é ótimo, mas só se o seu sistema souber quem ele é.

Onde a atribuição pode quebrar

• Lead entra no CRM sem telefone e o vendedor não consegue ligar ou cruzar com outros canais.
• Eventos de conversão que você devolve para a Meta usando o telefone como chave do usuário podem chegar incompletos. Neste ponto a Meta não publicou nenhuma mudança específica da Conversions API ligada aos usernames; teste o seu fluxo antes de assumir que nada muda.
• Relatórios de campanha que contam leads por número único vão subcontar.

Com os usernames do WhatsApp em uso, a saída prática é pedir o telefone dentro da conversa quando ele for necessário para o negócio, e não presumir que ele virá de graça.

O botão REQUEST_CONTACT_INFO: como pedir o número sem atrito

Com os usernames do WhatsApp em vigor, nos casos em que o telefone é indispensável (entrega, cobrança, nota fiscal, retorno por ligação), a Meta liberou no início de julho de 2026 o botão REQUEST_CONTACT_INFO. Quando o cliente toca nele, o número de WhatsApp dele é compartilhado na conversa e a empresa recebe um webhook de contato com o telefone.

O botão funciona em templates de utility e de marketing e em mensagens interativas. Algumas regras que eu sigo ao desenhar esse fluxo:

1. Peça no momento em que o número tem utilidade óbvia. "Para enviarmos o código de rastreio, compartilhe seu número" converte melhor que um pedido solto na saudação.
2. Não condicione o atendimento ao número. Quem escolheu username escolheu privacidade. Travar a conversa até ele ceder é o jeito mais rápido de perder o lead.
3. Use mensagem interativa dentro da janela de atendimento em vez de template quando possível; desde 01/10/2026 tanto mensagens de serviço (acima da franquia de 1.000 por número ao mês) quanto utility na janela custam R$ 0,035 no Brasil, então cada mensagem extra do fluxo entra na conta.
4. Grave o vínculo BSUID ↔ telefone assim que o webhook de contato chegar.

Quanto custa se preparar (e quanto custa não se preparar)

Preparar a integração para os usernames do WhatsApp não tem tarifa da Meta. O custo está no trabalho de integração e nas mensagens extras que você passa a enviar.

Item	Custo	Observação
Receber e armazenar BSUID	Sem tarifa da Meta	Trabalho de desenvolvimento no CRM/integração
Mensagem pedindo o número (interativa, na janela)	R$ 0,035 acima da franquia	Tarifa de serviço no Brasil desde 01/10/2026
Template utility com o botão	R$ 0,035	Tabela oficial em BRL vigente desde 01/10/2026
Template marketing com o botão	R$ 0,3217	Cerca de 9 vezes o utility
Não se preparar	Leads perdidos, duplicados ou sem atribuição	O custo aparece no funil, não na fatura

Os valores são da tabela oficial da Meta em BRL; se você quer entender o modelo de cobrança inteiro, escrevi sobre isso no guia de custo por conversa na API oficial do WhatsApp.

Quando fazer

A resposta curta: agora, enquanto o telefone ainda chega para a maioria dos contatos. Cada conversa que acontece hoje, com user_id e wa_id juntos, é uma associação que você grava de graça. Depois que os usernames do WhatsApp estiverem abertos ao público, essa ponte passa a depender do contact book e da janela de 30 dias.

Username da sua empresa: reservar ou não

Os usernames do WhatsApp também valem para o lado da empresa. Desde 29/06/2026 ela pode reservar um nome pelo WhatsApp Manager, pelo Meta Business Suite, pelo app WhatsApp Business ou pela Username API. Quando a empresa tem username e nome de exibição, o nome de exibição aparece primeiro no perfil, na lista de conversas e nas mensagens, para o cliente reconhecer a marca.

Eu recomendo reservar cedo se a sua marca é disputada ou se você vai divulgar o contato em mídia impressa e anúncios, porque um username é mais fácil de lembrar que um número. Não há pressa se a empresa é local, atende uma base fixa e divulga o número há anos: o username é opcional e o número continua funcionando.

Dois cuidados. No novo modelo de contas que a Meta começou a liberar em 23/09/2026, o username pertence à WhatsApp account (a parte que guarda número, perfil e catálogo), separada da Messaging account que cuida de templates e cobrança, segundo a documentação de evolução do modelo de contas. E o webhook business_username_updates agora informa quando um username é revogado, então vale monitorá-lo.

Como a Agathas Web resolve isso

Os usernames do WhatsApp são uma mudança de integração, não de aparência. É por isso que o caminho mais seguro é estar numa plataforma que roda direto na API oficial e que tem gente técnica por trás.

O Voyia é a plataforma de atendimento e vendas que a Agathas Web opera sobre a WhatsApp Business Cloud API da Meta. O que está incluso, conforme a página do produto:

• API oficial, sem QR Code e sem gambiarra de WhatsApp Web, com templates, botões e mensagens interativas.
• Inbox multi-atendente em tempo real, com transferência e filas (a partir do plano Profissional), e app iOS e Android.
• Chatbot no-code e integração com IA usando a sua própria chave (Claude, GPT, Gemini, DeepSeek), com transferência para humano.
• Disparos segmentados com templates aprovados e relatórios de entrega, leitura e tempo de resposta.
• Tarifas da Meta repassadas sem markup, faturamento em BRL com nota fiscal, servidores no Brasil e tokens da Meta criptografados em AES-256.
• Migração do número do app WhatsApp Business ou de outra plataforma, com apoio na verificação junto à Meta.

Os planos são Starter (R$ 149/mês), Profissional (R$ 349/mês) e Business (R$ 749/mês), cada um com 1 número, sem fidelidade; Starter e Profissional têm taxa de instalação e configuração, que deve ser consultada com a equipe de vendas antes de contratar.

Como funciona na prática: você agenda uma demonstração de até 30 minutos, contrata o plano, conectamos o seu número à API oficial e você configura equipes, templates e fluxos com os tutoriais do painel. Se a sua operação depende de CRM, ERP ou Moodle que hoje usam o telefone como chave, a configuração personalizada e a adaptação dessas integrações são feitas pela nossa equipe sob orçamento, com escopo definido antes.

Uma recomendação honesta sobre os usernames do WhatsApp, que vale para qualquer fornecedor, inclusive nós: na demonstração, peça para ver como um contato que chega só com BSUID aparece no inbox e no seu CRM. Se ninguém souber responder, você já sabe onde está o risco. Você pode conhecer os planos do Voyia e falar com a equipe pela própria página.

Conclusão: trate o telefone como atributo, não como identidade

Os usernames do WhatsApp ainda não têm data de lançamento para o público, mas tudo que eles exigem da sua integração já está publicado: BSUID em todo webhook desde abril, envio por BSUID desde julho, botão para pedir o número e obrigatoriedade para quem usa a API oficial ou anuncia com Click-to-WhatsApp.

O plano é curto: mapeie onde o telefone é lido, adicione o BSUID como chave, pare de descartar eventos sem wa_id, grave o vínculo entre os dois enquanto ainda pode e desenhe o pedido do número para os casos em que ele é indispensável. Se você está começando na API oficial ou quer revisar a integração atual, veja também como automatizar o atendimento no WhatsApp com IA sem ser banido e como operar o WhatsApp Business em dois celulares do jeito oficial.

Quando quiser colocar isso para rodar sem montar a infraestrutura do zero, fale com a Agathas Web sobre o Voyia.

Fontes oficiais consultadas em 05/10/2026: BSUID e usernames, preços da plataforma, changelog, evolução do modelo de contas e Política de Mensagens do WhatsApp Business.