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 2026, a WhatsApp Business Platform introduz 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. A reserva de usernames abre em 29 de junho de 2026 em nível global, e a ativação é habilitada por ondas (waves) de acordo com o país.
Você pode:
Ter ao menos um canal de WhatsApp Business Platform conectado ao Botmaker. Acesso à sua conta Botmaker com permissões para administrar bots, contatos e integrações.
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 no Botmaker, independente do canal ou da identidade do usuário.
Contact ID / platformContactId: identificador do usuário no canal dentro do Botmaker. Pode conter o número de telefone ou o BSUID, conforme o caso.
${whatsappNumber}: variável que armazena o número de telefone apenas quando o usuário o compartilha explicitamente.
Lista de Contatos (Contact Book): recurso do Meta Business Suite que permite manter visíveis os números dos clientes atuais depois que eles 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.
A mudança é implementada em dois planos. Por um lado, a infraestrutura do BSUID e a API; por outro, a reserva e ativação dos usernames dos usuários finais, que é habilitada por ondas de acordo com o país.
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 (recurso opt-in).
A reserva de usernames abre em 29 de junho de 2026 em nível global. A partir dessa data, todas as empresas do mundo podem reservar seu username preferido; reservar cedo protege o nome da sua marca antes da ativação.
A ativação (quando o username passa a ser utilizável) é habilitada por ondas:
Onda | Data | Países |
Wave 1 | 7 de julho de 2026 | Argélia, Azerbaijão, Gana, Líbia, Nepal |
Wave 2 | 20 de julho de 2026 | Colômbia, Singapura, Peru, Malásia, República Dominicana |
Disponibilidade global | Fim de agosto de 2026 | Demais países |
As empresas podem reservar ou reivindicar seus usernames através do WhatsApp Manager, do Meta Business Suite ou da Username API.
Passo a passo: se você quer ver como reservar e registrar seu username passo a passo, dentro do Botmaker ou no Business Manager da Meta, compartilhamos o artigo “Como registrar seu username do WhatsApp no Botmaker”.
Importante para clientes integrados por API: além de reservar o username, você deve garantir que seus sistemas suportem os Business-Scoped User IDs (BSUID) junto com os números de telefone. A documentação técnica está em Business Scoped User IDs (Meta).
O que comunicar aos seus clientes: a reserva de usernames abre no fim de junho de 2026 e a usabilidade real depende da onda de rollout do país de cada um. Reservar cedo protege o nome preferido.
Nota: quando um usuário ativa seu username, seu número de telefone deixa de estar disponível para a empresa, exceto se houve interação nos últimos 30 dias, se ele estiver na lista de contatos da empresa, ou em outras exceções definidas pela Meta.
O Botmaker está se adaptando para que essa transição seja fluida:
O identificador único do usuário no 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 resolve o resto.
O Botmaker disponibiliza o BSUID e o número de telefone dentro da plataforma através da variável do bot ${bsuid}, e também permite consumi-los a partir de sistemas externos por API ou webhooks.
Na medida em que o BSUID estiver disponível, você poderá encontrar os dados em quatro lugares:
A partir da mudança, o Botmaker trabalha com três variáveis-chave que vale a pena conhecer em detalhe. Cada uma cumpre um papel distinto:
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 assuma formato numérico deverá ser ajustada para suportar cadeias alfanuméricas de até 128 caracteres.
O BSUID e o número de telefone já estão disponíveis dentro das ações de código. Você pode acessá-los diretamente a partir do contexto do usuário:
Isso permite consumir ambos os identificadores dentro da sua lógica de negócio sem exigir configuração adicional.
O Botmaker incorporou o endpoint /contacts, que permite baixar a informação dos contatos, incluindo o BSUID associado. A API de Contatos já está disponível.
Além do endpoint /contacts, 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 do Botmaker já estão enviando o BSUID no seu payload, junto com o número de telefone quando disponível. Quando um usuário interage pelo WhatsApp e o Botmaker dispõe do BSUID, ele é 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 usando os números de telefone tradicionais, já que o sistema permitirá referenciar as conversas do WhatsApp pelo ChatID, pelo número de telefone ou pelo novo BSUID.
Para os contatos que já contam com um número registrado por interações anteriores, o Botmaker manterá ambos os dados para garantir a continuidade do serviço.
Para evitar interrupções, recomendamos seguir estes passos:
Adote também as novas variáveis e fontes de dados na plataforma: use bsuid**,ContactIDe**{whatsappNumber} conforme apropriado em cada fluxo do bot, consuma context.userData.bsuid e context.userData.whatsappNumber a partir das suas ações de código, e aproveite o endpoint /contacts da API quando precisar consumir os dados a partir de sistemas externos.
Quando posso reservar o username da minha empresa?
A reserva abre em 29 de junho de 2026 em nível global: qualquer empresa do mundo pode reservar seu username preferido a partir dessa data. Reservar cedo protege o nome da sua marca antes da ativação.
De onde se reserva ou reivindica um username?
De três lugares: WhatsApp Manager, Meta Business Suite ou a Username API.
Quando o username fica utilizável no meu país?
A ativação é por ondas. Wave 1 (7 de julho): Argélia, Azerbaijão, Gana, Líbia e Nepal. Wave 2 (20 de julho): Colômbia, Singapura, Peru, Malásia e República Dominicana. Disponibilidade global: fim de agosto de 2026. Reservar o username não depende da onda; a usabilidade sim.
Sou um cliente integrado por API, o que devo levar em conta?
Além de reservar o username, garanta que seus sistemas suportem os Business-Scoped User IDs (BSUID) junto com os números de telefone. Os detalhes técnicos estão na documentação da Meta.
Onde posso encontrar o BSUID e o número de telefone dentro do Botmaker?
Em quatro lugares, na medida em que o BSUID estiver disponível: na tela de contatos; nos webhooks; nas ações de código (context.userData.bsuid e context.userData.whatsappNumber); e por API, baixando os contatos através do endpoint /contacts.
Como as notificações serão enviadas?
As empresas poderão se referir às conversas do WhatsApp e enviar notificações usando três tipos de identificadores: ChatID, número de telefone ou BSUID.
O que acontece se um usuário não quiser compartilhar seu número de telefone? Como enviar templates?
Se o usuário optar por ocultar o número, a empresa receberá seu BSUID. Você pode continuar enviando campanhas de saída ou mensagens via API usando esse identificador. Se por razões operacionais precisar do número, pode solicitá-lo por meio de um template de utilidade ou de marketing.
Será possível continuar enviando templates para usuários com número de telefone?
Sim. Se você já tem o número de WhatsApp registrado por interações anteriores, o Botmaker manterá ambos os dados (telefone e BSUID). Além disso, para os contatos existentes, o número continuará visível e utilizável se o usuário já estiver na sua lista de contatos da Meta.
Como os templates continuarão a ser 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. Os templates de autenticação (OTP) não sofrerão mudanças e poderão ser enviados apenas por número de telefone, não por BSUID.
Qual é a variável exata dentro do Botmaker que trará o BSUID em conversas do WhatsApp?
A variável é ${bsuid}. Já está disponível na plataforma. Dentro das ações de código, o mesmo dado está disponível em context.userData.bsuid.
Existe uma variável que contenha o número de telefone quando o usuário o compartilha?
Sim. A variável ${whatsappNumber} é preenchida com o número apenas quando o usuário o compartilha explicitamente. Se nunca compartilhou, permanecerá vazia. Nas ações de código está em context.userData.whatsappNumber.
Existe um endpoint de API para baixar contatos com seu BSUID?
Sim. O Botmaker incorporou o endpoint /contacts, que permite baixar todos os contatos junto com seu BSUID e, quando aplicável, seu número de telefone. Já está disponível.
O BSUID substituirá o valor atual de platformContactId, customerId ou outra variável?
Sim, eventualmente. O platformContactId pode começar a conter um BSUID em vez de um número a partir do rollout; não assuma formato numérico na lógica do bot. A variável bsuid**semprecontémoBSUID,e**{whatsappNumber} sempre o número (quando disponível).
O CHAT_CHANNEL_ID continuará representando apenas o canal/chat?
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.
Em conversas iniciadas pelo usuário, devemos assumir que em alguns casos já não receberemos o número de telefone?
Correto. A partir do rollout progressivo, cada vez que um usuário ativar seu username, o número de telefone deixará de estar disponível e só o BSUID será exposto. Não há uma data global única: depende da adoção individual e da onda de cada país.
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 pode deixar de ser um número de telefone; qualquer validação que assuma formato numérico deveria ser ajustada.
Para registrar seu username passo a passo, compartilhamos o artigo “Como registrar seu username do WhatsApp no Botmaker”.
Lembre-se de visitar nossa Central de Ajuda para obter mais informações.