> For the complete documentation index, see [llms.txt](https://docs.connectly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.connectly.ai/message-api/business-scoped-user-ids-bsuid.md).

# Business-scoped user IDs (BSUID)

WhatsApp is rolling out **usernames**. When a customer adopts a username, WhatsApp may stop sharing their phone number with businesses. In that case Meta identifies the customer with a **Business-Scoped User ID (BSUID)** instead — a stable, per-business identifier such as `US.13491208655302741918`.

Connectly can surface that BSUID so you don't lose the conversation when a customer goes phone-less.

{% hint style="warning" %}
**This is off by default, and there's no self-serve switch.** Most CRM, billing, and support workflows key on phone number, so Connectly **rejects** phone-less (BSUID-only) customers on each WhatsApp number unless support is explicitly enabled. To turn it on, **contact your Account Manager or Connectly support** — see Enabling BSUID support.
{% endhint %}

### What is a BSUID?

* **Format** — an ISO 3166 alpha-2 country code, a period, then alphanumeric characters: `US.13491208655302741918`.
* **Scoped to your business** — a BSUID only works with WhatsApp numbers your business owns; you can't message another business's BSUID.
* **Can change** — regenerated if the customer changes their phone number.
* **Phone may still be present** — adopting a username doesn't always hide the phone; if you've interacted recently, Meta may still send it alongside the BSUID.

### Enabling BSUID support

Support is configured **per WhatsApp number**, so you can accept phone-less customers on a marketing number while keeping a support number phone-only. There is **no toggle in the inbox or the API** — enablement is handled by Connectly. Contact your Account Manager or Connectly support and tell us which WhatsApp number(s) should accept username-only customers.

While a number is not enabled:

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

### Receiving BSUIDs in webhooks

Once a number is enabled, the customer's identifier in webhook payloads gains `userId` and `phoneNumber`. This applies wherever the customer appears — as `sender` on inbound message webhooks and as `recipient` on delivery-status webhooks.

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

{% hint style="info" %}
These fields are **always present** — empty values are returned as `""` (and `name` as `null`), not omitted. `id` always holds a usable identifier: the BSUID when Meta has shared one, otherwise the phone number.
{% endhint %}

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

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

Store `userId` against your customer record — it's the only stable way to recognize a customer who has hidden their phone number.

### Sending to a customer by BSUID

You can target a customer by BSUID. The field differs per endpoint:

| Endpoint                                  | How to pass a BSUID                                                                                               |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `POST …/send/messages` (session)          | `recipient.userId` = the **bare** BSUID (`US.…`); leave `id`/`phoneNumber` empty (or set `id` to the same BSUID). |
| `POST …/send/whatsapp_templated_messages` | `number` = the **prefixed** form `bsuid:US.…`.                                                                    |
| `POST …/send/campaigns`                   | entry `client` = the **prefixed** form `bsuid:US.…`.                                                              |

{% hint style="warning" %}
**Sending to phone-less (BSUID-only) customers is not available yet** — it depends on a WhatsApp Cloud API capability Meta has not yet released. Until then, send requests that target a BSUID are accepted by the API but fail with `400`:

```json
{
  "type": "ERROR_TYPE_INVALID_ARGUMENT",
  "code": "ERROR_CODE_BAD_REQUEST"
}
```

with a message indicating BSUID delivery is not yet supported. You can build and test your integration now; receiving BSUIDs in webhooks already works.
{% endhint %}

{% hint style="info" %}
**Authentication templates can't use BSUIDs.** One-tap, zero-tap, and copy-code authentication templates require a phone number — a permanent Meta restriction.
{% endhint %}

### Things to know

* **Keep handling phone numbers.** Most customers keep their phone visible; BSUID is additive — you receive both when both are available.
* **BSUIDs can change** on a phone-number change — re-key on the newest `userId`.
* **Portfolio-scoped** — a BSUID only works with WhatsApp numbers your business owns.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.connectly.ai/message-api/business-scoped-user-ids-bsuid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.