Nomes de utilizador do WhatsApp e IDs de utilizador por empresa (BSUID): o que muda nos webhooks da Cloud API
Os nomes de utilizador do WhatsApp permitem mostrar um nome em vez do número de telefone, por isso, desde o início de abril de 2026, os webhooks de mensagens da Cloud API também incluem um ID de utilizador por empresa (BSUID), como US.13491208655302741918, em user_id e from_user_id. Para um utilizador com nome de utilizador que não teve mensagens nem chamadas com o número nos últimos 30 dias e não está na lista de contactos, wa_id e from são omitidos.
A easyCoexistence liga um número da aplicação WhatsApp Business à Cloud API através da Coexistence e encaminha os seus webhooks messages e smb_message_echoes para o seu endpoint tal como a Meta os envia, com os campos BSUID incluídos, enquanto get_api_credentials dá ao seu código o necessário para responder com recipient.
Quando os BSUID começaram a aparecer nos webhooks da Cloud API, antes de os nomes de utilizador chegarem aos utilizadores do WhatsApp.
Quando as APIs passaram a aceitar mensagens enviadas para um BSUID, indicado em recipient em vez de to.
Período de retenção, por número de telefone da empresa, em que qualquer mensagem ou chamada com o utilizador mantém o número nos webhooks.
A maioria dos caracteres alfanuméricos depois do código de país de duas letras e do ponto de um BSUID.
Erro da Messages API: Business-scoped User ID (BSUID) recipients are not supported for this message.
Tipo de mensagem de sistema para uma alteração de BSUID comunicada sem número de telefone, com o BSUID antigo em previous_user_id.
O que são os nomes de utilizador e os BSUID do WhatsApp?
Um nome de utilizador é um nome único e opcional que um utilizador do WhatsApp pode definir, apresentado na aplicação em vez do número de telefone; a Meta está a disponibilizá-los gradualmente em 2026. Um BSUID é o identificador interno que a Meta acrescentou para que as empresas continuem a distinguir os utilizadores: gerado automaticamente, único para cada par de portefólio empresarial e utilizador, e escrito como o código de país ISO 3166 de duas letras do utilizador, um ponto e até 128 caracteres alfanuméricos. A Meta exige que os parceiros e as empresas com integração direta o suportem, uma vez que nenhuma empresa controla se os seus utilizadores adotam nomes de utilizador.
Que campos transportam os novos identificadores?
Propriedades novas ao lado das que continham o número de telefone, nos webhooks messages, status, system e user_preferences. Os campos parent só aparecem para portefólios empresariais que a Meta inscreveu em BSUID parent, que funcionam entre os portefólios inscritos:
Quando é que o número de telefone é omitido?
Quando o utilizador tem nome de utilizador e nenhuma das três condições da Meta se verifica. O número mantém-se nos webhooks se o número de telefone da empresa enviou mensagem ou ligou para o número do utilizador nos últimos 30 dias, recebeu uma mensagem ou chamada dele nesse período, ou se o utilizador está na lista de contactos do portefólio. A janela de 30 dias conta-se por número de telefone da empresa, pelo que um segundo número no mesmo portefólio pode receber apenas o BSUID do mesmo utilizador. Os utilizadores sem nome de utilizador continuam a chegar com o número de telefone e o BSUID.
Como é agora uma mensagem recebida?
Como antes, com o BSUID ao lado do número de telefone ou no seu lugar. No exemplo da Meta de um utilizador com nome de utilizador cujo número não pode ser partilhado, contacts traz profile.name, profile.username e user_id, e a mensagem traz from_user_id onde antes estava from:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
"contacts": [{
"profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
"user_id": "US.13491208655302741918"
}],
"messages": [{
"from_user_id": "US.13491208655302741918",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
"timestamp": "1749416383",
"type": "text",
"text": { "body": "Does it come in another color?" }
}]
}
}]
}]
}Como mudam os webhooks de estado?
Os estados sent, delivered e read ganham um array contacts com o nome do utilizador, user_id, wa_id quando o número pode ser partilhado, e username nos estados delivered e read. Em statuses, recipient_user_id transporta o BSUID, e recipient_id é omitido quando enviou para um BSUID e o número não pode ser partilhado. Um estado failed não tem array contacts e omite recipient_user_id quando a mensagem foi enviada para um número de telefone, por isso associe as falhas ao id da mensagem.
Como deve guardar e cruzar os utilizadores?
Pelo BSUID primeiro, com o número de telefone como segunda chave sempre que chegar. Guarde o BSUID completo como string, incluindo o código de país e o ponto, porque a Meta rejeita pedidos que alterem qualquer parte dele, e guarde também o BSUID parent se os seus portefólios estiverem inscritos. Associe os registos existentes pelo wa_id enquanto ele ainda chegar e mantenha o BSUID ao lado deles, porque um utilizador que adote um nome de utilizador mais tarde pode voltar sem número. A FAQ da Meta pede as mesmas associações nos CRM e nas ferramentas que os alimentam.
O que acontece quando um utilizador muda de número de telefone?
O seu BSUID é regenerado, e a alteração chega no campo messages como mensagem de sistema, já que a Meta não tem um campo user_id_update ao qual subscrever. system.type é user_changed_number quando o novo número pode ser partilhado com a sua empresa, ou user_changed_user_id quando só a alteração do BSUID pode ser comunicada; system.user_id contém o novo BSUID e system.previous_user_id o antigo, o que permite transportar o registo. Trate os dois tipos.
Como responde a um utilizador conhecido apenas pelo BSUID?
Envie para /<BUSINESS_PHONE_NUMBER_ID>/messages com recipient definido como o BSUID e to omitido; se ambos estiverem presentes, to prevalece e a resposta vai para o número de telefone. A entrada contacts da resposta traz então input e user_id em vez de wa_id. Qualquer tipo de mensagem funciona, exceto os templates de autenticação one-tap, zero-tap e copy code, que exigem um número de telefone, e apenas os números do mesmo portefólio empresarial podem chegar a um BSUID. O erro 131062 significa que o tipo de mensagem não aceita destinatários BSUID.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"recipient": "US.13491208655302741918",
"type": "text",
"text": { "body": "Yes, it also comes in blue." }
}Como pede ao utilizador o número de telefone?
Com o botão REQUEST_CONTACT_INFO, adicionado a um template de utilitário ou de marketing, ou enviado como mensagem interativa do tipo request_contact_info. Um utilizador que o toca partilha o número na conversa, e chega um webhook contacts com origin definido como contact_request e o número em phones[].wa_id; um contacto partilhado manualmente chega com origin other e um vCard. A Meta disponibilizou o botão no início de julho de 2026, e a etiqueta do botão não pode ser personalizada.
O que é a lista de contactos?
Um armazenamento que a Meta aloja para cada portefólio empresarial, sem trabalho de integração: quando um número de telefone da empresa troca mensagens ou chamadas com o número de telefone de um utilizador, esse número e o BSUID são registados e usados para preencher webhooks posteriores com o número de telefone, tenha ou não nome de utilizador. Só contam as interações posteriores ao seu lançamento. Pode ser desativado no Meta Business Suite, em Definições de negócio, Informações da empresa, o que apaga os dados que contém; e GET ou DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book com um bsuid verifica ou remove uma entrada.
O que deve mudar numa integração Coexistence?
O tratamento dos três webhooks que só um número Coexistence recebe, que também mudam. No webhook history, cada conversa ganha um objeto context com wa_id, user_id e username, e as suas mensagens ganham from_user_id. Em smb_message_echoes, é acrescentado um array contacts, e message_echoes[].to pode ser omitido enquanto to_user_id transporta o BSUID; as edições e revogações feitas na aplicação WhatsApp Business chegam da mesma forma. Em smb_app_state_sync, o phone_number de um contacto pode ser omitido, com user_id e username ao lado. Cruze os echoes e as conversas importadas pelo user_id, além do número.
Como pode testar antes de os utilizadores adotarem nomes de utilizador?
Com a ferramenta de teste da Meta no App Dashboard: em Use cases, Connect with customers through WhatsApp, Customize, Configuration, a ligação Test junto ao webhook de messages envia um exemplo para o seu endpoint. Cobre mensagens recebidas e estados em quatro cenários:
- Um utilizador sem nome de utilizador: campos de BSUID e de número de telefone, e sem username.
- Um utilizador com nome de utilizador cujo número não está disponível: username e BSUID, sem campos de número de telefone.
- Um utilizador com nome de utilizador cujo número está disponível: username, BSUID e número de telefone.
- Um portefólio inscrito em BSUID parent: um BSUID parent ao lado do BSUID próprio do portefólio.
Como trata o easyCoexistence os BSUID?
Transmite-os tal como a Meta os envia. Um número encaminhado para o seu endpoint com set_webhook_destination recebe os webhooks messages e smb_message_echoes diretamente da Meta, incluindo user_id, from_user_id, to_user_id e username, e, com automações ou reencaminhamento ativos, o easyCoexistence reencaminha o valor enviado pela Meta sem alterações. Para responder a um BSUID, o seu código usa get_api_credentials, que devolve o ID do número de telefone, o endpoint de envio e, quando disponível, o seu próprio token; as ferramentas send_message e send_template recebem um número de telefone em dígitos internacionais.
Erros comuns
- Usar apenas wa_id como chave dos contactos. Um utilizador com nome de utilizador que não teve contacto com o número nos últimos 30 dias chega apenas com user_id e from_user_id, e um handler que exige wa_id perde a mensagem.
- Cortar o prefixo de país de um BSUID. A Meta quer o valor completo, com o código de país e o ponto, e um pedido com qualquer parte alterada falha.
- Esperar por um campo user_id_update. A Meta não tem nenhum; as alterações de BSUID chegam em messages como mensagens de sistema dos tipos user_changed_number ou user_changed_user_id.
- Cruzar os echoes da Coexistence apenas por to. Em smb_message_echoes o campo to pode ser omitido, pelo que uma resposta escrita na aplicação passa despercebida, a menos que to_user_id também seja cruzado.
Cada ligação é monitorizada 24/7. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Os utilizadores sem nome de utilizador também recebem um BSUID?
Sim. A Meta define user_id nos webhooks de mensagens, tenham ou não nome de utilizador, por isso a maioria dos utilizadores chega com o número de telefone e o BSUID.
Um número Coexistence pode ter um nome de utilizador de empresa?
Sim. Desde 29 de junho de 2026, uma empresa pode adotá-lo ou alterá-lo no Meta Business Suite, no WhatsApp Manager, na aplicação WhatsApp Business ou na Username API; não oculta o número da empresa, e business_username_updates comunica cada alteração de estado.
Um BSUID funciona entre portefólios empresariais?
Não. Um BSUID pertence a um portefólio e a um utilizador, e um número de outro portefólio não lhe pode enviar mensagens. Os portefólios geridos que a Meta inscreve recebem BSUID parent, com ENT depois do código de país, que funcionam entre os portefólios inscritos.
Quanto custa o easyCoexistence por número do WhatsApp?
De US$ 9 a US$ 0.75 por ligação por mês, consoante o número de ligações, e os primeiros 3 dias são gratuitos. As cobranças de mensagens da própria Meta continuam no método de pagamento da sua WhatsApp Business Account.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em