Usernames and business-scoped user IDs [#usernames-and-bsuid]

WhatsApp is introducing usernames as an optional privacy feature for end users. When a user adopts a username, their phone number may no longer appear in your webhook payloads. Businesses can also adopt usernames. To reserve a username for your business phone number, see Business usernames.

If you already have a user's phone number (for example, collected through forms, email, prior conversations, or any other means), you can continue sending outbound messages to that number as before. This change only affects inbound webhooks when a user who has adopted a username contacts you without a prior phone-based interaction. Authentication templates (one-tap, zero-tap, and copy code) are not affected and continue to require a phone number.

To ensure uninterrupted messaging, Meta is simultaneously rolling out business-scoped user IDs (BSUIDs). These are stable, anonymous identifiers that let you reach and recognize users even without their phone number.

These are two separate changes:

Meta is rolling out username support gradually across regions. The timeline is managed by Meta and subject to change.

What is a BSUID [#what-is-a-bsuid]

A business-scoped user ID (BSUID) is a unique, stable identifier for a WhatsApp user within your business portfolio.

• Format: ISO 3166 alpha-2 country code + period + up to 128 alphanumeric characters. Example: US.13491208655302741918. To distinguish a BSUID from a phone number, check whether the value starts with two letters followed by a period.
• Scope: Unique per business portfolio. The same user has a different BSUID with each business they interact with.
• Stability: Stays the same unless the user changes their phone number. In that case, Meta generates a new BSUID and sends a user_id_update webhook with the old and new values so you can update your records.
• Not the same as identity changes: Identity changes occur when a user reinstalls WhatsApp or changes devices while keeping the same phone number. A BSUID update occurs when a user changes their phone number entirely.
• Always present: Every inbound webhook includes a BSUID in contact.userId, regardless of whether the user has a username.

BSUIDs start appearing in your webhooks automatically. No configuration is required on your side.

Parent BSUIDs [#parent-bsuids-what-is-a-bsuid]

Most businesses do not need parent BSUIDs. They are available only to businesses that manage multiple linked portfolios and have submitted a request to Meta and received explicit approval. A parent BSUID works across all linked portfolios and appears in contact.parentUserId. It is useful when the same user interacts with multiple phone numbers you own and you want a single identifier across all of them.

If your business operates a single portfolio, this field does not apply.

What are usernames [#what-are-usernames]

Any WhatsApp user can set an optional username that appears in the app instead of their phone number when messaging businesses. Once a user adopts a username, their phone number may be hidden from businesses they have not interacted with recently.

Usernames are entirely optional. Users who do not adopt one are unaffected. Their phone number continues to appear in your webhooks exactly as before.

Business usernames [#business-usernames-what-are-usernames]

Businesses can also adopt a username. A business username maps to a single business phone number across all of WhatsApp. One phone number can have only one username at a time, and no two WhatsApp phone numbers (consumer or business) can share the same username.

Business usernames must follow these format rules:

• Must only contain English letters (a-z), digits (0-9), period (.), and underscore (_) characters.
• Non-English characters (such as ñ, é, ü) do not work and cause the request to fail.
• Must be between 3 and 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 two consecutive periods.
• Must not start with www.
• Must not end with a domain (for example, .com, .org, .net, .edu, .gov).
• WhatsApp ignores case when comparing usernames, but not period and underscore characters. For example, myID and myid are the same username, but myid, my.id, and my_id are all distinct.

Businesses can reserve and claim their preferred username in WhatsApp Manager or Meta Business Suite. Reserved usernames remain linked to the business account and become active once the feature launches in their region. Usernames are first-come, first-served, so reserve early to secure your preferred handle. In most cases, you can claim the same username as your Facebook or Instagram account.

Usernames are unique to a phone number. If your business has multiple phone numbers, each one needs a different username (you can use the same display name across all of them).

You can change or delete a username at any time. After changing or deleting, the old username is held for 60 days so you can reclaim it.

For step-by-step instructions on reserving, changing, and deleting a business username, see the WhatsApp How to reserve and manage usernames article.

WhatsApp displays business profile information in chat windows in the following order (highest priority first):

1. Saved contact name
2. Verified business name or Official Business Account name
3. Username
4. Phone number

Your business phone numbers always appear in your business profile.

Phone number visibility [#phone-number-visibility]

When a user's phone number is available, your webhook payloads include both the phone number and the BSUID. When the phone number is unavailable, you receive the BSUID only.

A user's phone number is included in your webhook payloads if any of the following is true:

• You messaged or called their phone number within the last 30 days.
• You received a message or call from their phone number within the last 30 days.
• The user is in your Contact Book.

If none of these apply and the user has adopted a username, you receive their BSUID instead of their phone number.

Two mechanisms determine whether a phone number is included:

• 30-day window (per business phone number): The 30-day lookback is evaluated per business phone number. If you message a user from one business phone number, webhooks for a different business phone number in your portfolio do not automatically include that user's phone number. The phone number appears there only if that other number has also interacted with the user within the last 30 days.
• Contact Book (per business portfolio): Contact Book automatically stores phone number and BSUID pairs whenever any business phone number in your portfolio interacts with a user. It is on by default and requires no setup. Once a pair is stored, the phone number is always included in webhooks from all phone numbers in your portfolio, even if the user later adopts a username. Contact Book only captures interactions that occur after early April 2026. It does not store historical data.

If you lose a user's phone number after they adopt a username, it is not permanent. Any interaction from a specific business phone number (outbound campaign, inbound reply) restores visibility on that number's webhooks and adds the user to the Contact Book for portfolio-wide visibility. You can also request the phone number directly in conversation using the REQUEST_CONTACT_INFO button described in Request a phone number from username users.

To maximize phone number visibility, send outbound messages to your contact list on a regular schedule. Any outbound message to a phone number resets the 30-day window and populates the Contact Book, keeping phone numbers visible even after users adopt usernames.

API payload changes [#api-payload-changes]

All changes are additive. No fields are removed from current payloads.

Inbound message webhook (MO) [#inbound-message-webhook-api-payload-changes]

Infobip delivers this to your webhook URL when a user sends you a message.

Phone number available

Phone number unavailable

When a phone number is unavailable, from and contact.userId carry the same BSUID value. contact.userId is the more reliable field to read. It always carries the BSUID regardless of whether the phone is present. For a full list of fields across all API surfaces, see the summary table.

Outbound message request (MT) [#outbound-message-request-api-payload-changes]

Send to a phone number

Send to a BSUID

The to field accepts either a phone number or a BSUID. The maximum field length is 150 characters. You do not need to make other changes to the request format.

Outbound campaigns sent to phone numbers work the same as before. You continue to send to phone numbers and receive phone numbers in the corresponding delivery report webhooks.

Delivery report webhook (DLR) [#delivery-report-webhook-api-payload-changes]

Infobip delivers this to your DLR webhook when a message status changes.

Example payload

The contact object follows the same structure as in the inbound webhook. It is included for sent, delivered, and read status events only. It is not included in failed delivery reports. The identifiers included in the DLR depend on how you sent the original message:

• Sent to a phone number: The DLR includes both the phone number and the BSUID.
• Sent to a BSUID, phone number known: The DLR includes both the phone number and the BSUID.
• Sent to a BSUID, phone number unknown: The DLR includes the BSUID only.

Seen report webhook [#seen-report-webhook-api-payload-changes]

Infobip delivers this to your webhook when a user views a message you sent.

Example payload

The contact object follows the same structure as in the inbound and delivery report webhooks. The identifiers included depend on how you sent the original message, using the same rules described in Delivery report webhook (DLR).

Summary of all field changes [#field-changes-summary-api-payload-changes]

The following table lists every field affected by usernames and BSUIDs across all API surfaces:

Request a phone number from username users [#request-phone-number]

If a user has adopted a username and their phone number is unavailable to you, WhatsApp provides a way to request it directly in the conversation thread.

You can add a new button type, REQUEST_CONTACT_INFO, to utility and marketing templates. When the user taps it, they share their virtual contact card (including phone number) in the message thread, and WhatsApp triggers a contacts webhook containing the number.

The following shows a template creation payload with a REQUEST_CONTACT_INFO button. No parameters are required for the button itself, as WhatsApp sets the label and does not support customization.

When the user taps the button, WhatsApp delivers a contacts webhook containing the user's phone number. Read the phone number from this webhook, store it in your CRM, and use it in subsequent outbound messages to maintain phone number visibility going forward.

For the full webhook payload structure, see the Inbound messages API reference.

Integration requirements [#integration-requirements]

To support usernames and BSUIDs, update your integration as follows:

1. Parse webhooks for BSUIDs.
   • Treat from as either a phone number or a BSUID. Read contact.userId for every inbound message.
2. Store the BSUID.
   • Add a userId field to your customer records and use it as the stable WhatsApp identifier alongside the phone number.
3. Handle user_id_update events.
   • When a user changes their phone number, Meta sends this event with the old and new User IDs. Update your records accordingly.
4. Send to BSUIDs when needed.
   • When replying to a username-only user, use their userId in the to field.
5. Account for authentication limitations.
   • One-tap, zero-tap, and copy code authentication templates require a phone number and cannot use a BSUID. Ensure users likely to need OTP have a phone number on file.

Rollout timeline [#timeline]

BSUIDs, identity fields (contact.userId, contact.username, contact.parentUserId), Contact Book, and the REQUEST_CONTACT_INFO template button are already available.

Username adoption is rolling out gradually across regions. The rollout timeline is managed by Meta and subject to change.

For more details, see the Business-scoped user IDs documentation from Meta.

Support [#support]

For API integration questions or to report abuse related to usernames or BSUIDs, contact Infobip support.