Usar IDs de usuário com escopo de negócios (BSUIDs)

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 dele e pode omitir o número de telefone das payloads de Webhook. Cada usuário tem controle sobre adotar ou não um nome de usuário, portanto, as empresas não podem depender dos números de telefone como a única forma de identificar clientes. Portanto, a Meta exige que empresas e parceiros da Plataforma do WhatsApp Business, bem como anunciantes de anúncios com clique para o WhatsApp, ofereçam suporte a BSUIDs para continuar processando mensagens de usuários que adotam nomes de usuário. Para oferecer suporte a essa mudança, a Meta começou a adicionar IDs de usuário com escopo de negócios (BSUIDs) às payloads de Webhook no início de abril de 2026. Um BSUID é um identificador de backend 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 um nome de usuário, e ele pode ser usado para enviar mensagens ao usuário quando o número de telefone dele 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 quando 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 tiver trocado uma mensagem ou chamada com o usuário nos 30 dias anteriores, ou quando a lista de contatos da Meta contiver 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 regras de identidade de BSUID, solicitações de mensagens e chamadas, a lista de contatos da Meta e os campos de Webhook que sua integração precisa armazenar. Exemplo de nome de usuário do WhatsApp

Entenda os identificadores

Identificador	Escopo	Exemplo	Quando usar
Número de telefone	Uma conta do WhatsApp	`+16315551111`	Use quando o número de telefone estiver disponível e a operação exigir um.
BSUID	Um portfólio de negócios da Meta e um usuário do WhatsApp	`US.13491208655302741918`	Use a partir de qualquer número de telefone comercial no mesmo portfólio.
BSUID principal	Um conjunto de portfólios de negócios vinculados da Meta e um usuário do WhatsApp	`US.ENT.11815799212886844830`	Use somente depois que a Meta habilitar BSUIDs principais para os portfólios vinculados.

A Meta gera BSUIDs regulares automaticamente. Cada BSUID começa com o código de país de duas letras ISO 3166 alpha-2 do usuário, seguido por um ponto e até 128 caracteres alfanuméricos. Mantenha 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 principal 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 definido para outro portfólio.

Modelos de mensagem de autenticação de um toque, zero toque e cópia de código exigem um número de telefone. Não envie esses tipos de modelos apenas com um BSUID.

Para vincular portfólios e usar BSUIDs principais, 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 principais. Exemplo de ID de usuário com escopo de negócios

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 pertencente ao mesmo portfólio que o BSUID regular.
Inscreva seu endpoint de Webhook nos eventos do WhatsApp utilizados pela sua integração.
Trate todos os novos campos de BSUID, BSUID principal, número de telefone e nome de usuário como opcionais ao desserializar Webhooks.
Armazene o BSUID regular e o BSUID principal de forma independente quando ambos estiverem presentes.

Enviar uma mensagem com um BSUID

Ambos os endpoints de mensagens do WhatsApp aceitam recipient:

Endpoint	Comportamento
`POST /whatsapp/messages/sendDirectly`	Envia a mensagem de forma síncrona para a API do WhatsApp Business.
`POST /whatsapp/messages`	Enfileira a mensagem para envio assíncrono.

Defina recipient como um BSUID regular ou um BSUID principal. Omita to quando quiser que a YCloud enderece o usuário por BSUID.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello from YCloud!"
    }
  }'

Use o mesmo corpo de solicitação com POST /whatsapp/messages para enfileirar a mensagem.

Entrada	Resultado
Apenas `to`	A YCloud envia para o número de telefone.
Apenas `recipient`	A YCloud envia para o BSUID ou BSUID principal.
Ambos `to` e `recipient`	A YCloud usa `to` e ignora `recipient`.
Nenhum dos campos	A YCloud rejeita a requisição.

Solicitar o número de telefone de um usuário

Use uma mensagem de solicitação de informações de contato quando 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 é fixo como Share Contact Info, e o botão não aceita parâmetros no momento do envio.

{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Crie e aprove o modelo antes de enviá-lo. Consulte Solicitar modelo de número de telefone para obter uma solicitação completa de modelo.

Usar uma mensagem interativa

Envie uma mensagem interativa request_contact_info quando não precisar de um modelo:

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Please share your phone number."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

Processar a resposta do contato

Quando o usuário compartilha informações de contato, a YCloud envia um evento whatsapp.inbound_message.received cujo tipo de mensagem type é contacts. Para uma resposta à sua solicitação, contacts[].origin é contact_request.

{
  "type": "whatsapp.inbound_message.received",
  "whatsappInboundMessage": {
    "fromUserId": "US.13491208655302741918",
    "type": "contacts",
    "contacts": [
      {
        "origin": "contact_request",
        "phones": [
          {
            "phone": "+16315551111",
            "wa_id": "16315551111"
          }
        ]
      }
    ]
  }
}

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 de solicitação de informações de contato

Botão de solicitação de 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 de um usuário e o BSUID. Com o recurso habilitado, enviar ou receber uma mensagem ou chamada 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 que 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 volta a coletar novas entradas; ele não restaura os dados excluídos. Configurações do catálogo de contatos da Meta

Configurações do catálogo de contatos da Meta

Solicitações de contato e Armazenamento Local

Quando um usuário compartilha seu número de telefone por meio de um botão de solicitação de contato, a Meta adiciona o número de telefone ao catálogo de contatos se o recurso estiver habilitado. Para empresas que usam o Armazenamento Local, 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 mantidos além do período de retenção padrã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 Armazenamento Local.

Excluir uma entrada do catálogo de contatos da Meta

Exclua uma entrada do catálogo de contatos da Meta para um BSUID regular através de um número de telefone comercial do WhatsApp com: DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}

curl --request DELETE \
  "https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/%2B16315551111/contactBook/US.13491208655302741918" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"

Use um BSUID padrão para esta operação. BSUIDs pais contendo .ENT. não são compatíveis. Codifique em URL o prefixo + no número de telefone 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 de 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 incluem mais o número de telefone do usuário e o BSUID juntos. O cache de 30 dias da Meta ainda pode fornecer ambos os identificadores, e uma interação posterior pode criar a entrada do 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.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/calls/connect \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "sdpType": "offer",
    "sdp": "SDP_OFFER"
  }'

Para o ciclo de vida completo de chamadas, consulte Gerenciar chamadas do WhatsApp.

Processar campos de webhook do BSUID

As seguintes cargas úteis 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.

Marcador	Significado
`<ADDED>`	Um novo campo ou objeto opcional introduzido para suporte a BSUID.
`<CHANGED>`	Um campo existente de número de telefone do cliente pode ser omitido; seu nome permanece inalterado.
Sem marcador	Campos existentes mantidos para mostrar a estrutura completa do evento.

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 uma carga útil como dados de teste em JSON.

Evento	Campos opcionais para armazenar
`whatsapp.message.updated`	`whatsappMessage.recipientUserId`, `whatsappMessage.parentRecipientUserId`, `whatsappMessage.customerProfile.name`, `whatsappMessage.customerProfile.username`
`whatsapp.inbound_message.received`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`
`whatsapp.user.preferences`	`whatsappUserPreference.userId`, `whatsappUserPreference.parentUserId`
`whatsapp.call.connect`	`callingConnect.toUserId`, `callingConnect.toParentUserId`, `callingConnect.fromUserId`, `callingConnect.fromParentUserId`
`whatsapp.call.terminate`	`callingTerminate.toUserId`, `callingTerminate.toParentUserId`, `callingTerminate.fromUserId`, `callingTerminate.fromParentUserId`
`whatsapp.call.status.updated`	`callingStatusUpdated.recipientUserId`, `callingStatusUpdated.parentRecipientUserId`
`whatsapp.group.participants_update`	`whatsappGroup.recipientUserId`, `whatsappGroup.parentRecipientUserId`, `whatsappGroup.customerProfile.username` e os campos `recipientUserId` e `parentRecipientUserId` em `whatsappGroup.addedParticipants[]`, `whatsappGroup.removedParticipants[]` e `whatsappGroup.failedParticipants[]`
`whatsapp.smb.history`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`, `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`
`whatsapp.smb.app.state.sync`	`whatsappSmbAppStateSync.stateSync[].contact.userId`, `whatsappSmbAppStateSync.stateSync[].contact.parentUserId`, `whatsappSmbAppStateSync.stateSync[].contact.username`
`whatsapp.smb.message.echoes`	`whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`, `whatsappMessage.customerProfile.username`

Aplique estas regras de omissão:

O campo de BSUID pai fica ausente quando os BSUIDs pai não estão habilitados.
O campo de destino de mensagem ou chamada enviada pode estar ausente quando você endereçou o usuário pelo número de telefone.
customerProfile aparece em atualizações de mensagem sent, delivered e read, mas não em atualizações failed.
customerProfile.username fica ausente quando o usuário não habilitou nomes de usuário. Também fica ausente em atualizações de status sent.
O número de telefone pode estar ausente mesmo quando o BSUID correspondente estiver presente.

whatsapp.message.updated

O exemplo mostra uma mensagem entregue. <CHANGED> marca to como condicional quando o número de telefone está indisponí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.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "delivered",
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "name": "Example customer", // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.inbound_message.received

Armazene os novos identificadores do remetente junto com o nome de perfil existente. O destinatário comercial to não é alterado; 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.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.user.preferences

A preferência permanece sob whatsappUserPreference. Use os identificadores de usuário fornecidos mesmo quando contactPhoneNumber estiver ausente.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "WABA_ID",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "BUSINESS_PHONE_ID",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222", // <CHANGED>
    "userId": "US.13491208655302741918", // <ADDED>
    "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1791532800000"
  }
}

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 do número de telefone do cliente pode ser omitido nesses exemplos.

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "answer",
    "sdp": "SDP_CONTENT"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "offer",
    "sdp": "SDP_CONTENT"
  }
}

whatsapp.call.terminate

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated

Os identificadores do destinatário são irmãos de recipientPhone sob callingStatusUpdated.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingStatusUpdated": {
    "wabaId": "WABA_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "status": "RINGING",
    "recipientPhone": "+16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.group.participants_update

Uma atualização de participante único pode conter identificadores diretamente sob whatsappGroup. Resultados em lote os contêm em cada item de addedParticipants, removedParticipants ou failedParticipants. Processe o array referente à operação no evento.

added
removed
failed

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "GROUP_ID@g.us",
    "addedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z",
    "waId": "16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "status": "removed",
    "groupId": "GROUP_ID@g.us",
    "removedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "failed",
    "groupId": "GROUP_ID@g.us",
    "failedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        },
        "errors": [
          {
            "code": 131000,
            "title": "Something went wrong",
            "message": "Please retry later."
          }
        ]
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

whatsapp.smb.history

Mantenha o wrapper específico do evento: o histórico de entrada usa whatsappInboundMessage, enquanto o 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 apenas com metadados pode omitir ambos os objetos de mensagem.

Histórico de entrada
Histórico de saída

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.smb.app.state.sync

Esse payload foi mantido da documentação de migração legada do BSUID. Esse 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.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.app.state.sync",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappSmbAppStateSync": {
    "wabaId": "WABA_ID",
    "phoneNumber": "+16315551111",
    "stateSync": [
      {
        "contact": {
          "fullName": "Example customer",
          "firstName": "Example",
          "phoneNumber": "+16315552222", // <CHANGED>
          "userId": "US.13491208655302741918", // <ADDED>
          "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
          "username": "example_customer" // <ADDED>
        },
        "action": "add",
        "timestamp": 1791532800000
      }
    ]
  }
}

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.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

Lidar com a alteração de número de telefone por um usuário

Quando whatsappInboundMessage.type for system e system.type for user_changed_number, os campos externos do remetente identificam a identidade antiga do usuário. Os campos aninhados de system contêm os novos BSUIDs e, quando disponível, o novo número de telefone. Use os nomes de campo user_id e parent_user_id dentro de system.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "system",
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    },
    "system": {
      "type": "user_changed_number",
      "wa_id": "16315553333", // <CHANGED>
      "user_id": "US.13491208655302741919", // <ADDED>
      "parent_user_id": "US.ENT.11815799212886844831" // <ADDED>
    }
  }
}

Trate parent_user_id como opcional. O novo número de telefone em wa_id também pode ser omitido, portanto use user_id e qualquer parent_user_id fornecido para atualizar o mapeamento de identidade. Mantenha os valores antigos e novos por tempo suficiente para reconciliar conversas existentes e atualizar seu armazenamento de identidades de forma idempotente.

Nomes de usuário comerciais

Um nome de usuário comercial ajuda os clientes a encontrarem 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 a sua marca. Use o Gerenciador do WhatsApp, a 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 seu número de telefone comercial 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. Você precisa de 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:

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.

Seu número de telefone comercial permanece visível no perfil comercial.

Lista de verificação 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 principais 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 to ou recipient e teste a regra de precedência de to.
Teste usuários apenas com nome de usuário, números de telefone ausentes, alterações de número de telefone, ausência de BSUIDs principais, Webhooks duplicados 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.

Primeiros passos

Guias

Endpoints

Webhooks

Usar IDs de usuário com escopo de negócios (BSUIDs)

Por que os BSUIDs existem

Entenda os identificadores

Antes de começar

Enviar uma mensagem com um BSUID

Solicitar o número de telefone de um usuário

Usar um botão de modelo

Usar uma mensagem interativa

Processar a resposta do contato

Entender o catálogo de contatos da Meta

Solicitações de contato e Armazenamento Local

Excluir uma entrada do catálogo de contatos da Meta

Iniciar uma chamada com um BSUID

Processar campos de webhook do BSUID

Lidar com a alteração de número de telefone por um usuário

Nomes de usuário comerciais

Nomes de usuário reservados

Prioridade de exibição na janela de conversa

Lista de verificação de migração

Exemplos de status de mensagem

Exemplos de mensagens recebidas

​Por que os BSUIDs existem

​Entenda os identificadores

​Antes de começar

​Enviar uma mensagem com um BSUID

​Solicitar o número de telefone de um usuário

​Usar um botão de modelo

​Usar uma mensagem interativa

​Processar a resposta do contato

​Entender o catálogo de contatos da Meta

​Solicitações de contato e Armazenamento Local

​Excluir uma entrada do catálogo de contatos da Meta

​Iniciar uma chamada com um BSUID

​Processar campos de webhook do BSUID

​Lidar com a alteração de número de telefone por um usuário

​Nomes de usuário comerciais

​Nomes de usuário reservados

​Prioridade de exibição na janela de conversa

​Lista de verificação de migração

Exemplos de status de mensagem

Exemplos de mensagens recebidas

Por que os BSUIDs existem

Entenda os identificadores

Antes de começar

Enviar uma mensagem com um BSUID

Solicitar o número de telefone de um usuário

Usar um botão de modelo

Usar uma mensagem interativa

Processar a resposta do contato

Entender o catálogo de contatos da Meta

Solicitações de contato e Armazenamento Local

Excluir uma entrada do catálogo de contatos da Meta

Iniciar uma chamada com um BSUID

Processar campos de webhook do BSUID

Lidar com a alteração de número de telefone por um usuário

Nomes de usuário comerciais

Nomes de usuário reservados

Prioridade de exibição na janela de conversa

Lista de verificação de migração