Por que os BSUIDs existem
O WhatsApp está lançando nomes de usuário opcionais em 2026. Quando um usuário adota um nome de usuário, o WhatsApp pode exibir o nome de usuário em vez do número de telefone do usuário e pode omitir o número de telefone das cargas úteis de webhook. Cada usuário controla se deseja adotar um nome de usuário, de modo que as empresas não podem depender de números de telefone como a única forma de identificar clientes. Portanto, a Meta exige que empresas e parceiros da Plataforma WhatsApp Business, assim como anunciantes de anúncios do tipo clique para o WhatsApp, ofereçam suporte a BSUIDs para que possam continuar processando mensagens de usuários que adotam nomes de usuário. Para oferecer suporte a essa alteração, a Meta começou a adicionar IDs de usuário com escopo de negócios (BSUIDs) às cargas úteis de webhook no início de abril de 2026. Um BSUID é um identificador de back-end para um usuário do WhatsApp dentro de um portfólio de negócios da Meta. A Meta o inclui em webhooks de mensagens, independentemente de o usuário ter adotado ou não um nome de usuário, e ele pode ser usado para enviar mensagens ao usuário quando seu número de telefone não estiver disponível. Nomes de usuário e BSUIDs têm ciclos de vida diferentes. Um usuário pode alterar seu nome de usuário sem alterar seu número de telefone ou BSUID. Se o usuário alterar seu número de telefone, a Meta gera um novo BSUID. Armazene esses identificadores separadamente e atualize a associação deles ao receber um evento de sistema de alteração de número de telefone. Um número de telefone ainda pode aparecer quando o número de telefone comercial trocou uma mensagem ou chamada com o usuário nos últimos 30 dias, ou quando a lista de contatos da Meta contém o usuário. Trate os campos de número de telefone e nome de usuário como condicionais e atualize os analisadores e o armazenamento de identidades para aceitar BSUIDs junto com quaisquer outros identificadores presentes. Este guia aborda as regras de identidade de BSUID, solicitações de mensagem e chamada, a lista de contatos da Meta e os campos de webhook que sua integração precisa armazenar.
Entender os identificadores
A Meta gera BSUIDs regulares automaticamente. Cada BSUID começa com o código de país de duas letras ISO 3166 alfa-2 do usuário, seguido por um ponto e até 128 caracteres alfanuméricos. Preserve o valor completo. Não remova nem altere o prefixo do país, o ponto ou os caracteres do identificador.
Os BSUIDs têm as seguintes regras de ciclo de vida:
- Um BSUID é exclusivo para um par de portfólio de negócios e usuário.
- O BSUID de um usuário muda quando o usuário altera seu número de telefone.
- Um BSUID pai funciona em todos os portfólios vinculados para os quais a Meta o habilitou.
- Um número de telefone comercial não pode usar um BSUID regular com escopo de outro portfólio.
Antes de começar
- Armazene sua chave de API da YCloud em
YCLOUD_API_KEY. - Use um número de telefone comercial do WhatsApp de propriedade do mesmo portfólio que o BSUID regular.
- Inscreva seu endpoint de webhook nos eventos do WhatsApp que sua integração usa.
- Trate todos os novos campos de BSUID, BSUID pai, número de telefone e nome de usuário como opcionais ao desserializar webhooks.
- Armazene o BSUID regular e o BSUID pai de forma independente quando ambos estiverem presentes.
Enviar uma mensagem com um BSUID
Ambos os endpoints de mensagens do WhatsApp aceitamrecipient:
Defina
recipient como um BSUID regular ou um BSUID pai. Omita to quando quiser que a YCloud enderece o usuário por BSUID.
POST /whatsapp/messages para enfileirar a mensagem.
Solicitar o número de telefone de um usuário
Use uma mensagem de solicitação de informações de contato quando o seu fluxo de trabalho precisar de um número de telefone que não foi incluído em um webhook. O usuário decide se deseja compartilhá-lo.Usar um botão de modelo
Adicione um botãoREQUEST_CONTACT_INFO a um modelo de utilidade ou marketing. O texto do botão é fixado como Share Contact Info, e o botão não aceita parâmetros no momento do envio.
Usar uma mensagem interativa
Envie uma mensagem interativarequest_contact_info quando não precisar de um modelo:
Processar a resposta do contato
Quando o usuário compartilha informações de contato, a YCloud envia um eventowhatsapp.inbound_message.received cujo type da mensagem é contacts. Para uma resposta à sua solicitação, contacts[].origin é contact_request.
2xx e processe o número de telefone de forma assíncrona. Um contato compartilhado diretamente pelo WhatsApp também pode incluir um vCard.
Entender o catálogo de contatos da Meta
O catálogo de contatos da Meta armazena a associação entre o número de telefone e o BSUID de um usuário. Com o recurso ativado, enviar ou receber uma mensagem ou ligação usando o número de telefone do usuário registra ambos os identificadores. A Meta pode então incluir essa associação em webhooks mesmo depois de o usuário adotar um nome de usuário. Os catálogos de contatos pertencem a portfólios empresariais individuais. Portfólios vinculados não compartilham nem sincronizam suas entradas: registre a associação de forma independente em cada portfólio. A Meta retém as entradas até que você desative o recurso ou desative sua conta. Você pode desativá-lo em Meta Business Suite > Configurações do negócio > Informações da empresa. Desativar o recurso exclui as entradas armazenadas e interrompe o registro de novas entradas. Reativá-lo inicia a coleta de novas entradas; isso não restaura os dados excluídos.
Solicitações de contato e Local Storage
Quando um usuário compartilha o número de telefone por meio de um botão request-contact-info, a Meta adiciona o número de telefone ao catálogo de contatos se o recurso estiver ativado. Para empresas que usam Local Storage, a Meta extrai o número de telefone do vCard compartilhado e o armazena no catálogo de contatos nos data centers da Meta. Outros dados do vCard não são retidos além do período padrão de retenção. A Meta removeu a exigência anterior de enviar uma mensagem separada para capturar essa associação. Consulte a documentação oficial do BSUID para ver o comportamento atual do Local Storage.Verificar uma entrada no catálogo de contatos da Meta
UseGET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid} para verificar se a Meta possui uma entrada de número de telefone para um BSUID padrão. Esta operação não retorna o número de telefone nem modifica a entrada.
403. A WABA deve estar disponível para sua conta, o número de telefone deve estar vinculado a essa WABA e o BSUID padrão deve pertencer ao mesmo portfólio empresarial da Meta. BSUIDs pai contendo .ENT. não são suportados. Codifique o caractere inicial + do número de telefone em URL como %2B ao construir o caminho manualmente.
Uma resposta bem-sucedida sempre inclui o booleano present:
200 com present: false significa que nenhuma entrada correspondente existe. Entradas inválidas, falhas de permissão e falhas de upstream continuam sendo erros. Um HTTP 404 de upstream não significa present: false.
Excluir uma entrada do catálogo de contatos da Meta
Exclua uma entrada do catálogo de contatos da Meta para um BSUID comum por meio de um número de telefone comercial do WhatsApp com:DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}
.ENT. não são suportados. Codifique o caractere inicial + no número de telefone em URL como %2B ao construir o caminho manualmente.
Uma resposta HTTP 200 sempre contém success: true. Um valor de deleted igual a true significa que a Meta excluiu uma entrada correspondente. Um valor igual a false significa que a Meta processou a solicitação, mas não encontrou nenhuma entrada correspondente.
Excluir a entrada não exclui contatos, mensagens ou registros comerciais de BSUID da YCloud. Após a exclusão, os eventos de webhook para números de telefone comerciais no mesmo portfólio empresarial da Meta não incluirão mais o número de telefone e o BSUID do usuário juntos. O cache de 30 dias da Meta ainda pode fornecer ambos os identificadores, e uma interação posterior pode criar a entrada no catálogo de contatos novamente.
Iniciar uma chamada com um BSUID
POST /whatsapp/calls/connect também aceita recipient. As mesmas regras de destino se aplicam: forneça to ou recipient, e to tem precedência quando ambos estiverem presentes.
Processar campos de webhook de BSUID
Os seguintes payloads de webhook da YCloud mostram os campos adicionados ou alterados para suporte a BSUID. Atualize seu analisador para aceitar os novos identificadores e lidar com números de telefone de clientes ausentes.
Os exemplos incluem o envelope de evento da YCloud e mostram onde cada campo aparece. Campos opcionais seguem as regras de omissão abaixo. Remova os comentários
// <ADDED> e // <CHANGED> antes de usar um payload como dados de teste JSON.
Aplique estas regras de omissão:
- Um campo de BSUID pai está ausente quando os BSUIDs pai não estão habilitados.
- Um campo de destino de mensagem enviada ou chamada pode estar ausente quando você endereçou o usuário por número de telefone.
customerProfileaparece em atualizações de mensagemsent,deliverederead, mas não em atualizações defailed.customerProfile.usernameestá ausente quando o usuário não habilitou nomes de usuário. Também está ausente em atualizações de status desent.- Um número de telefone pode estar ausente mesmo quando o BSUID correspondente estiver presente.
whatsapp.message.updated
whatsapp.message.updated
O exemplo mostra uma mensagem entregue.
<CHANGED> marca to como condicional quando o número de telefone não está disponível. O novo objeto customerProfile é omitido para failed; seu username também é omitido para sent ou quando o usuário não possui nome de usuário.whatsapp.inbound_message.received
whatsapp.inbound_message.received
Armazene os novos identificadores do remetente juntamente com o nome de perfil existente. O destinatário corporativo
to permanece inalterado; o número de telefone do cliente from pode ser omitido. Veja o exemplo de alteração de número de telefone abaixo para uma mensagem system.whatsapp.user.preferences
whatsapp.user.preferences
A preferência permanece sob
whatsappUserPreference. Use os identificadores de usuário fornecidos mesmo quando contactPhoneNumber estiver ausente.whatsapp.call.connect
whatsapp.call.connect
Para chamadas iniciadas pela empresa, os identificadores do cliente são
toUserId e toParentUserId. Para chamadas iniciadas pelo usuário, são fromUserId e fromParentUserId. Apenas o campo de número de telefone do cliente pode ser omitido nestes exemplos.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.terminate
whatsapp.call.terminate
Para chamadas iniciadas pela empresa, os identificadores do cliente são
toUserId e toParentUserId. Para chamadas iniciadas pelo usuário, são fromUserId e fromParentUserId. Apenas o campo de número de telefone do cliente pode ser omitido nestes exemplos.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.status.updated
whatsapp.call.status.updated
Os identificadores do destinatário são irmãos de
recipientPhone sob callingStatusUpdated.whatsapp.group.participants_update
whatsapp.group.participants_update
Uma atualização de participante único pode conter identificadores diretamente sob
whatsappGroup. Resultados em lote contêm identificadores em cada item de addedParticipants, removedParticipants ou failedParticipants. Processe a matriz para a operação no evento.- adicionado
- removido
- falhou
whatsapp.smb.history
whatsapp.smb.history
Mantenha o wrapper específico do evento: o histórico de entrada usa
whatsappInboundMessage, enquanto o histórico de saída usa whatsappMessage. Os campos de saída toUserId e toParentUserId são aliases de compatibilidade de recipientUserId e parentRecipientUserId. Estes exemplos mostram eventos contendo mensagens; um bloco de histórico somente com metadados pode omitir ambos os objetos de mensagem.- Histórico de entrada
- Histórico de saída
whatsapp.smb.app.state.sync
whatsapp.smb.app.state.sync
Este payload foi mantido da documentação de migração legada de BSUID. Este evento não está listado no catálogo público atual de eventos assináveis; não o adicione a
enabledEvents com base neste exemplo. Use o formato abaixo ao manter uma integração que já recebe esse payload legado.whatsapp.smb.message.echoes
whatsapp.smb.message.echoes
Estas são mensagens enviadas a partir do aplicativo WhatsApp Business ou de um dispositivo complementar compatível. Os nomes de campo legados
toUserId e toParentUserId são aliases de compatibilidade de recipientUserId e parentRecipientUserId. Mantenha o perfil sob whatsappMessage.Lidar com alterações de número de telefone e BSUID
QuandowhatsappInboundMessage.type for system, processe ambas as variantes de alteração de identidade:
Use
system.user_id e qualquer system.parent_user_id fornecido para a nova identidade. Use system.previous_user_id e system.previous_parent_user_id para a identidade anterior quando fornecidos. Estes campos aninhados preservam os nomes originais em snake_case da Meta.
O exemplo a seguir mostra uma alteração de número de telefone:
wa_id é um número de telefone sem o + inicial e pode ser omitido; para user_changed_user_id, ele também pode permanecer inalterado. Não limpe um número de telefone existente apenas porque o evento o omite. Mantenha os identificadores anteriores e os novos por tempo suficiente para reconciliar conversas existentes e atualizar seu repositório de identidades de forma idempotente.
Consulte Mensagem de alteração de BSUID recebida para ver um exemplo sem número de telefone.
Nomes de usuário comerciais
Um nome de usuário comercial ajuda os clientes a encontrar sua empresa no WhatsApp. Ele não oculta o número de telefone da sua empresa. Cada número de telefone pode ter um nome de usuário, e um nome de usuário não pode ser compartilhado por dois números de telefone do WhatsApp. O nome de usuário de um consumidor pode mudar sem alterar o BSUID do usuário. Mantenha o nome de usuário como informação de perfil em vez de usá-lo como sua chave de identidade. Consulte Reivindicar um nome de usuário comercial para conhecer as regras de formato de 3 a 35 caracteres e o processo de reivindicação e análise.
Nomes de usuário reservados
Você pode reivindicar um nome de usuário qualificado reservado pela Meta ou escolher outro nome de usuário para sua marca. Use o Gerenciador do WhatsApp, o Meta Business Suite ou a API de nomes de usuário. A aprovação, por si só, não significa que o nome de usuário esteja ativo para os clientes. Se o nome de usuário reservado pertencer à sua Página do Facebook ou conta do Instagram, vincule o número de telefone da sua empresa a essa Página ou conta antes de reivindicá-lo. Você pode vinculá-lo ao reivindicar o nome de usuário no Meta Business Suite ou no Gerenciador do WhatsApp, ou adicionar o número de telefone à Página ou conta. É necessário ter controle total ou acesso parcial básico com a permissãomanage_phone.
Prioridade de exibição na janela de conversa
O WhatsApp exibe a identidade comercial nesta ordem:- O nome salvo nos contatos do cliente.
- O nome comercial verificado ou o nome da Conta Comercial Oficial.
- O nome de usuário comercial.
- O número de telefone.
Checklist de migração
- Adicione todos os campos de webhook relacionados a BSUID ao seu modelo de desserialização como um campo opcional.
- Armazene BSUIDs regulares e pai separadamente de números de telefone e nomes de usuário.
- Indexe a identidade do cliente por portfólio e BSUID. Não trate um BSUID como um identificador globalmente portátil.
- Encaminhe solicitações de mensagens e chamadas por meio de
toourecipiente teste a regra de precedência deto. - Teste usuários somente com nome de usuário, números de telefone ausentes, alterações de número de telefone, alterações de BSUID com número de telefone inalterado, BSUIDs pai ausentes, webhooks duplicados e presença e recriação da lista de contatos.
Exemplos de status de mensagem
Inspecione os payloads de mensagens enviadas, entregues, lidas e com falha.
Exemplos de mensagens recebidas
Inspecione contatos, atualizações do sistema e outros payloads recebidos.

