Business-scoped user IDs (BSUID)
How Connectly surfaces WhatsApp Business-Scoped User IDs (BSUIDs) for customers who adopt a WhatsApp username, and how to enable support.
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.
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.
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
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.
Example delivery-status webhook for a phone-less customer:
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:
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.….
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:
with a message indicating BSUID delivery is not yet supported. You can build and test your integration now; receiving BSUIDs in webhooks already works.
Authentication templates can't use BSUIDs. One-tap, zero-tap, and copy-code authentication templates require a phone number — a permanent Meta restriction.
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.
Last updated