EntrarComeçar teste grátis
Meta Tech Provider

Nomes de usuário do WhatsApp e IDs de usuário com escopo de negócio (BSUID): o que muda nos webhooks da Cloud API

Os nomes de usuário do WhatsApp permitem que os usuários exibam um nome no lugar do número de telefone. Por isso, desde o início de abril de 2026, os webhooks de mensagens da Cloud API também trazem um ID de usuário com escopo de negócio (BSUID), como US.13491208655302741918, em user_id e from_user_id. Para um usuário com nome de usuário que não trocou mensagens nem chamadas com o número nos últimos 30 dias e não está na agenda de contatos, wa_id e from são omitidos.

O easyCoexistence conecta um número do app do WhatsApp Business à Cloud API pela Coexistência e roteia os webhooks messages e smb_message_echoes dele para o seu endpoint como a Meta os envia, com os campos de BSUID incluídos, enquanto get_api_credentials dá ao seu código o que ele precisa para responder com recipient.

April 2026

Quando os BSUIDs começaram a aparecer nos webhooks da Cloud API, antes de os nomes de usuário chegarem aos usuários do WhatsApp.

July 2026

Quando as APIs passaram a aceitar mensagens enviadas a um BSUID, informado em recipient no lugar de to.

30 days

Janela retroativa, por número comercial, em que qualquer mensagem ou chamada com o usuário mantém o número dele nos webhooks.

128

Número máximo de caracteres alfanuméricos depois do código de país de duas letras e do ponto em um BSUID.

131062

Erro da Messages API: "Business-scoped User ID (BSUID) recipients are not supported for this message."

user_changed_user_id

Tipo de mensagem de sistema para uma mudança de BSUID informada sem número de telefone, com o BSUID antigo em previous_user_id.

O que são nomes de usuário e BSUIDs do WhatsApp?

Um nome de usuário é um nome único e opcional que o usuário do WhatsApp pode definir, exibido no app no lugar do número de telefone; a Meta está liberando os nomes de usuário gradualmente em 2026. Um BSUID é o identificador de backend que a Meta criou para que as empresas continuem distinguindo os usuários: gerado automaticamente, único para cada par de Portfólio de Negócios e usuário, e escrito como o código de país ISO 3166 de duas letras do usuário, um ponto e até 128 caracteres alfanuméricos. A Meta exige que parceiros e empresas com integração direta deem suporte a ele, já que nenhuma empresa controla se seus usuários vão adotar nomes de usuário.

Quais campos trazem os novos identificadores?

Novas propriedades ao lado das que continham o número de telefone, nos webhooks messages, status, system e user_preferences. Os campos parent aparecem apenas para Portfólios de Negócios que a Meta inscreveu em BSUIDs pai, que funcionam entre os portfólios inscritos:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

Quando o número de telefone é omitido?

Quando o usuário tem nome de usuário e nenhuma das três condições da Meta se aplica. O número permanece nos webhooks se o número comercial enviou mensagem ou ligou para o número do usuário nos últimos 30 dias, recebeu mensagem ou chamada dele nesse período, ou se o usuário está na agenda de contatos do portfólio. A janela de 30 dias é contada por número comercial, então um segundo número no mesmo portfólio pode receber apenas o BSUID do mesmo usuário. Usuários sem nome de usuário continuam chegando com o número de telefone e com o BSUID.

Como fica uma mensagem recebida agora?

Como antes, com o BSUID ao lado do número de telefone ou no lugar dele. No exemplo da Meta de um usuário com nome de usuário cujo número não pode ser compartilhado, contacts traz profile.name, profile.username e user_id, e a mensagem traz from_user_id onde antes vinha from:

messages webhook: a text from a user known only by BSUID
{
  "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 status?

Os status enviado, entregue e lido ganham um array contacts com o nome do usuário, user_id, wa_id quando o número pode ser compartilhado, e username nos status entregue e lido. Em statuses, recipient_user_id traz o BSUID, e recipient_id é omitido quando você enviou para um BSUID e o número não pode ser compartilhado. Um status de falha não tem array contacts e omite recipient_user_id quando a mensagem foi enviada para um número de telefone, então associe as falhas ao id da mensagem.

Como armazenar e associar os usuários?

Primeiro pelo BSUID, com o número de telefone como segunda chave sempre que ele chegar. Armazene o BSUID inteiro como string, com código de país e ponto, pois a Meta rejeita requisições que alterem qualquer parte dele, e armazene também o BSUID pai se seus portfólios estiverem inscritos. Associe os registros existentes por wa_id enquanto ele ainda chegar e guarde o BSUID junto, porque um usuário que adotar um nome de usuário depois pode voltar sem número. A FAQ da Meta pede as mesmas associações em CRMs e nas ferramentas que eles alimentam.

O que acontece quando um usuário muda o número de telefone?

O BSUID dele é gerado de novo, e a mudança chega no campo messages como mensagem de sistema, já que a Meta não tem um campo user_id_update para assinar. system.type é user_changed_number quando o novo número pode ser compartilhado com você, ou user_changed_user_id quando só a mudança do BSUID pode ser informada; system.user_id traz o novo BSUID e system.previous_user_id o antigo, o que permite transferir o registro. Trate os dois tipos.

Como responder a um usuário conhecido apenas pelo BSUID?

Envie para /<BUSINESS_PHONE_NUMBER_ID>/messages com recipient definido como o BSUID e sem to; com os dois presentes, to prevalece e a resposta vai para o número de telefone. A entrada contacts da resposta então traz input e user_id em vez de wa_id. Qualquer tipo de mensagem funciona, exceto templates de autenticação one-tap, zero-tap e copy code, que exigem número de telefone, e só números do mesmo Portfólio de Negócios podem alcançar um BSUID. O erro 131062 significa que o tipo de mensagem não aceita destinatários BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

Como pedir o número de telefone de um usuário?

Com o botão REQUEST_CONTACT_INFO, adicionado a um template de utilidade ou de marketing, ou enviado como mensagem interativa do tipo request_contact_info. Um usuário que toca nele compartilha 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 contato compartilhado manualmente chega com origin igual a other e um vCard. A Meta disponibilizou o botão no início de julho de 2026, e o texto dele não pode ser personalizado.

O que é a agenda de contatos?

Um armazenamento que a Meta hospeda para cada Portfólio de Negócios, sem trabalho de integração: assim que um número comercial envia mensagem ou liga para o número de telefone de um usuário, ou recebe contato dele, esse número e o BSUID são registrados e usados para preencher os webhooks seguintes com o número de telefone, tenha o usuário nome de usuário ou não. Só contam as interações posteriores ao lançamento. Ela pode ser desativada no Meta Business Suite, em Business settings, Business info, o que apaga o que ela guarda, e GET ou DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book com um bsuid consulta ou remove uma entrada.

O que uma integração de Coexistência deve mudar?

A forma como trata os três webhooks que só um número de Coexistência recebe, que também mudam. Em history, cada conversa ganha um objeto context com wa_id, user_id e username, e as mensagens dela ganham from_user_id. Em smb_message_echoes, é adicionado um array contacts, e message_echoes[].to pode ser omitido, com to_user_id trazendo o BSUID; edições e mensagens apagadas no app do WhatsApp Business chegam da mesma forma. Em smb_app_state_sync, o phone_number de um contato pode ser omitido, com user_id e username ao lado. Associe os echoes e as conversas importadas por user_id, além do número.

Como testar antes de os usuários adotarem nomes de usuário?

Com a ferramenta de teste da Meta no App Dashboard: em Use cases, Connect with customers through WhatsApp, Customize, Configuration, o link Test ao lado do webhook messages envia um exemplo ao seu endpoint. Ela cobre mensagens recebidas e status em quatro cenários:

  • Usuário sem nome de usuário: campos de BSUID e de número de telefone, sem username.
  • Usuário com nome de usuário cujo número não está disponível: username e BSUID, sem campos de número de telefone.
  • Usuário com nome de usuário cujo número está disponível: username, BSUID e número de telefone.
  • Portfólio inscrito em BSUIDs pai: um BSUID pai ao lado do BSUID do próprio portfólio.

Como o easyCoexistence trata os BSUIDs?

Ele os repassa como a Meta os envia. Um número roteado para o seu endpoint com set_webhook_destination recebe os webhooks messages e smb_message_echoes diretamente da Meta, com user_id, from_user_id, to_user_id e username incluídos, e, com automações ou encaminhamento ativos, o easyCoexistence encaminha o valor enviado pela Meta sem alterações. Para responder a um BSUID, seu código usa get_api_credentials, que retorna o ID do número de telefone, o endpoint de envio dele e, quando disponível, o seu próprio token; as ferramentas send_message e send_template recebem um número de telefone em formato internacional, só com dígitos.

Erros comuns

  • Usar só wa_id como chave dos contatos. Um usuário com nome de usuário que não teve contato 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 do BSUID. A Meta exige o valor inteiro, com código de país e ponto, e uma requisição com qualquer parte alterada falha.
  • Esperar por um campo user_id_update. A Meta não tem esse campo: mudanças de BSUID chegam em messages como mensagens de sistema do tipo user_changed_number ou user_changed_user_id.
  • Associar os echoes da Coexistência só por to. Em smb_message_echoes o campo to pode ser omitido, então uma resposta digitada no app passa despercebida se to_user_id não for considerado também.
Fazendo isso com o EasyCoexistence

Toda conexão é monitorada 24/7. De R$ 29,90 a R$ 3,90 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Usuários sem nome de usuário também têm BSUID?

Sim. A Meta preenche user_id nos webhooks de mensagens tenha o usuário nome de usuário ou não, então a maioria dos usuários chega com o número de telefone e o BSUID.

Um número de Coexistência pode ter nome de usuário comercial?

Sim. Desde 29 de junho de 2026, uma empresa pode adotar ou alterar um no Meta Business Suite, no WhatsApp Manager, no app do WhatsApp Business ou pela Username API; isso não oculta o número comercial, e business_username_updates informa cada mudança de status.

Um BSUID funciona entre Portfólios de Negócios diferentes?

Não. Um BSUID pertence a um portfólio e a um usuário, e um número de outro portfólio não pode enviar mensagens para ele. Empresas gerenciadas que a Meta inscreve recebem BSUIDs pai, com ENT depois do código de país, que funcionam entre os portfólios inscritos.

Quanto custa o easyCoexistence por número de WhatsApp?

De R$ 29,90 a R$ 3,90 por conexão por mês, conforme a quantidade de conexões, e os primeiros 3 dias são grátis. As cobranças de mensagens da própria Meta continuam no método de pagamento da sua WhatsApp Business Account.

Continue lendo

Pronto para começar?

Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.

Começar teste grátis

Verificado em