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.
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.
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 |
"" (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:
"recipient": {
"id": "US.13491208655302741918",
"channelType": "whatsapp",
"name": "John Snow",
"userId": "US.13491208655302741918",
"phoneNumber": ""
}
Store the userId value against your customer record. It’s the only stable identifier for customers who have hidden their phone number.
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.…. |
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.
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.
