Neste artigo, você encontrará uma explicação detalhada sobre a transição do WhatsApp para os nomes de usuário e o identificador BSUID, incluindo a quem essa mudança impacta, as atualizações técnicas na plataforma Botmaker e um guia de perguntas frequentes para que sua empresa adapte seus processos e sistemas antes de junho de 2026.
A partir de junho de 2026, a WhatsApp Business Platform introduzirá mudanças significativas na forma como as empresas identificam e se comunicam com seus usuários. Essa evolução busca priorizar a privacidade, permitindo que as pessoas interajam com negócios sem precisar compartilhar seu número de telefone.
Você pode:
Pré-requisitos
Ter ao menos um canal da WhatsApp Business Platform conectado à Botmaker. Acesso à sua conta da Botmaker com permissões para administrar bots, contatos e integrações.
Conceitos-chave
BSUID (Business Scoped User ID): identificador único e anônimo gerado pela Meta para cada combinação específica de usuário e empresa. É uma cadeia alfanumérica de até 128 caracteres.
Username: nome de usuário público que cada pessoa pode ativar no WhatsApp como alternativa a compartilhar seu número de telefone.
ChatID: identificador único de cada chat na Botmaker, independente do canal ou da identidade do usuário.
Contact ID / platformContactId: identificador do usuário no canal dentro da Botmaker. Pode conter o número de telefone ou o BSUID conforme o caso.
WhatsApp Phone: variável que armazena o número de telefone apenas quando o usuário o compartilha explicitamente. Agenda de Contatos (Contact Book): funcionalidade do Meta Business Suite que permite manter visíveis os números dos clientes atuais quando ativarem seu username.
O Business Scoped User ID (BSUID) é um identificador único e anônimo gerado pela Meta para cada combinação específica de usuário e empresa.
Não existe uma data de “desligamento” global do número de telefone. O número deixa de estar disponível na plataforma de forma individual, quando cada usuário ativa seu username (feature opt-in).
Nota: Quando um usuário ativa seu username, o número de telefone deixa de estar disponível para a empresa, exceto se tiver havido interação nos últimos 30 dias, se estiver na agenda de contatos da empresa, ou em outras exceções definidas pela Meta.
Documentação oficial da Meta: Business Scoped User IDs
A Botmaker está se adaptando para que essa transição seja fluida:
O identificador único do usuário na Botmaker passará a ser independente do meio: você poderá conversar, buscar chats ou enviar templates indistintamente por número de telefone ou por BSUID, e a plataforma resolverá o resto.
A Botmaker disponibiliza o BSUID e o número de telefone dentro da plataforma por meio das variáveis do bot, e também permite consumi-los a partir de sistemas externos via API ou webhooks.
A partir da mudança, a Botmaker passa a manejar três variáveis-chave que vale a pena conhecer em detalhe. Cada uma cumpre um papel diferente:
Nota: A partir do rollout, o platformContactId pode deixar de ser um número de telefone e passar a conter um BSUID. Qualquer lógica do bot, validação ou integração que assume formato numérico precisará ser ajustada para suportar cadeias alfanuméricas de até 128 caracteres.
A Botmaker está incorporando um novo endpoint /contacts que permite baixar a informação dos contatos, incluindo o BSUID associado.
O endpoint:
Além do novo endpoint, os endpoints existentes já permitem referenciar um usuário por número de telefone ou por BSUID de forma intercambiável. Isso se aplica ao envio de templates, busca de chats e outras operações.
Os webhooks da Botmaker já estão enviando o BSUID no seu payload. Quando um usuário interage pelo WhatsApp e a Botmaker dispõe do BSUID, este é enviado automaticamente através do campo correspondente, sem exigir mudanças na configuração existente dos seus webhooks.
Para que sua integração funcione antes e depois do rollout sem exigir ajustes urgentes:
É importante identificar quais processos serão modificados e quais permanecerão iguais:
São afetados:
Não são afetados:
Será mantida a capacidade de enviar templates de notificação utilizando os números de telefone tradicionais, já que o sistema permitirá referenciar as conversas do WhatsApp por meio do ChatID, do número de telefone ou do novo BSUID.
Para os contatos que já contam com um número registrado por interações anteriores, a Botmaker conservará ambos os dados para garantir a continuidade do serviço.
Como serão enviadas as notificações?
As empresas poderão se referir às conversas do WhatsApp e enviar notificações utilizando três tipos de identificadores: ChatID, número de telefone ou BSUID. A plataforma permitirá carregar qualquer um desses dados para iniciar ou manter a comunicação.
O que acontece se um usuário não quiser compartilhar seu número de telefone? Como enviar templates para ele?
Se o usuário optar por ocultar seu número, a empresa receberá seu BSUID. Você poderá continuar enviando campanhas de envio ou mensagens via API utilizando esse identificador no lugar do número de telefone. Se por razões operacionais (como um envio físico ou validação legal) você precisar do número, poderá solicitá-lo ao usuário por meio de um template de utilidade ou marketing projetado para capturar esse dado.
Será possível continuar enviando templates para usuários com número de telefone?
Sim. Se você já tem o número do WhatsApp registrado por interações anteriores, a Botmaker conservará ambos os dados (telefone e BSUID). Além disso, para os contatos existentes, o número de telefone continuará sendo visível e utilizável se o usuário já estiver na sua “Agenda de Contatos” da Meta.
Como os templates continuarão sendo enviados?
O processo técnico se mantém similar, mas com maior flexibilidade no identificador. As campanhas de marketing e mensagens de utilidade poderão ser disparadas usando o BSUID. Cabe destacar que os templates de autenticação (OTP) não sofrerão mudanças no seu funcionamento básico. Estes poderão ser enviados apenas por número de telefone e não por BSUID.
Qual é a variável exata dentro da Botmaker que trará o BSUID em conversas do WhatsApp?
A variável é ${bsuid}. Já está disponível na plataforma e você pode utilizá-la nos fluxos do bot.
Existe uma variável que contenha o número de telefone quando o usuário o compartilha?
Sim. A variável WhatsApp Phone é preenchida com o número de telefone apenas quando o usuário o compartilha explicitamente (por exemplo, mediante um fluxo que solicita o contato). Se o usuário nunca compartilhou seu número, essa variável permanecerá vazia. É a forma recomendada de capturar e armazenar telefones a partir do rollout.
Existe um endpoint de API para baixar contatos com seu BSUID?
Sim. A Botmaker está incorporando o endpoint /contacts, que permite baixar todos os contatos da conta junto com seu BSUID e, quando aplicável, seu número de telefone. A documentação é publicada automaticamente junto com o restante da API.
O BSUID substituirá o valor atual de platformContactId, customerId ou outra variável?
Sim, eventualmente. O platformContactId ou “ID do usuário no canal” pode começar a conter um BSUID no lugar de um número de telefone a partir do rollout — recomenda-se não assumir formato numérico na lógica do bot. A variável ${bsuid} sempre contém o BSUID, e WhatsApp Phone sempre contém o número (quando disponível).
O CHAT_CHANNEL_ID continuará representando apenas o canal/chat ou também poderia mudar com essa atualização?
Não muda. O CHAT_CHANNEL_ID representa a linha do cliente (o business), não a do usuário. Não é afetado pela introdução do BSUID.
Existe algum exemplo real de payload, code action ou variáveis de plataforma onde o BSUID já seja visível?
Sim, já está disponível na plataforma e pode ser testado hoje mesmo através da variável ${bsuid}. A incorporação dentro das code actions está sendo liberada em breve.
Em conversas iniciadas pelo usuário, devemos assumir que em alguns casos não receberemos mais o número de telefone e somente chegará o BSUID?
Correto. A partir do rollout progressivo, sempre que um usuário ativar seu username, o número de telefone deixará de estar disponível na plataforma e somente será exposto o BSUID. Não existe uma data global única — depende da adoção individual de cada usuário.
Para contatos históricos, a Botmaker continuará expondo ambos os dados (telefone e BSUID) em variáveis utilizáveis dentro do bot?
Sim. Para contatos com interações anteriores, a Botmaker manterá tanto o telefone quanto o BSUID acessíveis, e ambos poderão ser utilizados para enviar notificações.
Existe documentação técnica adicional, changelog, manual ou FAQ ampliado além deste artigo?
No momento não há documentação técnica adicional publicada. A equipe da Botmaker está preparando material complementar que será compartilhado conforme o rollout avance. A fonte oficial de referência é a documentação da Meta sobre Business Scoped User IDs.
Existe alguma forma de validar esse comportamento em um ambiente de teste ou desenvolvimento antes do rollout geral?
A implantação é geral, não é oferecido um ambiente de testes separado. A validação é realizada diretamente na plataforma utilizando a variável ${bsuid}, que já está disponível.
Haverá mudanças necessárias em ações como trigger intent, change bot, master bot ou autenticações por links externos?
Não são necessárias mudanças nessas ações. A única coisa a considerar é que o platformContactId ou o “ID do usuário no canal” pode deixar de ser um número de telefone — qualquer validação ou lógica que assuma formato numérico deverá ser ajustada.
Para evitar interrupções, recomendamos seguir estes passos:
Lembre-se de visitar nossa Central de Ajuda para obter mais informações.