# Business-scoped user IDs

A **business-scoped user ID** (BSUID) is Meta's identifier for a WhatsApp user, scoped to one business portfolio. It arrives on inbound messages whether or not the contact uses a WhatsApp username, and it addresses a contact whose phone number you do not have.

Bird surfaces it as `bsuid` on a message's `from` and `to`, accepts it as the `to` of a send, and filters the message list by it. Meta's [business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) reference is the source for the rollout itself and for what other Meta surfaces do with the identifier.

## Why a contact arrives without a phone number

WhatsApp is rolling out usernames. A user who adopts one shows their username instead of their phone number in the app, and Meta then withholds the number from the payloads a business receives. The BSUID is the identity that is always there, which is why an inbound message can carry one and no `phone_number` at all.

Meta still includes the phone number when you already have a relationship with the contact: when that specific business phone number has messaged or called them, or received a message or call from them, in the last 30 days, or when they are in your Meta contact book. The 30-day condition is evaluated per business phone number, so a contact who wrote to one of your numbers can still arrive without a phone number on another.

A message from a WhatsApp user also carries the profile they publish, in `username` and `display_name` on `from`. Both are absent when the contact has not adopted a username or the message carries no profile, and neither can be used to address a message.

## What a BSUID looks like

```json
{
  "from": {
    "bsuid": "US.13491208655302741918",
    "username": "alexr",
    "display_name": "Alex Rivera"
  }
}
```

An ISO 3166 alpha-2 country code, a period, then up to 128 alphanumeric characters. A **parent BSUID**, which a managed business can be enrolled for so one identifier works across a set of portfolios, inserts `ENT` after the country: `US.ENT.11815799212886844830`. Bird accepts both forms as a recipient.

Three properties decide how you store and use one:

- **Pass the whole value, unchanged.** Meta rejects a modified BSUID, so no part of it is optional: the country code, the period, and every character of the identifier travel together. Bird validates the shape before accepting a send, and the country code has to be uppercase and a real ISO 3166 alpha-2 code; a lowercase or unknown prefix is refused rather than corrected. The 128-character bound applies to the identifier after the country code, and after the `ENT.` segment on a parent BSUID.
- **It is scoped to a business portfolio.** Any business phone number in the same portfolio can message that BSUID; a number in a different portfolio cannot, and the send fails.
- **It is not permanent.** Meta documents that a contact's BSUID is regenerated when they change their phone number, so it identifies a conversation partner rather than serving as a durable customer key of your own.

## How a conversation usually goes

A contact you have not spoken to before reaches you by BSUID, and the exchange that gets you their number runs in three steps:

1. **The contact messages you.** The inbound message carries `from.bsuid`, and `from.phone_number` may be absent. That message opens the [customer service window](/docs/knowledge-base/whatsapp/customer-service-window), so you can reply free-form for the next 24 hours.
2. **You ask for the number.** Send a [contact info request](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), a single button that asks the contact to share the number their WhatsApp account uses. The same ask rides on a template through its `request_contact_info` button, which reaches a contact whose window has closed.
3. **The contact taps the button.** Their number arrives as an inbound [contact card](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) with `origin` set to `contact_request` and the number in `phone_numbers`. From then on the relationship satisfies Meta's own condition, so the contact's phone number is populated on the messages that follow as well.

A contact can decline. Dismissing the share sheet produces no message and no webhook, so a flow that needs a number has to time out on its own rather than wait for a decline to arrive, and it has to keep working for a contact who never shares one.

## Sending to a BSUID

`to` takes a BSUID wherever it takes a phone number:

```json
{
  "to": "US.13491208655302741918",
  "from": "+13124495648",
  "text": { "body": "Your order shipped." }
}
```

Four things differ from a send addressed by phone number:

- **`from` has to sit in the portfolio the BSUID is scoped to.** That is the same portfolio requirement Meta applies, and a mismatch fails at WhatsApp rather than at accept.
- **One-time-passcode templates need a phone number.** A Bird-managed template in the `authentication` category, or one carrying a one-time-passcode button, is refused at accept with a `422` [`E15014`](/docs/api/errors/E15014) `WhatsAppRecipientNotSupportedForTemplate`. A template your workspace authored is not checked at accept: Meta requires a phone number for one-tap, zero-tap, and copy-code authentication templates, so such a send is accepted and then fails.
- **A value that is neither a phone number nor a well-formed BSUID is refused at accept**, with a `422` [`E15001`](/docs/api/errors/E15001) `WhatsAppInvalidRecipient`.
- **Price is keyed on the BSUID's country prefix.** A phone number supplies the country a message is priced against, and for a BSUID send the two-letter prefix supplies it instead.

Everything else about the send is unchanged: the [customer service window](/docs/guides/whatsapp/message-types#the-customer-service-window) still gates free-form content, and the `202` still means accepted rather than delivered.

**Address a contact on the identity they wrote to you with.** Bird records an open window under each identity the inbound message carried, and a send finds the window under the identity it is addressed to. A contact who reached you by BSUID alone leaves no phone-keyed window behind, so a free-form send to a phone number you hold from elsewhere can be refused with a `422` [`E15044`](/docs/api/errors/E15044) `WhatsAppServiceWindowClosed` while Meta still considers the conversation open. Replying to the `from` of their message avoids the mismatch.

## Reading and filtering by BSUID

Every read carries whatever identities the message holds:

- **On a message**, `from` and `to` each carry a `phone_number`, a `bsuid`, or both. An inbound message names the contact on `from`; an outbound one names them on `to`.
- **On a webhook**, the same addresses ride on the event payload. See [WhatsApp events](/docs/guides/whatsapp/events#the-event-envelope) for the envelope.
- **On the message list**, `to` and `from` each accept a BSUID as well as a phone number, and each matches one end of the message. The `bsuid` filter matches the contact in either direction. The older `phone_number` filter is deprecated: `to` and `from` replace it and match both kinds of identity.

Store both identities against your own contact record, and key the record on your own identifier rather than on either of Meta's. A contact can arrive with a BSUID only, gain a phone number once they share it, and get a new BSUID if they change numbers.

## Next steps

- [Receiving contact cards](/docs/guides/whatsapp/receiving-whatsapp/contact-cards): the arm the shared number arrives on
- [WhatsApp contact info requests](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): the button that asks for it
- [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp): the request envelope, the `202` model, and safe retries
- [Meta's business-scoped user IDs reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids): the rollout, parent BSUIDs, and the rest of Meta's surfaces