Nomes de usuário do WhatsApp e IDs de usuário com escopo comercial (BSUID)

Aviso

O Serviços de Comunicação do Azure está introduzindo mudanças urgentes, e alguns serviços estão sendo aposentados. Saiba mais no guia de desativações e alterações significativas.

O WhatsApp está lançando nomes de usuário em 2026. Os nomes de usuário são um recurso opcional que permite que os usuários do WhatsApp exibam um nome de usuário em vez de seu número de telefone. Para dar suporte a essa alteração, o Meta apresenta um novo identificador chamado BSUID (ID de usuário com escopo comercial) que identifica exclusivamente um usuário do WhatsApp em um portfólio de negócios específico.

Este artigo explica o que são BSUIDs, como eles afetam Serviços de Comunicação do Azure Mensagens Avançadas e como preparar sua integração.

O que é uma BSUID?

Uma BSUID (ID de usuário com escopo comercial) é um identificador opaco exclusivo que o Meta atribui a um usuário do WhatsApp dentro de um portfólio de negócios específico. BSUIDs são:

  • Gerado automaticamente pelo Meta para cada par de portfólio de usuários.
  • Prefixado com um código de país: o formato é {ISO 3166 alpha-2 country code}.{up to 128 alphanumeric characters}, por exemplo, US.13491208655302741918.
  • Exclusivo por portfólio de negócios: uma BSUID é associada a um portfólio de negócios individual. O mesmo usuário do WhatsApp tem um BSUID diferente para cada portfólio de negócios com o qual interage.
  • Estável entre alterações de nome de usuário: se um usuário alterar seu nome de usuário, sua BSUID permanecerá a mesma.
  • Regenerado na alteração do número de telefone: Se um usuário alterar seu número de telefone, uma nova BSUID será gerada.

Importante

Ao usar BSUIDs em solicitações de API, use todo o valor BSUID, incluindo o código do país e o período. Omitir ou modificar qualquer parte do BSUID faz com que a solicitação falhe.

Impacto nas mensagens de saída

Observação

O envio de mensagens para BSUIDs estará disponível a partir de junho de 2026, quando a Meta lançar o recurso de nome de usuário do WhatsApp para usuários finais. Até lá, o to campo só dá suporte a números de telefone.

O campo existente to na API de Notificação de Envio agora aceita um número de telefone ou um BSUID. O serviço detecta automaticamente o formato e faz o roteamento de acordo. Não são necessários novos campos.

Enviar para um número de telefone (comportamento existente):

{
  "channelRegistrationId": "<channel-registration-id>",
  "to": ["+14255550199"],
  "kind": "text",
  "content": "Hello!"
}

Enviar para um BSUID:

{
  "channelRegistrationId": "<channel-registration-id>",
  "to": ["US.13491208655302741918"],
  "kind": "text",
  "content": "Hello!"
}

Impacto nas mensagens de entrada

Quando um usuário do WhatsApp envia uma mensagem para sua empresa, o evento AdvancedMessageReceived agora inclui um novo fromBSUID campo que contém o BSUID do remetente.

Se o usuário adotou um nome de usuário e seu número de telefone não está disponível, o campo existente from pode estar vazio. Ambos os campos coexistem quando o número de telefone está disponível.

Número de telefone disponível:

"data": {
  "from": "14255551234",
  "fromBSUID": "US.13491208655302741918",
  "to": "{channel-id}",
  "content": "Hi there!",
  "channelType": "whatsapp",
  "messageType": "text"
}

Número de telefone oculto (nome de usuário adotado):

"data": {
  "from": "",
  "fromBSUID": "US.13491208655302741918",
  "to": "{channel-id}",
  "content": "Hi there!",
  "channelType": "whatsapp",
  "messageType": "text"
}

Cuidado

O from campo agora pode estar vazio ou nulo. Não suponha que esse campo sempre contenha um número de telefone.

Impacto nos assuntos do evento

O campo subject nos eventos da Grade de Eventos para AdvancedMessageReceived usa o formato advancedMessage/sender/{sender@id}/recipient/{channel-id}. Quando um usuário do WhatsApp oculta seu número de telefone, a {sender@id} parte do assunto agora contém o BSUID do remetente em vez de seu número de telefone.

Aviso

Alteração significativa: Se você tiver assinaturas da Grade de Eventos com filtros de assunto com base no número de telefone do remetente, esses filtros não corresponderão a eventos de usuários que adotaram um nome de usuário do WhatsApp e ocultaram seu número de telefone. Atualize seus filtros de assunto e qualquer código de automação de webhook que analise o assunto do evento para incluir os valores BSUID.

Assunto com número de telefone:

advancedMessage/sender/14255551234/recipient/11111111-1111-1111-1111-111111111111

Assunto com BSUID (número de telefone oculto):

advancedMessage/sender/US.13491208655302741918/recipient/11111111-1111-1111-1111-111111111111

Impacto nos eventos de status de entrega

O evento AdvancedMessageDeliveryStatusUpdated agora inclui um novo toBSUID campo que contém o BSUID do destinatário.

Se a mensagem tiver sido enviada para uma BSUID, o campo existente to poderá estar vazio.

Enviado para um número de telefone:

"data": {
  "from": "{channel-id}",
  "to": "14255550199",
  "toBSUID": "US.13491208655302741918",
  "status": "Delivered",
  "channelType": "whatsapp",
  "messageId": "22222222-2222-2222-2222-222222222222"
}

Enviado para um BSUID:

"data": {
  "from": "{channel-id}",
  "to": "",
  "toBSUID": "US.13491208655302741918",
  "status": "Delivered",
  "channelType": "whatsapp",
  "messageId": "22222222-2222-2222-2222-222222222222"
}

Regras de disponibilidade de número de telefone

Quando um usuário do WhatsApp adota um nome de usuário, seu número de telefone pode não aparecer mais em cargas de webhook. No entanto, o número de telefone ainda será incluído quando qualquer uma das seguintes condições for atendida:

  • Você deu uma mensagem ou ligou para o número de telefone do usuário nos últimos 30 dias.
  • Você recebeu uma mensagem ou chamada do número de telefone do usuário nos últimos 30 dias.
  • O usuário está em seu Livro de Contatos.

Observação

O período de análise de 30 dias é calculado por número de telefone comercial, e não por portfólio. Se você enviar uma mensagem a um usuário com um número de telefone comercial, os webhooks de outro número comercial do seu portfólio não incluirão o número do usuário, a menos que esse número específico também tenha interagido recentemente.

Livro de Contatos

O Meta fornece um recurso de Livro de Contatos que armazena automaticamente informações de contato do usuário do WhatsApp (número de telefone e mapeamentos BSUID) de interações. Detalhes principais

  • O Livro de Contatos é fornecido e hospedado pelo Meta. Ele está habilitado por padrão. Nenhum trabalho de integração é necessário.
  • O escopo é definido no nível do portfólio comercial.
  • Somente interações que ocorrem após o início do Livro de Contatos são capturadas. Interações anteriores não são armazenadas retroativamente.

Limitações

  • Modelos de autenticação: os modelos de autenticação de um toque, sem toques e cópia de código ainda requerem números de telefone. BSUIDs não podem ser usados para esses tipos de modelo.
  • Escopo de portfólio: os BSUIDs têm escopo para portfólios de negócios individuais e não podem ser usados em diferentes portfólios.
  • Livro de Contatos: captura apenas as interações após a inicialização. Nenhum dado retroativo.

Como se preparar

Aviso

Alteração significativa: Os campos from e to em eventos de Mensagens Avançadas agora podem estar vazios ou nulos. Qualquer código que pressupõe que esses campos sempre contenham um número de telefone será interrompido. Você deve atualizar seus manipuladores de eventos para usar os novos campos fromBSUID e toBSUID.

Para preparar sua integração aos nomes de usuário do WhatsApp e BSUIDs:

  1. Pare de assumir que from e to sempre contenham números de telefone. Examine qualquer lógica que analise, valide ou formate esses campos como números E.164. Esses campos agora podem estar vazios ou nulos.

  2. Processar fromBSUID e toBSUID campos. Atualize seus manipuladores de eventos para ler os novos campos BSUID em eventos AdvancedMessageReceived e AdvancedMessageDeliveryStatusUpdated .

  3. Atualize a lógica de mensagens de saída. Ao responder a um usuário apenas com nome de usuário, use a BSUID do campo fromBSUID como valor to na solicitação de envio. O envio para BSUIDs estará disponível a partir de junho de 2026.

  4. Examine os filtros de assunto da Grade de Eventos. Se você tiver assinaturas de webhook que filtram o evento subject (por exemplo, filtragem por um número de telefone de remetente específico), atualize esses filtros para também manipular valores BSUID. A parte do remetente do assunto agora pode conter um BSUID em vez de um número de telefone.

Linha do tempo principal

Date Etapa
terça-feira, 31 de março de 2026 BSUIDs começam a aparecer em cargas de webhook de produção
Início de abril de 2026 Lançamento do recurso Livro de Contatos
Junho de 2026 O envio de mensagens para BSUIDs já está disponível em produção; o WhatsApp está implementando gradualmente os nomes de usuário para os usuários finais

Conteúdo relacionado

  • Última atualização em