BSUID - Contact ID, metadata, endpoints, and applicability in Blip

Index

1. What is BSUID
2. Where to find BSUID in Blip
   1. Message metadata
      1. Available properties in metadata
      2. How to extract information from metadata
   2. PN > BSUID query endpoint
      1. Overview
      2. Data returned by the endpoint
      3. Request
      4. Response
      5. Recommended use
      6. Limitations

What is BSUID

BSUID (Business-Scoped User ID) is an identifier created by Meta to represent the relationship between a user and a specific business on WhatsApp. The same user with the same phone number has distinct BSUIDs for different businesses (always represented by Meta’s Business Manager/Business Portfolio), unlike the phone number, which is global. In other words, if the Business Portfolio with which the same user interacts is different, the BSUID will also be different. Example:

BSUID becomes the main technical identifier of the interaction, especially in scenarios without phone number sharing.

Where to find BSUID in Blip

Message metadata

BSUID is provided in the message metadata (messages, notifications, and echoes, in cases of Coexistence activations) and will be present in the metadata object of each envelope (messages, notifications, or echo) as long as this information is sent to Blip by Meta in the corresponding webhooks.

To check the BSUID information via metadata:

1. Access the desired bot in the Portal

2. Access the top menu in Blip

3. Click the three-dot icon (...)

4. Select the Log option in the menu

5. Locate the metadata object inside the message envelope

Available properties in metadata

The availability of fields depends on the information received from Meta. Fields not provided by Meta in the webhooks will not be filled.
 

How to extract information from metadata

To extract this information, you must define two output actions in the Studio’s Start block:

1. Define metadata variable

Define a variable with the following parameters:

• Variable name: metadata

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

2. Run script

Run a script to get only the value of #wa.bsuid present in this metadata. Script configuration:

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

The script scope will be displayed as shown in the image below:

• TIP! Use event logging to enhance data capture and make it more presentable through custom reports.

PN > BSUID query endpoint

Overview

Blip provides an endpoint that allows querying already known mappings between phone number, BSUID, and Blip ID.

Important!

The endpoint does not query Meta in real time. It only returns data previously received and processed by Blip. If Blip has not yet received the BSUID for a given phone number, the endpoint will not return it. The absence of a return for a queried number therefore does not mean an error or nonexistence of the contact. It only means that there is not yet a known and stored PN ↔ BSUID relationship by Blip for that user.

Data returned by the endpoint

Whenever identification information is received from Meta, Blip stores and provides the following data through the query endpoint:

Request

YOUR_TOKEN is your bot’s authorization key.

PHONE_NUMBERS should be the list of numbers to search for. They must be in their full form (with country code, area code, and number), with items separated by “;” (semicolon).

• NOTE: numbers must be separated by “;” (semicolon) if there is more than one, limited to a maximum of 100 items. The “+” sign and the ninth digit (for Brazilian numbers) may be included.

Example: +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}"
}

For batch requests:

{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}"
}

Note: be sure to separate numbers with “;”. 

Response

Only numbers that have already been identified and mapped by the Blip platform will be returned.

• NOTE: the returned Id (Blip internal ID) and waId (contact’s phone number) values will always be without the “+” sign and with the ninth digit (for Brazilian numbers). Example: +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"
      }
    ]
  }
 }

Recommended use

• Base mapping before Meta’s global rollout

• Deduplication of contacts in integrated CRMs

• Enrichment of records and base with BSUID

• Gradual migration of broadcast bases

• Preservation of service history and analytics

⚠️ The endpoint should be mainly used during the transition period for gradual enrichment of existing bases. After full adoption of the new identity model, it is recommended that new implementations already consider phone-independent IDs. 

Limitations

• Up to 100 numbers per request (TPS control)

• The endpoint has throughput control; requests that threaten platform stability may be rejected, and failure will be returned as in the example below

• It is recommended to implement retry with backoff in high-volume queries

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