> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Business-Scoped User IDs (BSUID)

> How Connectly surfaces WhatsApp BSUIDs for customers who adopt a username, and how to send messages to them 📥

WhatsApp is rolling out usernames. When a customer adopts one, WhatsApp may stop sharing their phone number with businesses. In that case, Meta identifies the customer with a **Business-Scoped User ID (BSUID)** — a stable, per-business identifier — instead of a phone number. Connectly surfaces BSUIDs in webhooks and lets you use them when sending, so you don't lose the conversation when a customer goes phone-less.

<Note>
  BSUID support is **off by default** and is configured per WhatsApp number. There is no self-serve toggle — contact your Account Manager or Connectly support to enable it for specific numbers. See [Enabling BSUID support](#enabling-bsuid-support).
</Note>

***

## What is a BSUID?

* **Format** — an ISO 3166 alpha-2 country code, a period, then alphanumeric characters. Example: `US.13491208655302741918`.
* **Business-scoped** — a BSUID only works with WhatsApp numbers your business owns. You cannot message another business's customer using their BSUID.
* **Can change** — regenerated if the customer changes their phone number. Always re-key on the newest `userId` value from webhooks.
* **Phone may still be present** — adopting a username doesn't always hide the phone number. If you've interacted with the customer recently, Meta may still send both.

***

## Enabling BSUID support

Support is configured per WhatsApp number, so you can accept phone-less customers on a marketing line while keeping a support line phone-only.

To enable it, contact your Account Manager or Connectly support and specify which WhatsApp number(s) should accept username-only customers.

**While a number is not enabled:**

* Inbound messages from phone-less customers are silently dropped — no inbox conversation, no webhooks, no flows triggered.
* Customers who still have a visible phone number are completely unaffected.

***

## Receiving BSUIDs in webhooks

Once enabled, the customer identifier in webhook payloads gains two new fields — `userId` and `phoneNumber` — alongside the existing `id`. This applies wherever a customer appears: as `sender` on inbound message webhooks and as `recipient` on delivery-status webhooks.

| Customer type              | `id`  | `userId` | `phoneNumber` |
| -------------------------- | ----- | -------- | ------------- |
| Phone-less (username only) | BSUID | BSUID    | `""`          |
| Phone + BSUID              | BSUID | BSUID    | phone         |
| Legacy phone-only          | phone | `""`     | phone         |

All three fields are always present — empty values are returned as `""` (and `name` as `null`), never omitted. The `id` field always holds a usable identifier: the BSUID when Meta has shared one, otherwise the phone number.

**Example — delivery-status webhook for a phone-less customer:**

```json theme={null}
"recipient": {
  "id": "US.13491208655302741918",
  "channelType": "whatsapp",
  "name": "John Snow",
  "userId": "US.13491208655302741918",
  "phoneNumber": ""
}
```

<Tip>
  Store the `userId` value against your customer record. It's the only stable identifier for customers who have hidden their phone number.
</Tip>

***

## Sending messages to a BSUID

The field you use to pass a BSUID differs between endpoints:

| Endpoint                                  | How to pass the BSUID                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------- |
| `POST …/send/messages` (session message)  | Set `recipient.userId` to the bare BSUID (e.g. `US.13491208655302741918`).             |
| `POST …/send/whatsapp_templated_messages` | Set `number` to the prefixed form `bsuid:US.…` (e.g. `bsuid:US.13491208655302741918`). |
| `POST …/send/campaigns`                   | Set the entry's `client` field to the prefixed form `bsuid:US.…`.                      |

<Warning>
  Sending to phone-less (BSUID-only) customers is **not yet available**. It depends on a WhatsApp Cloud API capability Meta has not yet released. Until then, send requests targeting a BSUID are accepted by the API but fail with a `400` error. You can build and test your BSUID integration now — receiving BSUIDs in webhooks already works.
</Warning>

**Authentication templates cannot use BSUIDs.** One-tap, zero-tap, and copy-code authentication templates require a phone number. This is a permanent restriction from Meta.

***

## Things to keep in mind

* **Keep handling phone numbers.** Most customers keep their phone number visible. BSUIDs are additive — when both are available, you receive both.
* **BSUIDs can change** when a customer changes their phone number. Always re-key your records on the newest `userId` from webhooks.
* **BSUIDs are portfolio-scoped** — they only work with WhatsApp numbers your business owns.