Entendendo os nomes de usuário e os BSUIDs do WhatsApp
O que são nomes de usuário do WhatsApp?
Um nome de usuário do WhatsApp é um identificador opcional e exclusivo que pode ser definido por qualquer um dos seguintes usuários para ser exibido no lugar do número de telefone no aplicativo: um usuário do WhatsApp (conectado ao aplicativo WhatsApp para consumidores) ou uma empresa (conectada ao aplicativo WhatsApp Business ou à Plataforma de API do WhatsApp Business). Os nomes de usuário funcionam de maneira semelhante aos nomes de usuário no Facebook Messenger ou no Instagram.
Existem dois atores e casos de uso distintos:
| Ator | Por que eles escolhem um nome de usuário | Efeito sobre a visibilidade do número de telefone |
|---|---|---|
| Usuário do WhatsApp (conectado ao aplicativo do WhatsApp para consumidores) | Privacidade: para evitar compartilhar seu número de telefone com empresas ou outros usuários | O número de telefone fica oculto para empresas nos webhooks (a menos que determinadas condições sejam atendidas) |
| Empresas (conectadas ao aplicativo WhatsApp Business ou à Plataforma de API do WhatsApp Business) | Identidade visual: para facilitar que os usuários os encontrem e reconheçam | O número de telefone não está oculto; o nome de usuário é apenas um identificador adicional |
Os nomes de usuário são um recurso adicional aos números de telefone, não um substituto. Todas as contas do WhatsApp ainda exigem um número de telefone.
O que é um BSUID?
Um ID de usuário no âmbito empresarial (BSUID) é um identificador exclusivo atribuído pela Meta a cada usuário do WhatsApp, vinculado especificamente a um determinado portfólio de empresas. É a principal forma de identificar e enviar mensagens a um usuário quando seu número de telefone não está disponível.
Principais características de um BSUID:
- Formato: prefixo do código de país ISO 3166 alfa-2, seguido por um ponto e até 128 caracteres alfanuméricos — por exemplo, US.13491208655302741918
- Âmbito: Único para cada par de portfólio de negócios e usuário. Um BSUID de um portfólio não pode ser usado com um número de telefone pertencente a um portfólio diferente.
- Disponibilidade: Sempre presente para usuários do WhatsApp (consumidores). Nem sempre disponível para empresas, a menos que seja adotado. Além disso, independentemente do nome de usuário ou do BSUID, os números de telefone das empresas estão sempre disponíveis.
- Regeneração: Um BSUID é regenerado caso o usuário altere seu número de telefone.
- Limitações: Os BSUIDs não podem ser usados para enviar modelos de autenticação do tipo “one-tap”, “zero-tap” ou “copiar código”. Esses tipos de mensagem exigem um número de telefone.
O que é um BSUID de pai ou mãe?
Um BSUID pai é uma variante especial do BSUID disponível para empresas gerenciadas que possuem vários portfólios de negócios Meta vinculados. Ele permite que um único identificador seja utilizado em todos os portfólios cadastrados.
- Formato:
{COUNTRY_CODE}.ENT.{ALPHANUMERIC_ID}— por exemplo,US.ENT.11815799212886844830 - Disponibilidade: Apenas para empresas cadastradas em um Account BSUID principal da Meta. Entre em contato com seu representante da Meta ou da Vonage para verificar se você se qualifica.
- Escopo: Funciona em todas as carteiras cadastradas. Os BSUIDs regulares continuam funcionando em conjunto com os BSUIDs principais.
Quando você receberá um BSUID em vez de um número de telefone?
A tabela abaixo resume quais identificadores são visíveis para a Vonage, dependendo do tipo de usuário:
| Tipo de usuário | O número de telefone está visível? | O BSUID está visível? | O nome de usuário fica visível? |
|---|---|---|---|
| Usuário sem nome de usuário | Sim | Sim (sempre) | Não |
| Usuário com nome de usuário “adopted” | Condicionalmente (veja abaixo) | Sim (sempre) | Sim |
| Negócio sem nome de usuário | Sim | Não | Não |
| Empresa com nome de usuário adotado | Sim | Não | Sim (apenas para fins de marca) |
Quando o número de telefone ainda é incluído para usuários que adotam um nome de usuário?
O Meta inclui o número de telefone do usuário nos webhooks se alguma das seguintes condições for atendida (avaliada por número de telefone comercial):
- Você enviou uma mensagem ou ligou para o número de telefone do usuário nos últimos 30 dias
- Você recebeu uma mensagem ou ligação do número de telefone desse usuário nos últimos 30 dias
- O usuário está na sua lista de contatos
Se nenhuma dessas condições for atendida, o wa_id O campo será omitido da carga útil do webhook. O from Esse campo conterá o BSUID em vez do número de telefone.
A Agenda de Contatos
O Meta oferece um recurso de agenda de contatos (disponível a partir do início de abril de 2026) que armazena automaticamente o número de telefone e o BSUID de um usuário sempre que você enviar ou receber uma mensagem ou ligação para ou desse número de telefone. Uma vez armazenado, o número de telefone continuará aparecendo nas cargas úteis dos webhooks, independentemente de o usuário ter adotado um nome de usuário.
A agenda de contatos está restrita ao nível do portfólio de negócios e é hospedada pela Meta. Não é necessário realizar nenhum trabalho de integração para ativá-la, pois ela já vem ativada por padrão pela Meta. Você pode desativá-la a qualquer momento em Meta Business Suite > Configurações da empresa > Informações da empresa.
Novo código de erro
Um novo código de erro é retornado quando você tenta enviar um tipo de mensagem que não suporta BSUIDs como destinatários:
| Código de erro | Detalhes |
|---|---|
| 131062 | Destinatários com ID de usuário no âmbito empresarial (BSUID) não são suportados para esta mensagem. |