📘
March 13, 2026 update :

Starting March 31, 2026, message webhooks will start returning users' actual BSUIDs. To support this change, YCloud has updated its webhook integration documentation. Please refer to the documentation for full details of the updated APIs and webhooks.

We recommend that businesses capture and store users' BSUIDs as soon as they become available, as BSUIDs may be required for future message sending scenarios.

WhatsApp is launching usernames later in 2026.

Usernames are an optional feature for users and businesses. If a username is adopted by a WhatsApp user, their username will be displayed instead of their phone number in the app. Business usernames are not intended for privacy, however. If you adopt a business username, it will not cause your business phone number to be hidden in the app.

To support usernames, Meta will share a new backend user identifier called business-scoped user ID, or BSUID. BSUID uniquely identifies a WhatsApp user and is tied to a specific business.

User usernames

A user username is a unique, optional name that WhatsApp users can set in order to display their username instead of their phone number in the app. Usernames can be used in lieu of profile names when personalizing message content for individual users.

WhatsApp users are limited to 1 username, but are able to change them periodically. Changing a username does not affect the user’s phone number or business-scoped user ID, and does not affect the user’s ability to communicate with other WhatsApp users or businesses on the WhatsApp Business Platform.

Usernames are assigned to the username property in API responses and webhooks payloads. Once enabled, a WhatsApp user’s username will appear in all incoming messages webhooks, and all delivered and read status messages webhooks.

Business-scoped user ID

📘
BSUIDs will begin appearing in webhooks starting March 31, 2026.

A BSUID is a unique user identifier that can be used to message a WhatsApp user when you don’t know their phone number. BSUID will be assigned to the user_id parameter and appear in all messages webhooks, regardless of whether or not the user has enabled the username feature.

BSUIDs are scoped to individual business portfolios. This means that any business phone number owned by a given portfolio can be used to message a BSUID scoped to the same portfolio, and attempts to message the BSUID using a phone number owned by a different portfolio will fail.

BSUIDs will be:

generated automatically
prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code and a period, followed by up to 128 alphanumeric characters (for example, US.13491208655302741918)
unique to each business portfolio-user pair (business portfolios⁠ were formerly known as Business Managers)
regenerated if a user changes their phone number (which trigger a system status messages webhook)

BSUIDs can be used to send any type of message except for one-tap, zero-tap, and copy code authentication templates, which require user phone numbers.

When making API requests with BSUIDs, use the entire BSUID value: country code, period, and all alpha numeric characters. Omitting or changing the country code, period, or alpha numeric characters will cause your request to fail. If you are a managed business with multiple business portfolios, and want to use BSUIDs that will work across all of them, see Parent business-scoped user IDs.

Parent business-scoped user IDs.

If you are a managed business and want to link business portfolios, you can ask your Meta point-of-contact to check if you are eligible. If you are eligible, and your business portfolios become linked, parent BSUIDs will be included in all messages webhooks, assigned to a newparent_user_idproperty.

Parent BSUIDs can be used in place of regular BSUIDS to message users. Functionally, parent BSUIDs have the same properties as regular BSUIDs, but can be used by any business phone number within the set of linked portfolios.

Note that you can still message users using their regular BSUID scoped to your business portfolio.

Phone numbers

If a WhatsApp user enables the username feature, their phone number will not be included in webhooks, unless you have interacted with the user before, as explained below. Therefore, regardless of whether or not the user has enabled the feature, the user’s BSUID will be included in any webhooks that would normally include their phone number, assigned to a new user_id property.

To reduce the chance of losing conversation context with existing users who enable the usernames feature, user phone numbers will be included in webhooks if any of the following conditions are met:

You have messaged or called the user’s phone number within the last 30 days of the webhook being triggered
You have received a message or call from the user’s phone number within the last 30 days of the webhook being triggered
You are in the user’s WhatsApp contacts list
The user is in your contact book

BSUIDs will begin appearing in webhooks starting March 31, 2026. However, our APIs will not support sending messages targeted to the BSUIDs until May 2026 (exact date pending). Once our APIs support BSUIDs in May, you will be able to message users using either their BSUID, phone number, or both.

Meta’s Contact book

In early April 2026, to support messaging thread continuity, Meta’s contact book feature that stores WhatsApp user contact information is being released.

Once the feature is available, if you send a message/call to a user’s phone number, or receive a message/call from a user’s phone number, the user’s phone number and BSUID will be added to your Meta’s contact book. Once this data has been recorded, it will be used to populate any webhook payloads and API responses that include the user’s phone number or BSUID, regardless of whether or not the user has enabled the usernames feature.

Contact book data will be retained until you disable the feature, or deactivate your account. If you wish, you can disable this feature anytime after March 16, 2026, in the Meta** Business Suite** >** Business settings** > Business info⁠ panel. If you disable your Meta’s contact book, it will stop storing user information, and any existing user information it has already stored will be deleted. If you re-enable the contact book later, it will start storing user information again, but previously stored information cannot be restored.

Limitations:

If you are using local storage and a user shares their phone number with you by tapping a request contact information button, the user’s contact information will not be added to your Meta’s contact book. Instead, send a message to the user’s phone number once it has been shared with you. This will cause their phone number and BSUID to be captured by your Meta’s contact book.
Meta’s Contact books are scoped to business portfolios. This means that if you have linked portfolios, a user’s phone number and BSUID would have to be recorded to each portfolio’s Meta’s contact book independently; user contact information is not shared or synced across linked portfolios.

Country codes

If a WhatsApp user enables the username feature, their phone number (and thus, country dialing code) may not appear in webhooks. In these cases, the user’s BSUID will appear instead, prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code (e.g., US.13491208655302741918).

Business usernames

Businesses will also be able to adopt a business username. If you adopt a business username, however, it will not cause your business phone number to be hidden in the WhatsApp or WhatsApp Business client.

A business username is mapped to a single business phone number across all of WhatsApp, i.e. a phone number can have only one username at a given time, and no two WhatsApp phone numbers (consumer or business) can have the same username.

Business usernames must adhere to the following format:

may only contain English letters (a-z), digits (0-9), period (.) and underscore (_) characters
must be between 3-35 characters in length
must contain at least one English letter (a-z, A-Z)
must not start or end with a period or have 2 consecutive periods
must not start with www
must not end with a domain (e.g., .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html, and so on)
case is ignored when comparing usernames, but period and underscore characters are not; for example, myID and myid are the same *username but myid, my.id, and my_id are all distinct

Reserved usernames

Before the username feature is made available, you will have the option to claim a username that WhatsApp has reserved for you. Alternatively, you can adopt a different username that aligns with your branding requirements. A reserved username can be claimed through WhatsApp Manager, Meta Business Suite, or via API. Claimed usernames that are approved will become active once the username feature is made available.

If a reserved username is already in use with your Facebook Page or Instagram account, you must link your business phone number to your Facebook Page or Instagram account before you will be able to claim the username.

You can link your phone number when claiming the username in Meta Business Suite or WhatsApp Manager, or by accessing your Facebook Page or Instagram account and adding your phone number directly⁠.

To link your phone number, you must have full control of the page or account, or basic partial access with the manage_phone permission. See About business portfolio and business asset permissions⁠ for information about control/access and permissions.

Chat window display priority

The following priority will be followed (in decreasing order of priority) for displaying business profile information in chat windows in the app. Your business phone numbers will always appear in your business profile.

Saved contact name
Verified business name or Official Business Account name
Username
hone number