WhatsApp Business-Scoped User ID (BSUID) integration guide
Meta is introducing usernames to WhatsApp. When a user enables a username, their phone number no longer appears in Webhooks by default, which breaks integrations that rely on phone numbers for user identification and message routing. This guide describes the Business-Scoped User ID (BSUID), a new user identifier that you must support to maintain reliable communication with all WhatsApp users.
Why BSUID is needed
Meta is adding the Username feature to WhatsApp. Once a user enables a username, it replaces their phone number in the app display, and the phone number no longer appears by default in Webhooks sent to businesses. If a user has not enabled the Username feature, Webhooks continue to include the user's phone number.
To ensure businesses can still identify users and send or receive messages after a user enables a username, Meta introduced a new identifier — the Business-Scoped User ID (BSUID).
The BSUID feature will be rolled out in phases by Meta, with a planned global release in September 2026. Before full rollout, you may not encounter cases where the phone number is empty. The official timeline is subject to Meta's announcement.
For the Webhook-related sections, non-API customers do not need to take action.
What is a BSUID
A BSUID is a unique identifier that WhatsApp automatically generates for each user and associates with your Business Manager (BM). Regardless of whether a user enables the Username feature, the BSUID appears in all message Webhooks.
The BSUID format consists of a two-letter country code followed by a period and an alphanumeric string:
US.13491208655302741918
A BSUID has the following characteristics:
Automatic generation — Meta's system generates BSUIDs automatically. No manual application is required.
BM-level binding — Regardless of how many WABAs or business phone numbers you have under the same BM, you receive the same BSUID for the same user. Any of your phone numbers can use that BSUID to send messages to the user.
Cross-BM isolation — Even for the same user, different BMs receive different BSUIDs. BSUIDs cannot be used interchangeably between BMs.
Stability — A BSUID is only regenerated when the user changes their phone number. The update is communicated via a
user_id_updateWebhook containing the mapping between the old and new BSUIDs. Enabling or disabling the Username feature, or changing the username, does not affect the BSUID.
How to use a BSUID
A BSUID has two primary uses: identifying users and sending messages.
Identifying users
In your current integration, you may use the phone number as the unique identifier for users. With the introduction of BSUID, store the BSUID as the primary user identifier in your system and associate it with phone numbers, conversation history, user tags, and other data.
Starting July 15, 2026, all message Webhooks include a UserId field (in message status events) or a FromUserId field (in inbound messages), whose value is the user's BSUID. You can start reading and storing this field now to prepare for future integration.
Sending messages
Starting July 15, 2026, you can send messages directly to users using their BSUID, without needing their phone number. This is especially important for scenarios where a user has enabled the Username feature and their phone number is no longer visible. Existing flows that send messages to end users using phone numbers are not affected — you can still send messages directly using the user's phone number.
Phone numbers and BSUIDs can be used simultaneously or independently. When both are provided, the phone number takes precedence.
Authentication templates (one-tap, zero-tap, copy code) do not support BSUID. You must use a phone number.
Parent BSUID
The Parent BSUID enables enterprises to identify the same user across multiple BMs. Because BSUIDs are isolated between BMs, you cannot identify or contact the same user across BMs using standard BSUIDs. To unify user identification and communication across BMs, contact Alibaba Cloud to apply to Meta for access to the Parent BSUID feature.
Once access is granted, any business phone number under any of your BMs can use the same Parent BSUID to send messages to the same user, without maintaining separate BSUIDs for each BM.
The Parent BSUID format includes the ENT identifier:
US.ENT.11815799212886844830
Once enabled, Webhooks include both the BM-level BSUID and the Parent BSUID. Parent BSUID requires a separate application to enable.
Required changes
The following changes are mandatory. Failure to complete them directly impacts communication with your users.
Inbound message handling
When a user enables the Username feature, the following cases no longer include the user's phone number:
Entirely new users who have never had any interaction with your business phone number.
Users who do not meet the phone number visibility conditions. For details, see Phone number visibility rules.
Messages from these users contain only a BSUID in the Webhook — no phone number. If a user has not enabled the Username feature, their phone number is still included.
If your system relies on phone numbers to identify users or establish sessions, it will be unable to process these messages or reply to these users. As more users enable the Username feature, the number of unprocessable messages will grow.
You must make the following changes:
In your Webhook parsing logic, the user identifier field (
from) may be either a phone number or a BSUID.Read and store the
FromUserIdfield (BSUID) and use it as the primary identifier for users.Conversations, records, tags, and other user-related data in your enterprise system must support association and querying by BSUID.
Enterprises must store the mapping between phone numbers and BSUIDs themselves — Chat App Message Service does not handle this.
Outbound message sending
When a user enables the Username feature and sends you a message for the first time, or when the user does not meet the phone number visibility conditions, you can only obtain the user's BSUID. For details on when phone numbers are available, see Phone number visibility rules.
If your sending interface only supports phone numbers, you will be unable to send messages to users whose phone numbers are unavailable. As adoption of the Username feature grows, your system's message delivery rate will decline.
If your business only involves proactively sending messages to end users using phone numbers and does not reply to inbound user messages, you do not need to address BSUID immediately. However, adding BSUID compatibility is still recommended to handle inbound messages from new users or users whose phone numbers are unavailable.
The Chat App Message Service ability to send messages using BSUID is available starting July 15, 2026.
You must make the following changes:
When sending messages, support using a BSUID as the target identifier.
User identifiers stored in your enterprise system must include the BSUID, so it is available when phone numbers are not.
If your code assumes the from field is always a phone number, receiving a BSUID may trigger program exceptions, affecting overall system stability. Additionally, if your system cannot associate historical records using BSUIDs, customer information will become fragmented when existing users enable the Username feature.
Phone number visibility rules
When a user enables the Username feature, their phone number no longer appears in Webhooks by default. However, the phone number is still included when any of the following conditions are met:
You sent a message to the user's phone number or made a call within 30 days before the Webhook was triggered.
You received a message or call from the user's phone number within 30 days before the Webhook was triggered.
The user has been added to your Contact Book.
The 30-day condition is calculated independently for each business phone number. If you use multiple phone numbers under the same WABA, one phone number meeting the condition does not mean the others do.
Unaffected scenarios
The following scenarios are not affected by this update:
Sending messages using an existing phone number — If your system already has the user's phone number, sending messages using that phone number is unaffected. Continue using it as normal.
Users who have not enabled the Username feature — For these users, the phone number field in Webhooks remains exactly as it is today.
Billing and data analytics — This update does not involve any changes to billing rules or data analytics structures.
For details on when phone numbers still appear in Webhooks for users who have enabled the Username feature, see Phone number visibility rules.
Message sending scenarios
When sending messages, phone numbers and BSUIDs can be used flexibly.
When to use phone numbers
Phone numbers are recommended in the following situations:
You already know the user's phone number — Your system already has the user's phone number. Use it directly with no changes needed.
Maintaining the 30-day interaction window — After sending a message to a user's phone number, the user's phone number continues to appear in Webhooks for the next 30 days, helping maintain conversation context continuity.
Sending authentication templates — Authentication templates do not support BSUID. You must use a phone number to send them.
When to use BSUID
BSUIDs are recommended in the following situations:
Phone number unavailable — The user has enabled the Username feature and does not meet the phone number visibility conditions. Webhooks contain only a BSUID with no phone number.
No recent interaction — You have not had message or call interaction with the user within the past 30 days, so their phone number no longer appears in Webhooks. You can only reply using a BSUID.
Cross-BM communication — Your enterprise has multiple BMs and has enabled Parent BSUID. Use the Parent BSUID as a unified identifier to contact the same user across BMs.
Webhook changes
Inbound message Webhook
When you receive a message from a user, the user identifier fields in the Webhook change as follows:
Field | Description | Change |
FromUserId | User's BSUID | New — always included |
FromUserName | Username | New — included when user has enabled a username |
From | Sender's phone number or BSUID | May be a phone number or BSUID |
FromParentUserId | User's Parent BSUID | New |
Outbound message status Webhook
The sent, delivered, and read status Webhooks for outbound messages change as follows:
Field | Description | Change |
UserId | User's BSUID | New — always included |
UserName | Username | New — included in delivered/read status when user has a username |
To | Recipient's phone number or BSUID | May be a phone number or BSUID |
ParentUserId | User's Parent BSUID | New |
User preferences Webhook (user_preferences)
Field | Description | Change |
wa_id | User's phone number | May be empty |
user_id | User's BSUID | New — always included |
username | Username | New — included when user has enabled a username |
From | Sender's phone number or BSUID | Modified to support BSUID |
FromUserId | User's BSUID | New — always included |
FromUserName | Username | New — included when user has enabled a username |
FromParentUserId | User's Parent BSUID | New |
WhatsApp provides a preferences and announcements setting that allows WhatsApp users to indicate their level of interest in marketing messages from your business, and to completely stop or resume receiving such messages. Only the stop and resume actions trigger the user preferences Webhook.
Group webhooks (group member changes)
Field | Description | Change |
participantUserId | Member's BSUID | New |
participantNumber | Member's phone number | May be empty |
participantParentUserId | Member's Parent BSUID | New |
participantUserName | Member's username | New |
Group webhooks (group message receipts)
Field | Description | Change |
RecipientParticipantUserName | Username of the group inbound message sender | New |
RecipientParticipantUserId | BSUID of the group inbound message sender | New |
RecipientParticipantId | BSUID or phone number of the group inbound message sender | Modified — may be a phone number or BSUID |
RecipientParticipantParentUserId | Parent BSUID of the group inbound message sender | New |
Group webhooks (group inbound messages)
Field | Description | Change |
FromUserId | BSUID of the group message sender | New |
FromUserName | Username of the group message sender | New |
From | BSUID or phone number of the group message sender | Modified — may be a phone number or BSUID |
FromParentUserId | Parent BSUID of the group message sender | New |
Call-related Webhooks
User-initiated calls:
Field | Description | Change |
FromUserId | User's BSUID | New |
FromUserName | User's username | New |
From | User's phone number or BSUID | Modified — may be a phone number or BSUID |
FromParentUserId | User's Parent BSUID | New |
Business-initiated calls:
Field | Description | Change |
UserId | User's BSUID | New |
UserName | User's username | New |
To | User's phone number or BSUID | Modified — may be a phone number or BSUID |
ParentUserId | User's Parent BSUID | New |
WhatsApp Business App coexistence webhooks
Echos: Data forwarded to the Cloud API when a business sends a message to a user via the Business App.
Field | Description | Change |
UserId | User's BSUID | New |
UserName | User's username | New |
To | Message recipient | May be a phone number or BSUID |
ParentUserId | User's Parent BSUID | New |
History inbound: Inbound message data synchronized from historical messages.
Field | Description | Change |
From | User's phone number or BSUID | Modified — may be a phone number or BSUID |
FromUserId | User's BSUID | New |
FromParentUserId | User's Parent BSUID | New |
FromUserName | User's username | New |
History outbound: Outbound message data synchronized from historical messages.
Field | Description | Change |
To | Message recipient | May be a phone number or BSUID |
UserId | User's BSUID | New |
ParentUserId | User's Parent BSUID | New |
UserName | User's username | New |
New webhook types
user_id_update
Triggered when a user changes their phone number. This Webhook contains the mapping between the old and new BSUIDs, enabling you to update and associate user identities in your system.
businessUsernameUpdate
Triggered when the status of your business username changes. Status values include approved, reserved, and deleted.
New features
Contact book
Meta provides a hosted Contact Book that requires no integration work on your part. However, this feature does not offer a page-based query interface.
Once enabled, every time your business phone number has a message or call interaction with a user, that user's phone number and BSUID are automatically added to the Contact Book. Users in the Contact Book always have their phone numbers included in subsequent Webhooks, regardless of whether they have enabled the Username feature.
The Contact Book is isolated by BM. Any interaction between any business phone number under the same BM and a user adds that user to the Contact Book, and all business phone numbers within the BM benefit. Contact Book data is not shared between different BMs.
Only new interactions after the feature goes live are recorded. Historical interactions are not retroactively included.
You can disable this feature in Meta Business Suite under Business Settings. Once disabled, existing data is deleted.
If you need to remove a specific user's record from the Contact Book, you can do so via the corresponding API provided by Chat App Message Service. Once removed, that user's phone number no longer appears in Webhooks unless the 30-day interaction condition is met again.
Contact Book limitations:
BM isolation with Parent BSUID — If you have multiple BMs enrolled in the same Parent BSUID account, each BM's Contact Book data is independent and not shared or synchronized across BMs. The same user's phone number and BSUID must each be triggered by separate interactions under each BM before they are individually recorded.
Local storage interaction — If you use Local Storage, when a user clicks the REQUEST_CONTACT_INFO button to share their phone number, Meta extracts the phone number from the user's vCard and stores it in the Contact Book at a Meta data center. No other information from the vCard is retained.
REQUEST_CONTACT_INFO button
When you do not know a user's phone number, you can use this button to proactively request the user to share it within a conversation. The button can be added to utility or marketing templates, or sent as a standalone interactive message.
After the user clicks the button, their phone number is sent to you in a contact Webhook. If you have the Contact Book enabled, the phone number is also automatically added to the Contact Book.
Business username
You can apply for a Business Username for your business phone number, making it easy for users to find your business through a direct search. A Business Username corresponds one-to-one with a business phone number. The same username cannot be bound to multiple phone numbers at the same time.
Format requirements:
Only English letters (a–z), digits (0–9), periods (.), and underscores (_) are supported.
Non-English characters (such as ñ, é, ü) are not supported.
Length must be between 3 and 35 characters.
Must contain at least one English letter.
Cannot start or end with a period. Cannot contain two consecutive periods.
Cannot start with "www" or end with a domain suffix (such as .com, .org).
You can apply for, query, or delete your Business Username through Chat App Message Service.
Business name display rules:
The business name displayed in a user's chat window follows this priority order (highest to lowest):
The contact name the user has saved themselves
Certified business display name or Official Business Account (OBA) name
Business Username
Business phone number
For example, if the user has not saved your number as a contact and your account does not have a certified or approved display name, the user sees your Business Username. If you have not set a Business Username, the phone number is displayed.
Setting a Business Username does not hide your phone number. Regardless of whether you have set a Business Username, your phone number is always displayed in your business profile.
FAQ
Why must I support BSUID?
The Username feature is optional, and you cannot control whether your users enable it. Once a user enables it, their phone number no longer appears in Webhooks. If your system cannot handle missing phone numbers, it will be unable to receive and process messages from these users. BSUID is the only reliable user identifier in this scenario.
What happens if I have not completed the integration yet?
For new users who have enabled a username, Webhooks are still delivered normally, but if your system cannot handle missing phone numbers, message processing may fail. For existing users who meet the 30-day interaction condition, phone numbers are still included in Webhooks, so the short-term impact is limited. However, as the Username feature becomes more widely adopted, the impact scope continues to grow. Complete the integration as early as possible.
How do I know it is the same user after they change their phone number?
After a user changes their phone number, their BSUID is regenerated, and a
user_id_updateWebhook is triggered that contains the mapping between the old and new BSUIDs. Use this Webhook to update and associate user identities in your system.Can a BSUID be used across multiple business phone numbers?
Yes. All business phone numbers under the same BM, regardless of which WABA they belong to, receive the same BSUID for the same user. Any of those phone numbers can use that BSUID to send messages to the user. However, BSUIDs are isolated between different BMs and cannot be used interchangeably. To use BSUIDs across BMs, apply for a Parent BSUID.
What if I still need the user's phone number?
Existing flows that send messages to end users using phone numbers are not affected by BSUID — you can still send messages directly using the user's phone number.
You can obtain or maintain phone number availability through the following means: maintain message or call interactions with the user within 30 days; enable the Contact Book so that phone numbers are automatically stored after interactions; or use the REQUEST_CONTACT_INFO button in conversations to proactively request users to share their phone number.
What is the difference between a Business Username and a display name?
Display names are not unique, and users cannot search for your business using a display name. A Business Username is globally unique, and users can find you through a direct search. When both exist, the display name takes precedence.