Skip to main content
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 up to 128 alphanumeric characters. Example: US.13491208655302741918. Parent BSUIDs (for businesses enrolled in Meta’s multi-portfolio program) carry an ENT segment: US.ENT.11815799212886844830.
  • 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 appear in the Connectly inbox, but no webhooks are delivered to your endpoints for them — from your integration’s point of view the conversation is invisible.
  • 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. 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:
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

One rule for every endpoint: copy the BSUID exactly as you received it in the webhook, and put it in the userId field. The legacy identifier fields (recipient.id, number, client) also accept a BSUID — bare or bsuid:-prefixed — and take precedence over userId when both are set. No prefix is required anywhere; bsuid: is a legacy form that stays supported for existing integrations. Parent BSUIDs (US.ENT.…) are accepted wherever a BSUID is.
Sending to phone-less (BSUID-only) customers is generally available. A value that looks like a BSUID but isn’t valid (wrong characters, missing country code) is rejected with a 400 and a BSUID-specific error message.
Reply with the same identifier you received. Always use the userId from the webhook. If your business is enrolled in Meta’s parent-BSUID program you also receive parentUserId — pick one of the two and use it consistently for each customer. Each identifier creates its own conversation thread in Connectly, so mixing them splits one customer’s history in two. 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.