Skip to content

Ledger entryNo. 132364

Business-Scoped User ID(BSUID)

Also called: Business scoped user ID · user_id (WhatsApp) · WhatsApp BSUID

Definition
A per-portfolio identifier Meta gives each WhatsApp user, such as IN.1349…, so businesses can recognise and reply to people who hide their number.

Platform & accounts

Mode · json explorer

Work it out

Find the BSUID in a webhook with no phone number

6 / 6
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "919876543210",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Riya",
                  "username": "riya.k"
                },
                "user_id": "IN.8341290712345678901"
              }
            ],
            "messages": [
              {
                "from_user_id": "IN.8341290712345678901",
                "id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYIDQ0QkNENUZD",
                "timestamp": "1776412800",
                "type": "text",
                "text": {
                  "body": "Is my TV still under warranty?"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
An illustrative inbound-message webhook from a user with a WhatsApp username. Step through the fields to see where the BSUID appears and which phone-based fields are missing.

Field 6: entry.0.changes.0.value.messages.0.id — The wamid still identifies the message for deduplication, exactly as before.

What is a business-scoped user ID (BSUID)?

A Business-Scoped User ID (BSUID) is the identifier Meta assigns to each WhatsApp user for a particular business portfolio. It has a two-letter ISO country code, a dot and up to 128 letters and digits, for example US.13491208655302741918. Meta introduced it alongside WhatsApp usernames: once people can chat with a business under a username instead of a phone number, a business needs a way to recognise them that does not depend on the number.

BSUIDs have appeared in Cloud API webhooks since early April 2026. The contacts object carries user_id, inbound messages carry from_user_id and status webhooks carry recipient_user_id. When a user has enabled a username, their phone number is omitted from webhooks unless you and the user messaged or called each other within the last 30 days, or the number is in your contact book. In that case the BSUID is the only identifier you get.

A BSUID is not the WhatsApp ID (wa_id), which is simply the user's phone number in international format and is the same for every business. A BSUID is scoped to one portfolio: the same customer has a different BSUID for each business portfolio, and businesses that link portfolios can opt into a parent BSUID, which includes ENT (as in US.ENT.…). It is also regenerated when the user changes phone number; Meta reports this with a user_id_update webhook, and a system message carrying the previous and new IDs can appear on the messages webhook. And it is not the business username, which is the business's own public handle: the BSUID identifies the customer, never the business.

Key takeaways

  • A BSUID is Meta's identifier for one WhatsApp user within one business portfolio: a country code, a dot, then up to 128 alphanumerics.
  • BSUIDs have appeared in webhooks since early April 2026 as user_id, from_user_id and recipient_user_id.
  • When a user turns on a WhatsApp username, their phone number can be left out of webhooks, leaving the BSUID as the only stable key.
  • The same person has a different BSUID in each business portfolio, and a new one if they change phone number.
  • Meta is adding sending by BSUID through a recipient field; even where it is enabled, authentication templates still need a phone number.

In code

A business-scoped user ID (BSUID) in code

// Called for every value in entry[].changes[] where field === "messages"
export async function upsertContacts(value, db) {
  for (const c of value.contacts ?? []) {
    const bsuid = c.user_id ?? null;          // e.g. "IN.83412907..."
    const phone = c.wa_id ?? null;            // may be missing for username users
    await db.contacts.upsert({
      where: bsuid ? { bsuid } : { phone },
      update: { phone: phone ?? undefined, name: c.profile?.name, username: c.profile?.username },
      create: { bsuid, phone, name: c.profile?.name, username: c.profile?.username },
    });
  }
  for (const m of value.messages ?? []) {
    if (m.type === "system" && m.system?.previous_user_id) {
      // The user's BSUID changed: re-key, don't duplicate.
      await db.contacts.update({
        where: { bsuid: m.system.previous_user_id },
        data: { bsuid: m.system.user_id },
      });
    }
  }
}

Match on BSUID first, fall back to the phone number, and re-key on a system message.

How does a business-scoped user ID (BSUID) work?

  1. Capture every BSUID field

    Read contacts[].user_id, messages[].from_user_id and statuses[].recipient_user_id on every webhook, alongside wa_id and from when they are present. Store the full value, including the country prefix.

  2. Model the customer with two keys

    Give the contact table a nullable phone column and a BSUID column, both indexed. Match inbound messages on BSUID first, then on phone, and link the two when both appear in the same webhook.

  3. Handle ID changes

    Subscribe to user_id_update, and when a messages webhook carries a message of type: "system" with system.type user_changed_user_id or user_changed_number, move the record from system.previous_user_id to system.user_id rather than creating a new contact.

  4. Reply by BSUID when there is no number

    Meta is adding the ability to send by BSUID: a recipient field holds the BSUID instead of to, and if both are present to wins. Check that it is enabled for your account before relying on it, and keep the phone number wherever you have it. Authentication templates (copy-code, one-tap and zero-tap) cannot be sent to a BSUID.

  5. Never share BSUIDs across portfolios

    A BSUID from one portfolio means nothing in another. If your company runs several portfolios, keep the BSUID per portfolio, or use the parent BSUID if you have enabled it.

The figures

A business-scoped user ID (BSUID): key facts and limits

Format
ISO alpha-2 code + "." + up to 128 alphanumerics
Example
US.13491208655302741918
Parent BSUID
Includes ENT, e.g. US.ENT.11815799212886844830
Scope
One business portfolio (parent BSUID spans linked portfolios)
In webhooks since
Early April 2026
Webhook fields
user_id · from_user_id · recipient_user_id
Changes when
The user changes phone number (system message)
Send field (being added)
recipient (to takes precedence if both are set)

Costly mistakes

Common mistakes with a business-scoped user ID (BSUID)

  • Keying everything on phone number

    A NOT NULL phone column will reject or duplicate username users. Make the phone nullable, add a unique BSUID column per portfolio and match on either.

  • Truncating or parsing the ID

    The value can be up to 128 characters after the prefix, and parent BSUIDs add ENT. Store it as an opaque string, in a column wide enough, and never strip the country code.

  • Treating a BSUID as global

    The same person has different BSUIDs in different business portfolios. Copying IDs between portfolios, or between brands of one group, will message nobody or the wrong record.

  • Ignoring the change event

    If you skip system messages, a user who changes number reappears as a stranger. Handle user_changed_number and user_changed_user_id by re-keying the existing contact.

Why does a business-scoped user ID (BSUID) matter?

Almost every WhatsApp integration built before 2026 keys customers by phone number: CRM records, opt-in logs, order lookups, chatbot state. As usernames roll out, some inbound messages arrive with no number at all. Systems that treat the BSUID as a first-class key keep recognising returning customers; systems that do not create duplicate contacts, lose conversation history and cannot match replies to orders.

Example: A returning customer with a username

A Hyderabad electronics store's support bot receives a message from a customer who has turned on a WhatsApp username and has not chatted with the store for two months. The webhook has a profile name, a username and from_user_id IN.83412907…, but no phone number. The bot looks the BSUID up, finds the customer's warranty record (linked in March, when an earlier webhook carried both BSUID and number) and answers with the right order. Without that link it would have opened a new, anonymous ticket.

BSUID FAQs

What is the difference between a BSUID and a wa_id?
A wa_id is the user's phone number and is the same for every business; a BSUID is an ID Meta generates per business portfolio. When a user hides their number behind a username, you may receive only the BSUID.
Does a WhatsApp BSUID ever change?
Yes, when the user changes phone number. Meta sends a user_id_update webhook (and a system message with the previous and new user ID), so you can move the existing contact to its new key.
Can I send a WhatsApp message to a BSUID?
Meta is adding that ability: the BSUID goes in a recipient field instead of to. Confirm it is enabled for your account first; authentication templates are the exception and still need a phone number.
Is the BSUID the same for all my WhatsApp numbers?
Yes, within one business portfolio. All numbers in the same portfolio see the same BSUID for a given user; a different portfolio sees a different one unless you use parent BSUIDs.

Best practices for a business-scoped user ID (BSUID)

  • Backfill now: every webhook that carries both wa_id and user_id is a free chance to link the two keys.
  • Log BSUIDs, not phone numbers, in application logs; they are less sensitive and still let you trace a conversation.
  • Keep OTP flows on phone numbers: authentication templates cannot be sent to a BSUID.
  • Check status webhooks too; recipient_user_id tells you which customer a delivery or read belongs to when the number is absent.

See InfiQ pricing

Put BSUID to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms