Nomes de utilizador do WhatsApp e BSUID: o que muda para OTP, CRM e webhooks

Um ID de utilizador com âmbito empresarial (BSUID) é o identificador que a Meta coloca agora em cada webhook WhatsApp para que uma empresa possa enviar mensagens a um utilizador sem saber o seu número de telefone. Ele existe porque a WhatsApp está a introduzir nomes de utilizador: uma vez que um utilizador ativa um, uma empresa que não esteve em contacto recentemente pode não receber mais o número. Este guia da equipa de engenharia da BroadNet explica o formato, o cronograma, o que ainda requer um número de telefone e como migrar webhooks, registos de CRM e fluxos OTP.

Principais conclusões

• Os BSUIDs apareceram nos webhooks do WhatsApp desde o início de abril de 2026, para cada utilizador, independentemente de usarem ou não um nome de utilizador.
• Um BSUID se parece com US.13491208655302741918: um código de país alpha-2 ISO 3166, um ponto e, em seguida, até 128 caracteres alfanuméricos.
• Ele é exclusivo para cada par de portfólio empresarial e utilizador, e é regenerado se o utilizador alterar o seu número de telefone.
• Desde julho de 2026, você pode enviar mensagens para um BSUID, exceto modelos de autenticação de um toque, zero toque e cópia de código, que ainda precisam do número de telefone.
• A Meta diz que os parceiros e as empresas integradas diretamente devem suportar BSUIDs para evitar a perda da capacidade de processar mensagens de utilizadores com nome de utilizador.
• Mantenha o número de telefone E.164 verificado como a âncora de identidade para OTP, fallback SMS e verificações de fraude. Trate o BSUID como uma chave de canal WhatsApp.

O que é um ID de utilizador com âmbito empresarial?

A Meta define um BSUID como "um identificador de utilizador exclusivo que pode ser usado para enviar mensagens a um utilizador WhatsApp quando você não sabe o seu número de telefone" (Meta, IDs de utilizador com âmbito empresarial). O formato é o país do utilizador como um código alpha-2 ISO 3166, um ponto e até 128 caracteres alfanuméricos, por exemplo US.13491208655302741918.

Três propriedades são importantes para o design do sistema:

• Âmbito. Um BSUID é exclusivo para um portfólio empresarial e um utilizador. A mesma pessoa tem um BSUID diferente para cada portfólio empresarial com o qual fala, portanto, você não pode usá-lo para corresponder clientes entre portfólios não relacionados.
• Estabilidade. É regenerado quando o utilizador altera o seu número de telefone. Meta envia um webhook de mensagem de sistema com o tipo user_changed_user_id, e um webhook user_id_update separado, quando isso acontece.
• BSUIDs principais (parent). Empresas geridas com vários portfólios empresariais podem solicitar ao seu ponto de contacto Meta que se inscreva em BSUIDs principais (parent), que contêm ENT (por exemplo, US.ENT.11815799212886844830) e funcionam em todos os portfólios inscritos.

Porque a WhatsApp está a introduzir nomes de utilizador?

Por privacidade. A Meta anunciou em 29 de junho de 2026 que as pessoas podem reservar um nome de utilizador para usar "ainda este ano", e que quando um utilizador tiver habilitado um, uma pessoa ou empresa para a qual ele enviar uma mensagem pela primeira vez não verá mais o seu número de telefone (Sobre Meta). A documentação do desenvolvedor da Meta diz que os nomes de utilizador serão implementados gradualmente em 2026.

Empresas também podem ter nomes de utilizador. A partir de 29 de junho de 2026, uma empresa pode reivindicar um nome de utilizador que a WhatsApp reservou para ela por meio do WhatsApp Manager, Meta Business Suite ou Username API, e os nomes de utilizador aprovados tornam-se ativos quando o recurso for lançado. Um nome de utilizador de empresa não esconde o número de telefone da empresa.

Qual é o cronograma?

Você perderá o número de telefone do cliente?

Às vezes. O BSUID aparece em todos os webhooks de mensagens. O número de telefone (wa_id, e from em mensagens de entrada) é incluído apenas quando pelo menos um destes for verdadeiro, de acordo com Meta:

• você enviou mensagem ou ligou para o número de telefone do utilizador nos 30 dias antes do webhook ser acionado;
• você recebeu uma mensagem ou chamada do número de telefone do utilizador dentro desses 30 dias; ou
• o utilizador está na sua agenda de contactos.

A busca retroativa de 30 dias é avaliada por número de telefone empresarial, portanto, um cliente conhecido pela sua linha de vendas pode ser desconhecido pela sua linha de suporte. A agenda de contactos é um recurso alojado pela Meta que armazena números de telefone e BSUIDs após uma primeira interação, para que webhooks posteriores possam continuar a transportar o número mesmo depois que o utilizador adota um nome de utilizador. Ela vem ativada por predefinição e pode ser desativada em Meta Business Suite sob as configurações de Negócio, Informações do Negócio. Deixe-a ativada, a menos que você tenha um motivo para não fazê-lo.

O que ainda precisa de um número de telefone?

Meta é explícito: BSUIDs "podem ser usados para enviar qualquer tipo de mensagem, exceto modelos de autenticação de um toque, zero toque e cópia de código, que exigem números de telefone do utilizador". Fora de WhatsApp, qualquer coisa que funcione na rede móvel também precisa do número.

Como é o webhook antes e depois?

Antes dos BSUIDs, o bloco de contactos num webhook de mensagens trazia o número de telefone em wa_id, e a maioria das integrações o utilizava como a chave do cliente. O exemplo de Meta do novo objeto de contactos adiciona o nome de utilizador, o BSUID e, quando habilitado, o BSUID principal (parent); wa_id está presente apenas quando o número pode ser partilhado:

1"contacts": [
2  {
3    "profile": {
4      "name": "<USER_DISPLAY_NAME>",
5      "username": "<USERNAME>"
6    },
7    "wa_id": "<USER_PHONE_NUMBER>",
8    "user_id": "<BSUID>",
9    "parent_user_id": "<PARENT_BSUID>"
10  }
11]

Mensagens de entrada também trazem from_user_id (e from_parent_user_id se habilitado), e webhooks de status trazem recipient_user_id, que o Meta afirma ser sempre definido para o BSUID do utilizador. Para enviar, coloque o BSUID no novo parâmetro recipient. Você pode usar o parâmetro to (número de telefone), o parâmetro recipient (BSUID) ou ambos; quando ambos estão presentes, o número de telefone tem precedência:

1{
2  "messaging_product": "whatsapp",
3  "recipient_type": "individual",
4  "recipient": "<BSUID>",
5  "type": "text",
6  "text": {
7    "body": "<BODY_TEXT>"
8  }
9}

A resposta de envio então inclui user_id no seu array de contactos, e wa_id torna-se opcional. Se o seu parser assume que wa_id está sempre presente, ele falhará no primeiro utilizador com nome de utilizador. Você pode colar payloads reais em nosso inspetor de payload de webhook para verificar quais campos a sua integração realmente recebe.

O que quebra para OTP?

Modelos de autenticação com botões de um toque, zero toque ou copiar código não podem ser enviados para um BSUID. Se um utilizador com nome de utilizador entrar em contacto com você via WhatsApp e você não tiver um número de telefone para ele, você não poderá enviar a ele um WhatsApp OTP desses tipos. Isso tem duas consequências para os fluxos de verificação:

• Recolha e verifique o número de telefone no registo, no formato E.164, e armazene-o como o endereço de verificação da conta. Não dependa do webhook WhatsApp para entregá-lo a você mais tarde. Veja o que é E.164.
• Mantenha um canal que funcione no próprio número. SMS OTP, voz OTP e verificações de rede silenciosas todos funcionam no número de telefone, e é por isso que um design multicanal com fallback automático sobrevive a essa mudança sem alterações. Nosso guia de OTP multicanal e o produto BroadNet OTP cobrem o padrão.

O que quebra para o CRM e para a deduplicação de clientes?

A maioria dos CRMs indexa um contacto WhatsApp pelo número de telefone porque SMS, voz e WhatsApp costumavam partilhá-lo. Após os nomes de utilizador, um novo contacto de entrada pode chegar apenas com um BSUID. Se você criar um novo registo no CRM para ele, você duplicará clientes gradualmente. Quatro regras mantêm os dados limpos:

1. 1Modele o BSUID como uma identidade de canal, não como o ID do cliente. Um cliente pode possuir vários BSUIDs (um por portfólio empresarial) e um novo após uma mudança de número.
2. 2Mantenha uma tabela de mapeamento de BSUID, portfólio, número de telefone quando conhecido, primeira visualização e última visualização, e atualize-a em cada webhook, incluindo user_id_update.
3. 3Mescle com base em evidências, não em suposições: um número de telefone verificado, um login ou uma referência de pedido que o cliente forneça no chat.
4. 4Nunca trate a ausência de wa_id como um novo cliente. Isso apenas significa que o número não pode ser partilhado naquele evento.

Como você migra? Um checklist passo a passo

1. 1Atualize os parsers de webhook para ler user_id, from_user_id, recipient_user_id e nome de utilizador, e para tratar wa_id e from como opcionais.
2. 2Adicione uma coluna BSUID (e o BSUID principal (parent) se você for uma empresa gerida) onde quer que você armazene contactos WhatsApp.
3. 3Backfill: para cada evento de entrada desde o início de abril de 2026, vincule o BSUID ao número de telefone que você já possui.
4. 4Trate a mensagem de sistema user_changed_user_id e o webhook user_id_update relincando o novo BSUID ao cliente.
5. 5Adicione o parâmetro recipient ao seu caminho de envio e utilize-o como fallback quando não tiver um número de telefone.
6. 6Encaminhe OTP para o número de telefone, nunca para um BSUID, e mantenha SMS ou voz como o canal de fallback.
7. 7Reserve o seu nome de utilizador empresarial em WhatsApp Manager, Meta Business Suite ou através do Username API.
8. 8Teste com uma conta com nome de utilizador habilitado antes que os nomes de utilizador cheguem aos seus clientes.

Se a BroadNet for sua fornecedora de WhatsApp, solicite acesso de teste e confirme como os campos BSUID aparecem nos webhooks para a sua conta antes de alterar o código de produção. Nosso hub de desenvolvedores e a página de WhatsApp Business API contêm os detalhes, e o encaminhamento omnichannel lida com o fallback SMS do qual os fluxos de autenticação agora dependem.

Perguntas frequentes

O que é um WhatsApp BSUID?

Um ID de utilizador com âmbito empresarial: um identificador que Meta atribui a cada utilizador WhatsApp para cada portfólio empresarial, para que a empresa possa enviar mensagens ao utilizador sem saber o seu número de telefone. Ele aparece como user_id nos webhooks.

Qual é o formato de um BSUID?

Um código de país alfa-2 ISO 3166, um ponto, e então até 128 caracteres alfanuméricos, por exemplo US.13491208655302741918. Os BSUID principais para empresas geridas incluem ENT, por exemplo US.ENT.11815799212886844830.

Perderei o número de telefone do cliente quando ele adotar um nome de utilizador?

Apenas em alguns webhooks. O número ainda é incluído se você trocou uma mensagem ou chamada com esse número nos últimos 30 dias, ou se o utilizador estiver na sua agenda de contactos. Caso contrário, o wa_id é omitido e você recebe apenas o BSUID.

Posso enviar mensagens para um BSUID?

Sim, desde julho de 2026, usando o parâmetro recipient do envio de API. Todos os tipos de mensagem funcionam, exceto os modelos de autenticação de um toque, zero toque e cópia de código, que exigem o número de telefone do utilizador.

Posso enviar modelos de autenticação (OTP) para um BSUID?

Não. Modelos de autenticação de um toque, zero toque e cópia de código exigem o número de telefone. Mantenha um número de telefone verificado para cada conta e use SMS ou voz OTP como alternativa.

Os BSUID funcionam em todos os portfólios empresariais?

Não. Um BSUID é exclusivo para um par de portfólio empresarial e utilizador. Empresas geridas podem perguntar a Meta sobre BSUIDs principais (parent), que funcionam em todos os portfólios inscritos juntos.

Um BSUID chega a mudar?

Sim. Ele é regenerado quando o utilizador altera o seu número de telefone, e o Meta sinaliza isso com uma mensagem de sistema user_changed_user_id e um webhook user_id_update.

Como reservo o meu nome de utilizador empresarial?

Desde 29 de junho de 2026, por meio de WhatsApp Manager, Meta Business Suite ou o Username API. Um nome de utilizador aprovado torna-se ativo quando o recurso de nome de utilizador for lançado, e ele não oculta o seu número de telefone empresarial.

Fontes

• Meta para Desenvolvedores, IDs de utilizador com âmbito empresarial (formato, cronograma, campos de webhook, agenda de contactos, parâmetro de envio, exceção de modelo de autenticação), acedido em 26 de setembro de 2026.
• Sobre Meta, É hora de reservar o seu nome de utilizador WhatsApp, 29 de junho de 2026, acedido em 26 de setembro de 2026.