Uma integração da WhatsApp Business API identifica o cliente que usa um nome de usuário do WhatsApp por um ID de usuário vinculado à empresa (Business-Scoped User ID, BSUID), um código exclusivo de cada cliente em cada portfólio empresarial. O webhook ainda inclui o número de telefone quando o mesmo número comercial trocou uma mensagem ou ligação com o cliente nos últimos 30 dias. O número também continua nos webhooks para os clientes que estão na agenda de contatos, uma lista que a Meta mantém com os números de telefone de conversas anteriores. Todas as outras mensagens de um cliente com nome de usuário chegam com um BSUID e sem número de telefone. Um manipulador de webhooks precisa aceitar mensagens que chegam com um BSUID e sem número de telefone. Se ele as rejeitar, essas mensagens se perdem, e a Meta não tem como enviá-las de novo.
Principais conclusões
- A Meta exige que parceiros, empresas com integração direta e anunciantes de anúncios de clique para o WhatsApp na Plataforma do WhatsApp Business ofereçam suporte a BSUIDs.
- O número de telefone do cliente continua chegando por 30 dias após uma mensagem ou ligação no mesmo número comercial e enquanto o cliente estiver na agenda de contatos.
- Uma mensagem pode ir para um BSUID, um número de telefone ou os dois, e só os modelos de autenticação de um toque, sem toque e de copiar código ainda precisam do número de telefone.
- Uma empresa que precisa de um número de telefone pode pedi-lo na conversa com um botão, e o cliente decide se quer compartilhá-lo.
- A 360Dialog, Official Meta Solution Partner, dá às empresas acesso à WhatsApp Business API, que aceita BSUIDs como destinatários das mensagens.
O que é um ID de usuário vinculado à empresa (BSUID)?
Um ID de usuário vinculado à empresa (BSUID) é um identificador que o WhatsApp gera para cada par de cliente e portfólio empresarial, e ele chega nos webhooks, tenha o cliente um nome de usuário ou não. Armazenar o BSUID dá à integração uma chave de cliente única que continua funcionando quando o cliente deixa de compartilhar o número de telefone.
Um nome de usuário é um nome opcional e exclusivo que um usuário do WhatsApp pode mostrar no lugar do número de telefone, e o WhatsApp está lançando os nomes de usuário aos poucos.[1] Nosso guia sobre nomes de usuário do WhatsApp para empresas mostra o que muda para os clientes e para as equipes que os atendem.
A Meta exige que todo parceiro e toda empresa com integração direta na Plataforma do WhatsApp Business ofereçam suporte a BSUIDs, e a exigência vale também para os anunciantes de anúncios de clique para o WhatsApp.[2] Os BSUIDs aparecem nos webhooks desde o início de abril de 2026. Na Cloud API, o valor fica no campo user_id de todo webhook messages.
Armazene e envie cada BSUID completo, porque uma solicitação com uma parte faltando ou alterada falha. Uma coluna de banco de dados para o BSUID precisa de espaço para o código de país de duas letras, o ponto e até 128 letras e dígitos depois dele. Cada BSUID funciona dentro de um portfólio empresarial, antes chamado de Gerenciador de Negócios, e só os números de telefone comerciais desse portfólio podem enviar mensagens a ele. Por isso, o mesmo cliente tem um BSUID diferente em cada portfólio.
Quando a API ainda retorna o número de telefone do cliente?
Os webhooks ainda trazem o número de telefone do cliente quando esse número de telefone comercial trocou uma mensagem ou ligação com o cliente nos últimos 30 dias ou quando o cliente está na agenda de contatos da empresa. Saber qual caso se aplica mostra à equipe quais conversas precisam primeiro do tratamento de BSUID.
Cinco situações definem quais identificadores um webhook traz, segundo a documentação da Meta sobre BSUID.
| Situação | Número de telefone | BSUID |
|---|---|---|
| O cliente não tem nome de usuário | Incluído | Incluído |
| O cliente tem nome de usuário, e este número comercial enviou ou recebeu uma mensagem ou ligação com ele nos últimos 30 dias | Incluído | Incluído |
| O cliente tem nome de usuário e está na agenda de contatos do portfólio | Incluído | Incluído |
| O cliente tem nome de usuário e compartilha o número com o botão Solicitar informações de contato | Incluído em um webhook contacts | Incluído |
| O cliente tem nome de usuário e não atende a nenhuma das condições acima | Omitido | Incluído |
A verificação dos 30 dias vale por número de telefone comercial, enquanto a agenda de contatos cobre o portfólio inteiro. Um cliente que volta fora dos dois casos pode parecer uma nova conversa. As ligações contam como mensagens, incluindo as feitas pela WhatsApp Calling API. Uma conversa que começa em anúncios de clique para o WhatsApp segue as mesmas condições.
Como funciona a agenda de contatos na API?
A agenda de contatos é uma lista que a Meta mantém para cada portfólio empresarial, e ela guarda o número de telefone do cliente junto com o BSUID dele assim que o cliente e a empresa trocam uma mensagem ou ligação. Enquanto o cliente estiver nela, os webhooks continuam trazendo o número de telefone depois que a janela de 30 dias se fecha. Duas chamadas de API permitem que a integração verifique e remova entradas individuais.
A agenda de contatos não precisa de configuração, e as entradas ficam até a empresa desativar o recurso no Meta Business Suite, em Configurações da empresa > Informações da empresa, ou desativar a própria conta. Desativar o recurso apaga todas as entradas de vez. A agenda registra apenas as interações posteriores ao lançamento pela Meta, e os números de telefone dela aparecem somente nas notificações de webhook.
A Meta adicionou a chamada de verificação em 24 de agosto de 2026 e mudou a resposta da chamada de exclusão em 25 de agosto de 2026.[3] As duas chamadas recebem um BSUID padrão e rejeitam BSUIDs principais.
| Chamada | Solicitação | Resposta |
|---|---|---|
| Verificação | GET /<BUSINESS_PHONE_NUMBER_ID>/contact_book?messaging_product=whatsapp&bsuid=<BSUID> | contacts com bsuid e present (true ou false), nunca o número de telefone |
| Exclusão | DELETE no mesmo caminho | success e deleted, com deleted definido como false para qualquer BSUID sem entrada |
O valor false em deleted é o mesmo para um BSUID desconhecido, para um inválido e para um de outro portfólio. Depois de uma exclusão, o número de telefone ainda pode aparecer dentro da janela de 30 dias ou após uma nova interação.
Como pedir um número de telefone com o botão Solicitar informações de contato?
O botão Solicitar informações de contato pede ao cliente que compartilhe o número de telefone na conversa, e o número volta em um webhook contacts junto com o BSUID. Com ele, qualquer fluxo que precise de um número de telefone pode coletá-lo dentro da conversa, com o consentimento do cliente.
O botão está disponível desde o início de julho de 2026 em modelos de utilidade e de marketing e em uma mensagem interativa. Um número compartilhado dessa forma também entra automaticamente na agenda de contatos quando a empresa usa a agenda. As orientações da Meta pedem que os bots que precisam de um número o solicitem e tratem os clientes que recusam.
Como enviar mensagens para um BSUID?
A empresa envia uma mensagem para um BSUID pela mesma solicitação de envio que usa para números de telefone, com o BSUID em um campo próprio. Enviar mensagens pelo BSUID permite que a empresa continue conversando com clientes cujo número de telefone ela nunca recebeu.
A Meta data o envio por BSUID a partir de julho de 2026. Uma solicitação identifica o cliente pelo número de telefone, pelo BSUID ou pelos dois, e o número de telefone tem prioridade quando os dois estão presentes.
Todos os tipos de mensagem funcionam com BSUID, exceto os modelos de autenticação de um toque, sem toque e de copiar código, que ainda precisam de um número de telefone. A API de Mensagens de Marketing também aceita BSUIDs, e a Meta recomenda números de telefone nela porque assim os webhooks continuam retornando o número.
Nossa documentação sobre nomes de usuário e BSUID mostra a solicitação de envio completa, a resposta e os códigos de erro na API da 360Dialog.[4]
O que muda nos webhooks?
Os webhooks agora trazem o BSUID do cliente em toda mensagem recebida e nos status de enviada, entregue e lida, e o número de telefone aparece só quando uma das condições de número de telefone da Meta se aplica. Um analisador que trata o BSUID como identificador obrigatório continua processando todas as mensagens.
O BSUID fica ao lado do número de telefone nas mesmas notificações, em campos próprios. Os campos de número de telefone aparecem quando o cliente não tem nome de usuário, quando uma condição de número de telefone se aplica ou quando a mensagem foi para um número de telefone, e o nome de usuário do cliente chega como um dado do perfil quando ele tem um. Os campos que não se aplicam ficam fora da notificação.
Uma mudança de número de telefone dá ao cliente um novo BSUID, informado no webhook messages como uma mensagem do sistema do tipo user_changed_number ou user_changed_user_id. As duas trazem previous_user_id, o BSUID antigo. A integração usa esse campo para encontrar o registro do cliente que já existe. A Meta não documenta um campo de webhook user_id_update separado.
Como gerenciar o nome de usuário da empresa pela API?
A empresa define, consulta e exclui o nome de usuário de cada número de telefone comercial pela API de nomes de usuário (Username API) da Meta, que também informa mudanças de status por webhook. Incluir essas chamadas em uma plataforma permite que a equipe acompanhe os nomes de usuário de muitos números em um só lugar.
A empresa pode definir ou alterar um nome de usuário para cada número de telefone comercial, consultar o status dele, aprovado ou reservado, e excluí-lo, e uma chamada de sugestões retorna nomes reservados com mais chance de aprovação. Um nome de usuário aprovado fica ativo assim que os nomes de usuário estiverem disponíveis no país da empresa. Os clientes da 360Dialog fazem isso com os pontos de extremidade de nome de usuário da empresa na nossa referência da API.[5]
Cada número de telefone comercial pode definir 2 novos nomes de usuário em qualquer período móvel de 14 dias, ou 10 quando o resultado tem status reservado, e uma solicitação acima do limite falha. A contagem é feita por número, e excluir um nome de usuário não a altera.
O webhook business_username_updates, que cada app assina, informa os status aprovado, excluído e reservado. Quando a Meta revoga um nome de usuário, o webhook informa a revogação, e o nome de usuário é excluído ou substituído por um nome gerado automaticamente.
Como funcionam os BSUIDs principais em vários portfólios?
Um BSUID principal é um identificador por cliente que todo portfólio empresarial inscrito na mesma conta de BSUID principal pode usar. Ele permite que uma empresa gerenciada com vários portfólios reconheça o mesmo cliente em todos eles.
A Meta oferece BSUIDs principais a empresas gerenciadas, e o ponto de contato da empresa na Meta verifica a elegibilidade. Os webhooks passam então a trazer o BSUID principal ao lado do BSUID comum, em parent_user_id, from_parent_user_id e recipient_parent_user_id. Um BSUID principal acrescenta ENT depois do código de país, e qualquer número de telefone comercial de um portfólio inscrito pode enviar mensagens a ele.
A inscrição mantém inalterados os controles de acesso, o faturamento e a administração de cada portfólio. As agendas de contatos continuam separadas por portfólio. Para listar os portfólios inscritos, a empresa chama GET https://api.facebook.com/<BUSINESS_ID>/parent-bsuid-accounts, que retorna parent_bsuid_account_id e enrolled_business_portfolios.
As plataformas que operam uma integração multicliente do WhatsApp mantêm os BSUIDs de cada cliente dentro do portfólio desse cliente.
O que a sua integração precisa tratar agora?
Uma integração pronta para BSUIDs armazena o BSUID como identificador central do cliente, trata o número de telefone como opcional e pede um número só onde um fluxo precisa dele. Essas mudanças mantêm cada conversa ligada ao registro de cliente certo.
Na prática, os analisadores de webhook e as colunas do banco de dados aceitam mensagens que trazem só um BSUID, e cada registro de cliente guarda o BSUID junto com o número de telefone. Os sistemas de CRM, campanhas, mensuração e faturamento passam então a identificar os clientes também pelo BSUID. Os fluxos que precisam de um número o pedem com o botão Solicitar informações de contato e mantêm um caminho para os clientes que recusam, e a ferramenta de teste de webhooks da Meta verifica o analisador em cada caso. As equipes que planejam respostas com apoio de IA podem ler como o agente de IA funciona com a API no nosso guia completo do Meta Business Agent. Quando todos os sistemas identificam os clientes pelo BSUID, cada conversa chega ao registro de cliente a que pertence, e quem a responde vê o histórico completo.
A 360Dialog é Official Meta Solution Partner da WhatsApp Business API, e a nossa documentação sobre nomes de usuário e BSUID traz a lista de verificação da integração passo a passo, com as solicitações de envio e as notificações de webhook na API da 360Dialog. Clique em Começar a usar a API para criar e testar o tratamento de BSUID no seu próprio número da WhatsApp Business API. Fale conosco para preparar a sua integração da WhatsApp Business API para os BSUIDs.
Perguntas frequentes
Uma empresa pode enviar mensagem a um cliente pelo nome de usuário?
Uma empresa não pode usar um nome de usuário como endereço de mensagem na WhatsApp Business API. As solicitações de envio aceitam um número de telefone no campo to ou um BSUID no campo recipient. O nome de usuário chega à empresa nos webhooks como dado do perfil, e o cliente pode alterá-lo quando quiser. O BSUID continua o mesmo após essa mudança e é o identificador a armazenar.
As mensagens de autenticação ainda são enviadas para números de telefone?
Os modelos de autenticação de um toque, sem toque e de copiar código ainda vão para o número de telefone do cliente, e enviar um deles para um BSUID falha com o erro 131062. Uma empresa que tem só o BSUID pode primeiro pedir o número com o botão Solicitar informações de contato. Depois que o cliente compartilha o número, a empresa envia o modelo de autenticação para esse número.
Como testar um manipulador de webhooks para BSUIDs?
A ferramenta de teste de webhooks da Meta envia notificações de exemplo com BSUID a um manipulador de webhooks pelo App Dashboard. Abra Casos de uso, depois Conectar-se com clientes pelo WhatsApp, Personalizar e Configuração, e selecione Testar ao lado do campo messages. A ferramenta cobre quatro casos: sem nome de usuário, nome de usuário sem telefone, nome de usuário com telefone e notificação com BSUID principal.
Os parceiros precisam atualizar as integrações dos clientes para BSUIDs?
Os parceiros na Plataforma do WhatsApp Business precisam oferecer suporte a BSUIDs, exigência que a Meta estende a empresas com integração direta e a anunciantes de anúncios de clique para o WhatsApp. O app de um parceiro pode enviar mensagens aos BSUIDs de um cliente pelos números comerciais do cliente. O BSUID de um cliente falha com o número do parceiro, porque cada BSUID pertence a um só portfólio empresarial.
Fontes
[1] WhatsApp Help Center, “About usernames,” https://faq.whatsapp.com/658755553162769/ (accessed October 29, 2026).
[2] Meta for Developers, “Business-scoped user IDs,” updated October 23, 2026, https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/ (accessed October 29, 2026).
[3] Meta for Developers, “Changelog,” https://developers.facebook.com/documentation/business-messaging/whatsapp/changelog/ (accessed October 29, 2026).
[4] 360Dialog documentation, “Usernames & BSUID,” https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid (accessed October 29, 2026).
[5] 360Dialog documentation, “Business Username,” https://docs.360dialog.com/docs/messaging-api/api-reference/business-username (accessed October 29, 2026).
