Understanding WhatsApp Usernames and BSUIDs

What Are WhatsApp Usernames?

A WhatsApp username is an optional, unique identifier that either of the following can set to display instead of a phone number in the app: a WhatsApp user (logged in to the WhatsApp Consumer App) or a business (logged in to the WhatsApp Business App or WhatsApp Business API Platform). Usernames work similarly to handles on Facebook Messenger or Instagram.

There are two distinct actors and use cases:

Usernames are a layer on top of phone numbers, not a replacement. Every WhatsApp account still requires a phone number.

What Is a BSUID?

A business-scoped user ID (BSUID) is a unique identifier assigned by Meta to each WhatsApp user, specifically tied to a particular business portfolio. It is the primary way to identify and message a user when their phone number is not available.

Key properties of a BSUID:

• Format: ISO 3166 alpha-2 country code prefix, followed by a period and up to 128 alphanumeric characters — for example, US.13491208655302741918
• Scope: Unique per business portfolio–user pair. A BSUID from one portfolio cannot be used with a phone number owned by a different portfolio.
• Availability: Always present for WhatsApp users (consumers). Not always available for businesses unless adopted. Additionally, regardless of the username or BSUID, the phone numbers of businesses are always available.
• Regeneration: A BSUID is regenerated if the user changes their phone number.
• Limitations: BSUIDs cannot be used to send one-tap, zero-tap, or copy code authentication templates. Those message types require a phone number.

What Is a Parent BSUID?

A parent BSUID is a special variant of a BSUID available to managed businesses with multiple linked Meta business portfolios. It allows a single identifier to be used across all enrolled portfolios.

• Format: {COUNTRY_CODE}.ENT.{ALPHANUMERIC_ID} — for example, US.ENT.11815799212886844830
• Availability: Only for businesses enrolled in a parent BSUID account by Meta. Contact your Meta or Vonage point-of-contact to check eligibility.
• Scope: Works across all enrolled portfolios. Regular BSUIDs still work alongside parent BSUIDs.

When Will You Receive a BSUID vs. a Phone Number?

The table below summarises what identifiers are visible to Vonage depending on the user type:

When Is a Phone Number Still Included for Username-Adopting Users?

Meta includes the user's phone number in webhooks if any of the following conditions are met (evaluated per business phone number):

• You have messaged or called the user's phone number within the last 30 days
• You have received a message or call from the user's phone number within the last 30 days
• The user is in your contact book

If none of these conditions are met, the wa_id field will be omitted from the webhook payload. The from field will contain the BSUID instead of the phone number.

The Contact Book

Meta provides a contact book feature (available from early April 2026) that automatically stores a user's phone number and BSUID whenever you send or receive a message or call to or from their phone number. Once stored, the phone number will continue to appear in webhook payloads regardless of whether the user has adopted a username.

The contact book is scoped to the business portfolio level and is hosted by Meta. No integration work is required to enable it, as it is enabled by default by Meta. You can disable it at any time in Meta Business Suite > Business settings > Business info.

New Error Code

A new error code is returned when you attempt to send a message type that does not support BSUIDs as recipients:

Further Information

Handling WhatsApp Usernames and BSUIDs