BSUID - ID de contatos, metadata, endpoints e aplicabilidade no Blip

Índice

1. O que é o BSUID
2. Onde encontrar o BSUID no Blip
   1. Metadata das mensagens
      1. Propriedades disponíveis no metadata
      2. Como extrair a informação do metadata
   2. Endpoint de consulta PN > BSUID
      1. Visão geral
      2. Dados retornados no endpoint
      3. Requisição
      4. Resposta
      5. Uso recomendado
      6. Limitações

O que é o BSUID

O BSUID (Business-Scoped User ID) é um identificador criado pela Meta para representar a relação entre um usuário e uma empresa específica no WhatsApp. O mesmo usuário com o mesmo phone number possui BSUIDs distintos para empresas diferentes (sempre representadas pelo Gerenciador de Negócios/Portfólio Empresarial da Meta), ao contrário do phone number, que é global. Ou seja, se o Portfólio Empresarial com o qual um mesmo usuário interage for diferente, o BSUID também será. Exemplo:

O BSUID passa a ser o principal identificador técnico da interação especialmente em cenários sem compartilhamento de telefone.

Onde encontrar o BSUID no Blip

Metadata das mensagens

O BSUID é disponibilizado no metadata das mensagens (mensagens, notificações e ecos, em casos de ativações de Coexistência) e estará presente no objeto metadata de cada envelope (mensagens, notificações ou eco) desde que essas informações sejam enviadas ao Blip pela Meta nos webhooks correspondentes.

Para consultar a informação do BSUID via metadata:

1. Acesse o bot desejado no Portal

2. Acesse o menu superior do Blip

3. Clique no ícone de três pontos (...)

4. Selecione a opção Log no menu

5. Localize o objeto metadata dentro do envelope da mensagem

Propriedades disponíveis no metadata

A disponibilidade dos campos depende das informações recebidas pela Meta. Campos não informados pela Meta nos webhooks não serão preenchidos.
 

Como extrair a informação do metadata

Para extrair essas informações, você deve definir duas ações de saída no bloco Início do Studio:

1. Definir variável de metadata

Defina uma variável com os seguintes parâmetros:

• Nome da variável: metadata

• Valor: {{input.message@metadata}}

2. Executar script

Execute um script para obter apenas o valor do #wa.bsuid presente neste metadata. Configuração do script:

function run(metadata){
metadata= JSON.parse(metadata);
return metadata["#wa.bsuid"];
}

Será apresentado o escopo do script, conforme imagem abaixo:

• DICA! Utilize registro de eventos para engrandecer a captura de dados e torná-los mais apresentáveis a partir de relatórios personalizados.

Endpoint de consulta PN > BSUID

Visão geral

A Blip disponibiliza um endpoint que permite consultar mapeamentos já conhecidos entre número de telefone, BSUID e ID Blip.

Importante!

O endpoint não consulta a Meta em tempo real. Ele retorna apenas dados previamente recebidos e processados pela Blip. Se a Blip ainda não recebeu o BSUID de um determinado PN, o endpoint não o retornará. A ausência de retorno para um número consultado, portanto, não significa erro ou inexistência do contato. Significa apenas que ainda não existe um relacionamento PN ↔ BSUID conhecido e armazenado pela Blip para aquele usuário.

Dados retornados no endpoint

Sempre que informações de identificação forem recebidas pela Meta, o Blip armazena e disponibiliza os seguintes dados através do endpoint de consulta:

Requisição

YOUR_TOKEN é a chave de autorização do seu bot.

PHONE_NUMBERS  deve ser a lista de números a serem buscados. Ela deve estar em sua forma completa (com DDI, DDD e o número), com os itens separados por “;” (ponto e vírgula).

• PONTO DE ATENÇÃO: os números devem ser obrigatoriamente separados por “;” (ponto e vírgula) no caso de haver mais de um, limitando-se ao máximo de 100 itens. Pode haver o sinal de “+” (mais) e o nono dígito (para números do Brasil).

Exemplo: +5531988889999;5531988889999;+553188889999;+553188889999. 
 

{PHONE_NUMBERS} = 5531988889999

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
 
{
    "id":  "{{$guid}}",
    "method": "get",
    "to": "postmaster@wa.gw.msging.net",
    "uri": “/external-contacts-mapping?phoneNumbers={PHONE_NUMBERS}"
}

No caso de requisições em lote:

{PHONE_NUMBERS} = 5531988889999;+553166667777

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
{
    "id":  "{{$guid}}",
    "method": "get",
    "to": "postmaster@wa.gw.msging.net",
    "uri": “/external-contacts-mapping?phoneNumbers={PHONE_NUMBERS}"
}

Observação: certifique-se de separar os números por “;”. 

Resposta

Só serão retornados os números que já foram identificados e mapeados pela plataforma Blip.

• PONTO DE ATENÇÃO: o retorno do Id (ID interno Blip) e do waId (número de telefone do contato) sempre trará os valores sem o sinal “+” e com o nono dígito (em casos de números do Brasil). Exemplo: +553188889999 -> 5531988889999.

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "total": 1,
    "itemType": "application/vnd.iris.whatsapp.contact-mapping-info+json",
    "items": [
      {
        "id": "5531988889999",
        "bsuid": "BR.11815799212886844830",
        "waId": "5531988889999",
        "lastReadDate": "2026-05-13T00:00:00.000Z"
      }
    ]
  }
 }

Uso recomendado

• Mapeamento de base antes do rollout global pela Meta

• Deduplicação de contatos em CRMs integrados

• Enriquecimento de registros e base com BSUID

• Migração gradual de bases de disparo

• Preservação de histórico de atendimento e analytics

⚠️ O endpoint deve ser utilizado principalmente durante o período de transição para enriquecimento gradual das bases existentes. Após a adoção completa do novo modelo de identidade, recomenda-se que novas implementações já considerem IDs independentes de telefone. 

Limitações

• Até 100 números por requisição (controle de TPS)

• O endpoint possui controle de throughput; requisições que ameacem a estabilidade da plataforma poderão ser recusadas e a falha será retornada como o exemplo a seguir

• Recomenda-se implementar retry com backoff em consultas de alta volumetria

{
  "method": "get",
  "status": "failure",
  "reason": {
        "code": 38,
         "description": "Max throughput rate reached on endpoint"
       }
}