BSUID - ID de contatos, metadata, endpoints e aplicabilidade no Blip 1 de junho de 2026 13:31 Atualizado Índice O que é o BSUID Onde encontrar o BSUID no Blip Metadata das mensagens Propriedades disponíveis no metadata Como extrair a informação do metadata Endpoint de consulta PN > BSUID Visão geral Dados retornados no endpoint Requisição Resposta Uso recomendado Limitações O que é o BSUIDO 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 BlipMetadata das mensagensO 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: Acesse o bot desejado no Portal Acesse o menu superior do Blip Clique no ícone de três pontos (...) Selecione a opção Log no menu Localize o objeto metadata dentro do envelope da mensagem Propriedades disponíveis no metadata Propriedade Descrição #wa.bsuid BSUID do usuário #wa.parentId Parent BSUID (quando disponível) #wa.username Username do usuário (quando disponível) 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 metadataPara extrair essas informações, você deve definir duas ações de saída no bloco Início do Studio:1. Definir variável de metadataDefina uma variável com os seguintes parâmetros: Nome da variável: metadata Valor: {{input.message@metadata}} 2. Executar scriptExecute 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 > BSUIDVisão geralA 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 endpointSempre que informações de identificação forem recebidas pela Meta, o Blip armazena e disponibiliza os seguintes dados através do endpoint de consulta: Campo Descrição id Identificador interno do contato na Blip. Pode ser baseado em telefone (5531999999999@wa.gw.msging.net) ou em um GUID (e4b11bdd-a9bf-46ad-a9b0-34116dece5fe@wa.gw.msging.net). bsuid Identificador exclusivo do usuário no contexto de uma empresa específica no WhatsApp. waId Número de telefone do contato quando disponível. parentUserId Identificador de correlação entre Business Accounts elegíveis da mesma organização. lastReadDate Data da interação mais recente do contato registrada pela plataforma. 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} = 5531988889999POST 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;+553166667777POST 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 “;”. RespostaSó 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" } } Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃 Artigos relacionados Ação: Definir variável Evolução da identificação dos contatos no Blip Como analisar possíveis impactos da evolução de IDs do WhatsApp nos fluxos do Builder/Studio