Understanding WhatsApp Usernames and Business-Scoped User IDs (BSUIDs) – Required Actions and Changes

Overview

Meta is introducing WhatsApp usernames in 2026, allowing WhatsApp users to display their username instead of their phone number for enhanced privacy. To support this transition and ensure uninterrupted business messaging, Meta will automatically generate a unique identifier for every user-business pair called Business-Scoped User ID (BSUID). This enables you to continue messaging users who have adopted usernames.

Vonage will support this identifier with a new field user_id under the WhatsApp object in the Messages API for both incoming message and message status webhooks.

Important: This change will impact how you receive and process WhatsApp webhooks. If your systems are not updated to handle BSUIDs, you may lose the ability to receive messages from users who adopt usernames.

Applies To

• Messages API
• WhatsApp Business Platform
• Direct customers
• Partners

What's Changing?

Meta is introducing usernames as an optional feature for both WhatsApp users and businesses.

WhatsApp Usernames Explained

For WhatsApp Users (It is a privacy Feature):

• Users can choose to display a username instead of their phone number
• Once enabled, their phone number will not be shared with businesses by default
• This gives users control over their privacy when messaging businesses

For Businesses (It is a Brand Presence):

• Businesses can also adopt usernames for better brand visibility
• Business phone numbers will still be visible even after adopting a username
• This feature is for branding, not privacy

Important: For WABA (WhatsApp Business Account) onboarding and registration, you must continue using phone numbers. Business usernames only affect the business’s name displayed on WhatsApp and are not used during onboarding or phone number registration.

Businesses cannot send messages 

What Is a BSUID?

A Business-Scoped User ID (BSUID) is a unique identifier (up to 128 alphanumeric characters) that Meta generates for each user-business pair. You can use BSUIDs to message WhatsApp users when their phone numbers are not available.

Key characteristics:

• Generated automatically by Meta
• Unique to each business portfolio - specific WhatsApp user pair
• BSUIDs are scoped to individual business portfolios, meaning only business phone numbers within the same portfolio can message a given BSUID. Attempts to send messages using a phone number from a different portfolio will fail.

• The BSUID is included in the message metadata payload in two scenarios:

  • When a user messages your business (inbound message webhook)

  • When you receive a delivery status webhook event 

• Regenerated if a user changes their phone number

Critical Changes to Your Webhooks

Timeline:

When You'll Stop Receiving Phone Numbers

If a WhatsApp user adopts a username, their phone number will NOT be included in your webhooks, unless one of these conditions is met:

1. You've messaged or called their phone number in the last 30 days
2. You've received a message or call from their phone number in the last 30 days
3. The user is in your contact book (Meta feature) (enabled by default on your Meta Business Portfolio)

Important: These conditions are evaluated per business phone number. If you message a user from phone number A, webhooks from phone number B won't include the user's phone number unless phone number B has also interacted with that user within 30 days. Also, messaging cannot be initiated based on just the username. They must have either the user's phone number or BSUID to send messages.

What You'll Always Receive

Regardless of whether a user has adopted a username, you'll always receive their BSUID in webhooks. The BSUID will appear in a new user_id field alongside the existing phone number field.

New Vonage Webhook Fields

Please see this KB article for changes to webhooks: Webhook Changes for WhatsApp Usernames 

Required Actions

To ensure uninterrupted service, you must:

1. Update Your Webhook Integration (By the end of May 2026)

• Add support for the new user_id field containing BSUIDs
• Handle cases where wa_id (phone number) may be an empty string
• Support up to 128-character alphanumeric identifiers 

2. Update Your Systems (By May 2026)(TBC)

Note: The actions below are applicable depending on your specific use case. Please review each item and implement only what is relevant to your integration.

• Update your CRM/database to store BSUIDs alongside user phone numbers
• Build logic to handle both user phone numbers and BSUIDs as identifiers, including when a phone number is not available.
• Map BSUIDs to existing customer records to maintain conversation history
• Update your API calls to support sending messages to BSUIDs once available (where applicable)

3. Update Your User Flows (By May 2026)(TBC)

Note: The actions below are applicable depending on your specific use case. Please review each item and implement only what is relevant to your integration.

• Review messaging bots and journeys to handle scenarios where users don't share phone numbers and instead share BSUIDs
• Add prompts to request phone numbers if required for your use case (see Meta page)
• Handle responses when users choose not to share their phone number

Note: We recommend starting your implementation planning as soon as possible to ensure a smooth transition.

What Stays the Same

If You Have the User's Phone Number

• Business-initiated messaging continues working normally
• Authentication templates continue working normally

Risk of Not Updating Your Systems

If you do not implement BSUID support, you risk losing:

• Messages from username adopters via click-to-WhatsApp ads
• User-initiated service messages from username adopters
• New inbound messages from users with phone number privacy enabled

BSUID Limitations

BSUIDs cannot be used for Authentication templates, and these templates require user phone numbers.

How Your Business Name Appears in WhatsApp

Business Profile Display: Your business phone numbers will always appear in your business profile, regardless of whether you adopt a username.

Display Priority in Users' Chat Window:

When users see your messages in their WhatsApp chat window, WhatsApp displays your business name in the following priority order (highest to lowest):

1. Saved contact name (if the user has saved your number)
2. Verified business name or Official Business Account (OBA) name
3. Username (if you've adopted one)
4. Phone number (default fallback)

Frequently Asked Questions

Q: Why won't I receive phone numbers anymore? 

A: Users who adopt usernames can hide their phone numbers for privacy. You'll receive a BSUID instead, which uniquely identifies that user to your business.

Q: Will I lose conversation history with existing customers? 

A: No. If you've interacted with the user within the last 30 days, or they're in your contact book, you'll still receive their phone number along with the BSUID.

Q: Do BSUIDs replace phone numbers entirely?

A: No. Usernames and BSUIDs are an additional privacy layer. Phone numbers remain the underlying account identifier.

Q: Can I message users if I only have their BSUID? 

A: Yes, once API support is available in May 2026. You'll be able to message users using their BSUID, phone number, or both.

Q: How long is a BSUID? 

A: BSUID is prefixed with the user's 2-letter ISO country code, a period, and up to 128 alphanumeric characters (e.g., US.13491208655302741918).

Q: Are BSUIDs scoped to a specific business portfolio?

A: Yes. BSUIDs are scoped to individual business portfolios. Only business phone numbers owned by the same portfolio can be used to message a given BSUID. Any attempt to message a BSUID using a phone number from a different portfolio will fail.

Q: Can I use BSUIDs across different business portfolios? 

A: No. BSUIDs are unique to each business portfolio-user pair. A BSUID from one portfolio cannot be used to message from a different portfolio. Alternatively, as a business with multiple portfolios, you can use parent_BSUID (see Meta page).

Q: What if phone numbers are missing in my webhooks? 

A: First, check if you've messaged or received messages from that user in the last 30 days. If not, and they're not in your contact book(refer to the Metas Contact Book feature), you'll only receive the BSUID, which you can use to continue messaging once API support is available. 

Q. How do I find out the BSUID of the user?

A: Businesses can find the BSUID when a user messages your business (inbound message webhook) or when you receive a delivery status webhook event 

Additional Information

For more information, please refer to the Meta Documentation