Saltar para o conteúdo principal

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. Exemplo de nome de usuário de usuário do WhatsApp

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.
Modelos de autenticação de um toque, zero toque e copiar código exigem um número de telefone. Não envie esses tipos de modelo apenas com um BSUID.
Para vincular portfólios e usar BSUIDs pai, peça ao seu ponto de contato da Meta para verificar sua elegibilidade. Você pode continuar usando BSUIDs regulares dentro de seus portfólios originais depois que a Meta habilitar os BSUIDs pai. Exemplo de ID de usuário com escopo de negócios

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 aceitam recipient: Defina recipient como um BSUID regular ou um BSUID pai. Omita to quando quiser que a YCloud enderece o usuário por BSUID.
Use o mesmo corpo de solicitação com 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ão REQUEST_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.
Crie e aprove o modelo antes de enviá-lo. Consulte Modelo de solicitação de número de telefone para ver uma solicitação completa de modelo.

Usar uma mensagem interativa

Envie uma mensagem interativa request_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 evento whatsapp.inbound_message.received cujo type da mensagem é contacts. Para uma resposta à sua solicitação, contacts[].origin é contact_request.
Valide a assinatura do evento, confirme-o com uma resposta 2xx e processe o número de telefone de forma assíncrona. Um contato compartilhado diretamente pelo WhatsApp também pode incluir um vCard. Botão para solicitar informações de contato

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. Configurações do catálogo de contatos da Meta

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

Use GET /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.
Use a chave de API da sua conta da YCloud. Chaves de API de Developer App retornam HTTP 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:
HTTP 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}
Use um BSUID padrão para esta operação. BSUIDs pai contendo .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.
Para ver o ciclo de vida completo de chamadas, consulte Gerenciar chamadas do WhatsApp.

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.
  • customerProfile aparece em atualizações de mensagem sent, delivered e read, mas não em atualizações de failed.
  • customerProfile.username está ausente quando o usuário não habilitou nomes de usuário. Também está ausente em atualizações de status de sent.
  • Um número de telefone pode estar ausente mesmo quando o BSUID correspondente estiver presente.
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.
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.
A preferência permanece sob whatsappUserPreference. Use os identificadores de usuário fornecidos mesmo quando contactPhoneNumber estiver ausente.
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.
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.
Os identificadores do destinatário são irmãos de recipientPhone sob callingStatusUpdated.
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.
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.
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.
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

Quando whatsappInboundMessage.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:
Trate todos os campos de identidade como opcionais. BSUIDs pai são fornecidos apenas quando ativados e disponíveis. 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. Exemplo de nome de usuário comercial

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ão manage_phone.

Prioridade de exibição na janela de conversa

O WhatsApp exibe a identidade comercial nesta ordem:
  1. O nome salvo nos contatos do cliente.
  2. O nome comercial verificado ou o nome da Conta Comercial Oficial.
  3. O nome de usuário comercial.
  4. O número de telefone.
O número de telefone da sua empresa permanece visível no perfil comercial.

Checklist de migração

  1. Adicione todos os campos de webhook relacionados a BSUID ao seu modelo de desserialização como um campo opcional.
  2. Armazene BSUIDs regulares e pai separadamente de números de telefone e nomes de usuário.
  3. Indexe a identidade do cliente por portfólio e BSUID. Não trate um BSUID como um identificador globalmente portátil.
  4. Encaminhe solicitações de mensagens e chamadas por meio de to ou recipient e teste a regra de precedência de to.
  5. 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.