Usernames do WhatsApp e BSUID: o que muda para quem usa a API

Atualizado em 28/10/2026

Usernames são nomes únicos e opcionais que usuários e empresas podem adotar no WhatsApp; quando um cliente ativa o dele, o número de telefone pode deixar de chegar nos webhooks da API. Para que as integrações continuem identificando quem escreveu, a Meta criou o BSUID (business-scoped user ID), um identificador do usuário válido só dentro do seu portfólio empresarial. Desde abril de 2026 ele aparece nos webhooks, e desde julho de 2026 a API aceita enviar mensagens para ele.

O que são usernames no WhatsApp

Segundo a documentação de BSUID da Meta, o username é um nome que o usuário pode definir para aparecer no app no lugar do número de telefone. Cada pessoa tem no máximo um, pode trocá-lo de tempos em tempos, e a troca não altera nem o número nem o BSUID. Adotar um username é opcional, tanto para pessoas quanto para empresas.

Do lado da empresa existe o username comercial. Ele não esconde o número da empresa (a Meta deixa claro que usernames comerciais não são um recurso de privacidade) e cada username aponta para um único número comercial. As regras de formato são:

• só letras do alfabeto inglês, dígitos, ponto e sublinhado;
• de 3 a 35 caracteres, com pelo menos uma letra;
• não pode começar nem terminar com ponto, nem ter dois pontos seguidos;
• não pode começar com www. nem terminar com sufixo de domínio, como .com;
• maiúsculas e minúsculas são iguais, mas ponto e sublinhado contam: minhaloja, minha.loja e minha_loja são nomes diferentes.

Desde 29 de junho de 2026 as empresas podem reservar e adotar o username pelo Meta Business Suite, pelo Gerenciador do WhatsApp, pelo app WhatsApp Business ou pela API. Na atualização de 23 de outubro de 2026, a Meta incluiu um limite: cada número comercial pode trocar de username até 2 vezes em 14 dias corridos (10 vezes para usernames reservados). Passou disso, a API devolve o erro 130429.

O que é o BSUID

O BSUID identifica um usuário do WhatsApp para uma empresa específica. Pela documentação, ele é:

• gerado automaticamente, tenha o usuário um username ou não;
• formado pelo código de país ISO 3166 alfa-2, um ponto e até 128 caracteres alfanuméricos, por exemplo US.13491208655302741918;
• único por par usuário + portfólio empresarial (o antigo Business Manager);
• regenerado quando o usuário troca de número de telefone.

O escopo é o ponto que mais pega: um BSUID só funciona com números do mesmo portfólio. Num SaaS, o BSUID que chegou no número do cliente A não serve para enviar pelo número do cliente B.

Empresas com vários portfólios podem pedir à Meta o BSUID principal (parent BSUID), que vale em todos os portfólios inscritos. Ele tem ENT depois do código do país (US.ENT.11815799212886844830) e chega no campo parent_user_id. A inscrição depende de elegibilidade avaliada pelo contato da Meta.

A Meta afirma que o suporte a BSUID é obrigatório para parceiros, empresas com integração direta e anunciantes de anúncios de clique para o WhatsApp, porque ninguém controla quando um cliente vai ativar o username.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Campos novos nos webhooks

O BSUID aparece em todo webhook que normalmente traria o telefone. A tabela resume os campos documentados:

Webhook	Campo	O que traz
Mensagem recebida	contacts[].user_id	BSUID do usuário
Mensagem recebida	contacts[].profile.username	Username, só se o usuário tiver um
Mensagem recebida	messages[].from	Telefone (pode ser omitido)
Mensagem recebida	messages[].from_user_id	BSUID
Status	statuses[].recipient_id	Telefone (pode ser omitido)
Status	statuses[].recipient_user_id	BSUID, sempre incluído (exceto em failed enviado por telefone)
Qualquer um, se habilitado	parent_user_id, from_parent_user_id, recipient_parent_user_id	BSUID principal

Um webhook de mensagem recebida de quem ativou o username e com quem você não falou nos últimos 30 dias pode chegar assim, sem telefone:

{
  "contacts": [
    {
      "profile": { "name": "Pablo M.", "username": "pablomorales" },
      "user_id": "BR.13491208655302741918"
    }
  ],
  "messages": [
    {
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgL...",
      "timestamp": "1761650000",
      "type": "text",
      "text": { "body": "Oi, meu pedido chegou?" }
    }
  ]
}

Webhooks de user_preferences, grupos e chamadas também ganharam os campos. E o novo business_username_updates avisa quando o status do username da empresa muda (context: "revoked" quando a Meta revoga o nome).

Quando o telefone ainda vem no webhook

Mesmo com o username ativo, o número do usuário continua no payload se pelo menos uma condição for verdadeira:

1. você enviou mensagem ou ligou para aquele número nos últimos 30 dias;
2. você recebeu mensagem ou ligação daquele número nos últimos 30 dias;
3. o usuário está no seu contact book.

As duas primeiras condições são avaliadas por número comercial, não por portfólio. Se o cliente fala com o número de vendas, o webhook do número de suporte pode chegar sem telefone.

Troca de número e troca de BSUID

Quando o usuário troca de número, o BSUID é regenerado e você recebe uma mensagem de sistema no campo messages com system.type igual a user_changed_number, trazendo user_id, previous_user_id e wa_id quando pode compartilhar o número. Se o número não puder ser compartilhado, o tipo é user_changed_user_id e só os identificadores mudam. Basta assinar messages (user_id_update não é um campo assinável). Detalhes do formato geral dos eventos estão em webhooks da API do WhatsApp e em status de mensagem via webhook.

Como enviar mensagem por BSUID

Desde julho de 2026, o POST /<PHONE_NUMBER_ID>/messages aceita o campo recipient com o BSUID no lugar de to:

curl -X POST 'https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>/messages' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "BR.13491208655302741918",
    "type": "text",
    "text": { "body": "Seu pedido saiu para entrega." }
  }'

Regras que valem a pena gravar:

• Use o valor inteiro. Código do país, ponto e todos os caracteres. Qualquer alteração faz a requisição falhar.
• to ganha de recipient. Se você mandar os dois, a Meta usa o telefone.
• Exceção: autenticação. Templates de autenticação one-tap, zero-tap e copy code exigem o telefone. Mandá-los para um BSUID retorna o erro 131062.
• Escopo do portfólio. BSUID de outro portfólio não funciona.

Na Marketing Messages API o envio por BSUID também existe desde 5 de maio de 2026, mas a Meta avisa que a otimização de entrega não roda nesses envios e recomenda usar o telefone quando você tiver.

Pedir o telefone ao cliente

Se o contato só tem BSUID e você precisa do número (para nota fiscal, cobrança ou OTP), a Meta criou o botão REQUEST_CONTACT_INFO. Ele pode entrar em templates de utilidade e marketing ou ser enviado como mensagem interativa. Quando o usuário toca, o número é compartilhado na conversa e chega um webhook de contatos com origin: "contact_request". O texto do botão não é personalizável.

Contact book: a agenda que a Meta guarda para você

O contact book é hospedado pela Meta e não exige integração. Depois que o recurso é lançado, toda interação (mensagem ou ligação, enviada ou recebida) entre um número do portfólio e um usuário grava o telefone e o BSUID dele. A partir daí, os webhooks daquele usuário trazem o telefone mesmo que ele ative o username.

Pontos de atenção:

• não é retroativo: conversas anteriores ao lançamento não entram;
• o escopo é o portfólio empresarial;
• os dados ficam até você desativar o recurso (em Meta Business Suite > Configurações da empresa > Informações da empresa) ou a conta; desativar apaga tudo, e reativar não restaura;
• pela API, GET /<PHONE_NUMBER_ID>/contact_book diz se existe telefone guardado para um BSUID (campo present), sem nunca devolver o número, e um DELETE remove a entrada.

Impacto no CRM que usa telefone como chave

A maioria das integrações usa wa_id ou from como chave primária do contato. Com usernames, mensagens podem chegar sem telefone e o BSUID muda quando o cliente troca de número.

Um modelo que resiste a isso:

1. Crie uma tabela de identidades, não uma coluna. Cada contato pode ter telefone, BSUID por portfólio e BSUID principal.
2. Procure por BSUID primeiro, depois por telefone. Se achar pelos dois e forem contatos diferentes, faça merge.
3. Grave o par telefone + BSUID sempre que vierem juntos. É assim que você reconhece o cliente quando ele aparecer só com BSUID.
4. Trate user_changed_number e user_changed_user_id atualizando o BSUID a partir de previous_user_id.
5. Responda pelo mesmo número comercial quando possível, por causa da regra dos 30 dias por número.
6. Teste antes de ver em produção. O Painel de Apps tem um botão Test no webhook de mensagens com cenários de usuário com e sem username.

async function resolverContato(value) {
  const c = value.contacts?.[0] ?? {};
  const msg = value.messages?.[0] ?? {};
  const bsuid = c.user_id ?? msg.from_user_id;
  const telefone = msg.from ?? c.wa_id; // pode vir vazio

  let contato = bsuid ? await db.contatoPorBsuid(bsuid) : null;
  if (!contato && telefone) contato = await db.contatoPorTelefone(telefone);
  if (!contato) contato = await db.criarContato();

  await db.vincular(contato.id, { bsuid, telefone, username: c.profile?.username });
  return contato;
}

Se o seu fluxo depende de anúncios, o mesmo cuidado vale para atribuição: veja como rastrear anúncios Click-to-WhatsApp. E mudanças paralelas na conta, como a nova estrutura da WABA, também afetam IDs que seu CRM guarda.

Cronograma confirmado na documentação da Meta

Data	O que aconteceu
Início de abril de 2026	BSUIDs começam a aparecer nos webhooks
5 de maio de 2026	/marketing_messages aceita envio por BSUID
29 de junho de 2026	Empresas podem reservar e adotar username comercial
Julho de 2026	Cloud API aceita envio por BSUID; botão REQUEST_CONTACT_INFO disponível
24 de agosto de 2026	Consulta ao contact book (GET .../contact_book)
23 de outubro de 2026	Limite de troca de username (2 a cada 14 dias) e erro 130429
2026	WhatsApp libera usernames aos usuários de forma gradual

A Meta não publicou data única para todos os usuários terem username; a página fala só em liberação gradual em 2026. Acompanhamos as próximas mudanças em novidades da API do WhatsApp em 2026.

Como fica na Vectalk

A Vectalk é um proxy da API oficial do WhatsApp: os webhooks que você registra com POST /api/webhooks recebem o mesmo payload que a Meta envia, então user_id, from_user_id, username e as mensagens de sistema chegam sem tradução. O que precisa mudar está no seu código, no modelo de contato descrito acima. A referência dos eventos está na documentação de webhooks, e o cadastro é feito em apps.vectalk.com.br/register.

Perguntas frequentes

O cliente que ativar username vai sumir do meu CRM?

Não, se a integração já lê o BSUID. O BSUID chega em todo webhook, com ou sem username. O que pode faltar é o telefone, quando não houve conversa nos últimos 30 dias naquele número e o cliente não está no contact book.

Posso enviar template de marketing para um BSUID?

Sim. O envio por BSUID aceita qualquer tipo de mensagem, menos templates de autenticação one-tap, zero-tap e copy code. Na Marketing Messages API, envios por BSUID não recebem otimização de entrega.

O BSUID muda?

Muda quando o usuário troca de número de telefone. Trocar de username não altera o BSUID. A mudança chega como mensagem de sistema no webhook messages.

Ter username esconde o número da minha empresa?

Não. A Meta diz que o username comercial não oculta o número da empresa e não foi pensado como recurso de privacidade.

Um BSUID serve para todos os meus clientes de SaaS?

Não. Ele é restrito ao portfólio empresarial em que foi gerado. Cada cliente terá BSUIDs próprios para os mesmos usuários.

---

Fontes oficiais consultadas em 28/10/2026: Business-scoped user IDs (atualizada em 23/10/2026), Changelog da plataforma do WhatsApp, Enviar mensagens de marketing (Marketing Messages API).