Business-scoped user IDs
Updated: Nov 21, 2025 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, we will share a new backend user identifier called business-scoped user ID, or BSUID. BSUID uniquely identifies a WA user and is tied to a specific business. This document describes how the addition of usernames will impact API requests, API responses, and webhook payloads. Additional changes to support usernames before the feature is made available will be recorded here. Any changes described in this document are subject to change.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 theusername 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
A business-scoped user ID (“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 theuser_id parameter and appear in all messages webhooks, regardless of whether or not the user has enabled the username feature.
BSUIDs will be:
generated automatically
composed of up to 256 alphanumeric characters
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.
Note that since BSUIDs are unique to each business portfolio-user pair, if you have multiple portfolios, your API requests will fail if you are attempting to message a BSUID that is scoped to a different portfolio. However, there may be legitimate use cases for some businesses to share the BSUID between business portfolios. We are scoping a solution to simplify this process. Please note to your Meta POC if you would like to discuss.
Phone numbers
When a user adopts a username, their phone number will not be included in messages webhooks in some cases. Instead, their BSUID will be sent in a newuser_id field, and their phone number may be sent as an empty string in the wa_id field, on both existing and new API versions. Although phone numbers will still be shared in a few cases, primarily for existing customer interactions, it is essential for you to begin ingesting BSUIDs as soon as possible, to minimize losing any conversation context.
If you message/call a WhatsApp user’s phone number, or receive a message/call from their phone number, we will include their phone number in API responses and messages webhooks for 30 days from the time of sending or receiving, regardless of whether or not the user has adopted a username. Sending/calling or receiving a message/call to or from the user’s phone number within this window will reset the 30 day window.
There may be situations where you receive messages from existing customers outside of the 30 day window that look like a message from a new user, because their phone number is not in the messages webhook (wa_id is an empty string). To ensure you can identify username adopters and maintain conversation context beyond 30 days, we are building a feature that will allow you to continue to receive a user’s phone number even after they have adopted a username, provided you have messaged the user’s phone number in the past. Communication history will be recorded starting from feature opt-in. We will provide details on the opt-in process and timing as they become available.
If a user has not adopted a username, messages webhooks will include both their phone number and their BSUID.
You can message users using either their BSUID or phone number as soon as BSUIDs begin appearing in API responses and webhook payloads.
Country codes
When a WhatsApp user enables the username feature, their phone number may not appear in webhooks. If you don’t know their phone number but still need to communicate with them, you can send a message to their BSUID. Country code will be included in all messages webhooks (subject to change).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, etc.) 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 distinctReserved 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 your 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. To link your page or account, 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 Phone numberSupport
You can contact your Partner Manager with any concerns. You can reach out to any of the standard support channels; for API integrations, please raise a Direct support ticket with question type, WA Usernames API Integration. Use the Report Abuse channel via Direct Support to report impersonation. Use our WhatsApp Intellectual Property Contact Form form to report infringement.Adopt or change a business username
You will be able to adopt or change a business username using Meta Business Suite, WhatsApp Manager, WhatsApp Business app, or the API. Request syntax:status — The status of the latest requested username. Values can be:
APPROVED — The requested username has been approved and will be active once the usernames feature is made available.
REJECTED — The requested username has been rejected. The business phone number’s existing approved username, if any, will remain in place. Check rejection_reasons for details.
PENDING — The username is undergoing review. When a decision is made, a phone_number_username_update webhook will be triggered, indicating the new status.
rejection_reasons — An array of strings indicated the reason(s) for the rejection. Only included if the requested username has been rejected. Values can be:
REQUIRE_FB_ACCOUNT_LINKING — The requested username may be available if you link your WhatsApp business phone number to the Facebook Page.
REQUIRE_IG_ACCOUNT_LINKING — The requested username may be available if you link your WhatsApp business phone number to the Instagram account.
EXISTING_PENDING_REQUEST — A previously requested username is still undergoing review.
NOT_AVAILABLE — The username is not available because it is associated with another account or it doesn’t pass our internal checks.
ACCOUNT_INELIGIBLE — The account is not eligible to request a username. The business phone number’s display name must be approved, and the owning business must be verified.
UNKNOWN — Rejected for an unknown reason. Please contact support.
Get current username
You can use the GET /<BUSINESS_PHONE_NUMBER_ID>/username endpoint to get the status of the business username associated with the business phone number, or information about the username. Request syntax:username — Current username. Will be an empty string if the business phone number has no username.
status — Username status. Values can be:
ACTIVE — The username is approved and will become active once the usernames feature is made available.
RESERVED — The username is reserved for the business phone number but is not active.
requested_username — Requested username. This property will only be included if a new username has been requested on the business phone number, but the requested username is still undergoing review.
Get reserved usernames
Adding a new GET /<BUSINESS_PHONE_NUMBER_ID>/username_suggestions endpoint that returns a list of usernames that have been reserved for your business portfolio. Call the POST /<BUSINESS_PHONE_NUMBER_ID>/username endpoint to claim the desired username from the list, which will then need to be approved. Once approved and usernames become available in your country, it will move to to an “active” status, meaning the business username will start appearing on your business profile, and users will be able to search for it using exact match search. Request syntax:username_suggestions — An array of reserved usernames, if any. These usernames have a higher chance of approval.
Delete a username
You can use the DELETE /<BUSINESS_PHONE_NUMBER_ID>/username endpoint to delete the business username associated with the business phone number. Request syntax:Response syntax:
success — Boolean. Will be set to true if the username is deleted successfully, otherwise it will be set to false.
Cancel pending username request
You can use the DELETE /<BUSINESS_PHONE_NUMBER_ID>/requested_username endpoint to cancel a pending business username request. Request syntax:Response syntax:
success — Boolean. Will be set to true if the username is deleted successfully, otherwise it will be set to false.
phone_number_username_update webhook
A new phone_number_username_update webhook will be added. This webhook will be triggered when the status of a business phone number’s username changes. Please make sure to subscribe each of your apps to this webhook field to be notified of username changes.id — WhatsApp Business Account ID.
time — Unix timestamp indicated when the webhook was triggered
display_phone_number — The business phone number’s display number (the number displayed on your profile in the app.
decision — Indicates the outcome of the business username review process. Values can be:
APPROVED — Indicates the username has been approved and will become active once the usernames feature is made available.
REJECTED — Indicates the username has been rejected. You can edit the name using WhatsApp Manager. Review the rejection reason before editing.
requested_username — The requested username.
rejection_reasons — Indicates the reason why the business username was rejected, if it was rejected. Values can be:
REQUIRE_FB_ACCOUNT_LINKING — The requested username is associated with an existing Facebook page. To claim the username, you must first add your business phone number to the Page.
REQUIRE_IG_ACCOUNT_LINKING — The requested username is associated with an existing Instagram handle. To claim the username, you must first add your business phone number to the Instagram account.
NOT_AVAILABLE — The username is not available because it is associated with another account or it doesn’t pass our internal checks.
ACCOUNT_INELIGIBLE — The account is not eligible to request a username. The business phone number’s display name must be approved, and the owning business must be verified.
UNKNOWN — Rejected for an unknown reason. Please contact support.
Messages
Send message requests
These changes apply to POST /<BUSINESS_PHONE_NUMBER_ID>/messages endpoint requests. This example syntax is sending a text message, but the changes apply to all message types.to — Supports both WhatsApp user phone numbers and user BSUIDs.
Send message response
These changes apply to POST /<BUSINESS_PHONE_NUMBER_ID>/messages endpoint responses.input — Will return the user’s BSUID if you send the message to the user’s BSUID. Otherwise, it will return the user’s phone number, or group ID (if sent the message to a group).
wa_id — Will be set to empty if you sent the message to the user’s BSUID.
user_id — New property. Will be set to the user’s BSUID if you sent the message to the user’s BSUID. Otherwise, the property will be omitted.
Example response to a send message request sent to a user’s phone number:
Error codes
Adding new error code response to the POST /<BUSINESS_PHONE_NUMBER_ID>/messages endpoint. Error code —131062
Details — You can only send authentication messages to recipients' phone numbers, not their business-scoped user IDs.
Marketing Messages API for WhatsApp
Send marketing message requests
Marketing Messages API for WhatsApp will support both phone numbers and BSUIDs. If you have both, we recommend sending messages to phone numbers, primarily so you can continue to receive phone numbers in webhooks. If you only have a user’s BSUID, use their BSUID. These changes will apply to POST /<BUSINESS_PHONE_NUMBER_ID>/marketing_messages endpoint requests.to — Supports both WhatsApp user phone numbers and user BSUIDs.
Send marketing message response
These changes apply to POST /<BUSINESS_PHONE_NUMBER_ID>/marketing_messages endpoint responses.input — Will return the user’s BSUID if you send the message to the user’s BSUID. Otherwise, it will return the user’s phone number, or group ID (if sent the message to a group).
wa_id — Will be set to empty if you sent the message to the user’s BSUID.
user_id — New property. Will be set to the user’s BSUID if you sent the message to the user’s BSUID. Otherwise, the property will be omitted.
Example response to a send a template message to a user’s phone number:
Messages webhooks
Status messages webhooks
These changes will apply to sent, delivered, read, and failed status messages webhooks. Exception: Groups API sent or failed status messages webhooks are unaffected.contacts — New array. Only included for sent, delivered, and read status messages. Will be omitted entirely for failed status messages webhooks.
name — New property. Value will be set to the WhatsApp user’s display name.
username — New property. Will be set to the WhatsApp user’s username if the user has adopted a username. Will be omitted entirely for sent status messages webhooks.
country_code — New property. Will be set to the WhatsApp user’s country code ( subject to change).
wa_id — New property. Will be set to empty if the user has adopted a username and (1) you sent the message to the user’s BSUID, (2) you haven’t messaged the user’s phone number within the last 30 days, or (3) the user has not added your number to their WhatsApp contacts list. If you sent the message to the user’s phone number, it will be set to the user’s phone number.
user_id — New property. Will be set to the WhatsApp user’s BSUID.
recipient_id — New empty value. Will be set to:
the WhatsApp user’s phone number, if you sent the message to the user’s phone number.
the group ID, if you sent the message to a group.
empty, if you sent the message to the user’s BSUID and (1) you haven’t messaged the user’s phone number within the last 30 days, and (2) the user has not added your number to their WhatsApp contacts list.
recipient_user_id — New property. Will be set to the user’s BSUID if you sent the message to the user’s BSUID. Otherwise, the property will be omitted entirely.
Example delivered status messages webhook describing a message sent to the phone number of a WhatsApp user who has enabled the usernames feature:
wa_id, which would normally be set to the user’s phone number, is empty:
Incoming messages webhooks
These changes apply to incoming messages webhooks ( text, image, interactive, etc.), including incoming messages sent by users in a Group chat. The example syntax below is for an incoming text message, but the changes are the same for all incoming message types.username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Set to the user’s country code ( subject to change).
wa_id — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list, otherwise set to the user’s phone number.
user_id — New property, set to the user’s BSUID.
from — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
from_user_id — New property, set to the user’s BSUID.
Example incoming text message from a user who has enabled the username feature. In this scenario, the business has not messaged the user’s phone number in the last 30 days, and the user has not added the business’s phone number to their WhatsApp contacts list. Note that wa_id, which would normally be set to the user’s phone number, is empty:
System status messages webhooks
These changes apply to system status messages webhooks.body — New string. Will be set to User <WHATSAPP_USER_PROFILE_NAME> changed from <OLD_BSUID> to NEW_BSUID if the user changed their business phone number.
wa_id — New (empty) value. Will be set to empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s new BSUID.
type — New (user_changed_user_id) value. Will be set to user_changed_user_id if the user changed their business phone number.
User_preferences webhooks
These changes will apply to user_preferences webhooks.username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Set to the user’s country code ( subject to change).
wa_id — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list, otherwise set to the user’s phone number.
user_id — New property, set to the user’s BSUID.
Groups API
Get group info
These changes apply to GET /<GROUP_ID> endpoint responses.wa_id — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list. Otherwise, will be set to the user’s phone number.
user_id — New property, set to the user’s BSUID.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Set to the user’s country code ( subject to change).
Get group join requests
These changes apply to GET /<GROUP_ID>/join_requests endpoint responses.wa_id — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list. Otherwise, will be set to the user’s phone number.
user_id — New property, set to the user’s BSUID.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Set to the user’s country code ( subject to change).
Remove group participants
These changes apply to DELETE /<GROUP_ID>/participants endpoint requests.user — Will accept a user’s phone number or BSUID.
Groups API webhooks
group_participants_update webhooks
These changes apply to the group_participants_update webhook.wa_id — New value (empty). Will be empty if the user has enabled the username feature and you have not messaged the user’s phone number in the last 30 days, or your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s BSUID.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Will be set to the user’s country code ( subject to change).
Blosk Users API
Block or unblock user requests
These changes apply to the POST and DELETE Block Users requests. This example is for a block user request syntax, but the changes also apply to unblock requests.input — Will be set to the user’s BSUID if you used their BSUID when blocking or unblocking the user. Will be set to the user’s phone number if you used their phone number when blocking or unblocking the user.
wa_id — New empty value. Will be set to empty if you used the user’s BSUID when blocking or unblocking the user. Will be set to the user’s phone number if you used their phone number when blocking or unblocking the user.
user_id — New property. Will be set to the user’s BSUID if you used the user’s BSUID when blocking or unblocking the user. If you used their phone number, the property will be omitted.
Calling API
Businesses-initiated call requests
The changes apply to business-initiated Calling API requests.to — Supports both WhatsApp user phone numbers and user BSUIDs.
Get call permissions
The changes apply to get call permissions requests. There are no changes to responses.user_wa_id — Accepts both WhatsApp user phone numbers and user BSUIDs.
Send call permission request
See send message requests.Call permission request webhooks
See incoming messages webhooks.Business-initiated connected calls webhooks
These changes apply to business-initiated connected calls webhooks.contacts — A new contacts object will be included.
name — New property. This will be set to the user’s profile name.
country_code — New property. This will be set to the user’s country code ( subject to change).
user_id — New property. This will be set to the user’s BSUID.
to — New empty value. This will be set to the WhatsApp user’s phone number if the user has adopted a username and (1) the message was sent to their phone number, (2) your business phone number is already in the user’s WhatsApp contacts list, or (3) you have messaged or called their phone number within the last 30 days. Otherwise, it will be set to an empty string.
to_user_id — New property. This will be set to the user’s BSUID.
User-initiated connected calls webhooks
These changes will apply to user-initiated connected calls webhooks.from — New empty value. If the user has adopted a username, it will be set to an empty string if (1) you haven’t messaged or called the user’s phone number in the last 30 days or (2) your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
from_user_id — New property. Will be set to the user’s BSUID.
wa_id — New empty value. If the user has adopted a username, it will be set to an empty string if (1) you haven’t messaged or called the user’s phone number in the last 30 days or (2) your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
name — New property. Will be set to the user’s profile name.
username — New property. If the user has adopted a username, it will be set to the user’s username. Otherwise, the property will be omitted.
country_code — New property. Will be set to the user’s country code ( subject to change).
user_id — New property. Will be set to the user’s BSUID.
Business-initiated terminated calls webhooks
These changes apply to business-initiated terminated calls webhooks.to — New empty value. This will be set to the WhatsApp user’s phone number if the user has adopted a username and (1) the call was made to their phone number, (2) your business phone number is already in the user’s WhatsApp contacts list, or (3) you have messaged or called their phone number within the last 30 days. Otherwise, it will be set to an empty string.
to_user_id — New property. This will be set to the user’s BSUID.
contacts — A new contacts object will be included.
name — New property. This will be set to the user’s profile name.
country_code — New property. This will be set to the user’s country code ( subject to change).
user_id — New property. This will be set to the user’s BSUID.
User-initiated terminated calls webhooks
These changes will apply to user-initiated terminated calls webhooks.from — New empty value. This will be empty if the user has adopted a username and (1) your business phone number is not in the user’s WhatsApp contacts list and (2) you have not messaged or called their phone number within the last 30 days. Otherwise, it will be set to the user’s phone number.
from_user_id — New property. This will be set to the user’s BSUID.
wa_id — New empty value. This will be empty if the user has adopted a username and (1) your business phone number is not in the user’s WhatsApp contacts list and (2) you have not messaged or called their phone number within the last 30 days. Otherwise, it will be set to the user’s phone number.
name — New property. This will be set to the user’s profile name.
country_code — New property. This will be set to the user’s country code ( subject to change).
user_id — New property. This will be set to the user’s BSUID.
Business-initiated calls status webhooks
These changes will apply to business-initiated calls status webhooks.recipient_id — New empty value. This will be set to an empty string if the WhatsApp user has adopted a username and (1) the call was made to their BSUID, (2) your business phone number is not in the user’s WhatsApp contacts list, and (3) you have not messaged or called their phone number within the last 30 days. Otherwise, it will be set to the user’s phone number.
recipient_user_id — New property. This will be set to the user’s BSUID.
contacts — A new contacts array will be included.
name — New property. This will be set to the user’s profile name.
country_code — New property. This will be set to the user’s country code ( subject to change).
user_id — New property. This will be set to the user’s BSUID.
SIP invites for business-initiated calls
These changes apply to business-initiated calls made using SIP.BSUID — Will be the user’s BSUID if the call was made to the user’s BSUID, or the user’s phone number if sent to their phone number.
SIP invites for user-initiated calls
These changes apply to user-initiated calls made using SIP.BSUID — Will be the user’s BSUID if the call was made to the user’s BSUID, or if the user has adopted a username and (1) you haven’t messaged or called the user’s phone number in the last 30 days, or (2) your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be the user’s phone number.
USERNAME — Will be the user’s username.
USER_COUNTRY_CODE — Will be the user’s country code ( subject to change).
SIP OK responses for business-initiated calls
BSUID — Will be the user’s BSUID if the call was made to the user’s BSUID, or if the user has adopted a username and (1) you haven’t messaged or called the user’s phone number in the last 30 days, or (2) your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be the user’s phone number.
USERNAME — Will be the user’s username.
USER_COUNTRY_CODE — Will be the user’s country code ( subject to change).
SIP BYE responses for business- and user-initiated calls
BSUID — Will be the user’s BSUID if the call was made to the user’s BSUID, or if the user has adopted a username and (1) you haven’t messaged or called the user’s phone number in the last 30 days, or (2) your business phone number is not in the user’s WhatsApp contacts list. Otherwise, it will be the user’s phone number.
USERNAME — Will be the user’s username.
USER_COUNTRY_CODE — Will be the user’s country code ( subject to change).
Coexistence
History webhooks
These changes will apply to history webhooks that describe an onboarded business customer’s WhatsApp Business app chat history.id — New empty value. Will be an empty string if, at the time when the user sent the message to the business customer, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
context — A new context object will be included.
wa_id — New property. Will be an empty string if, at the time when the user sent the message to the business customer, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s BSUID.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Will be set to the user’s country code (_subject to change).
from — New empty value. Will be an empty string if, at the time when the user sent the message to the business customer, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
from_user_id — New property. Will be set to the user’s BSUID.
These changes will apply to history webhooks that describe a media asset sent from a WhatsApp user to a business customer, or vice-versa.
contacts — A new contacts object will be included.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Will be set to the user’s country code ( subject to change).
wa_id — New property. Will be an empty string if, at the time when the user sent the message to the business customer, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s BSUID.
from_user_id — New property. Will be set to the user’s BSUID.
to — New empty value. Will be an empty string if, at the time when the business sent the message to the user, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
to_user_id — New property. Will be set to the user’s BSUID.
smb_message_echoes webhooks
These changes will apply to smb_message_echoes webhooks.contacts — A new contacts object will be included.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Will be set to the user’s country code ( subject to change).
wa_id — New property. Will be an empty string if, at the time when the user sent the message to the business customer, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s BSUID.
to — New empty value. Will be an empty string if, at the time when the business sent the message to the user, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of when the message was sent, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
to_user_id — New property. Will be set to the user’s BSUID.
smb_app_state_sync webhooks
These changes will apply to smb_app_state_sync webhooks.phone_number — New empty value. Will be an empty string if, at the time of the synchronization request, (1) the user had already enabled usernames, (2) the business customer had not messaged the user’s phone number within 30 days of the synchronization request, and (3) the business customer’s business phone number was not in the user’s WhatsApp contacts list. Otherwise, it will be set to the user’s phone number.
user_id — New property. Will be set to the user’s BSUID.
username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
country_code — New property. Will be set to the user’s country code ( subject to change).
Analytics
No changes.Billing and invoicing
No changesFAQs
What do I need to do to support usernames? BSUIDs and country code (subject to change) will begin appearing in webhooks payloads before usernames are made available to WhatsApp users. You will need to adopt BSUIDs in order to process user-initiated messages from users who have adopted a username. To do this, you must: Update your webhook integrations to support BSUIDs, which will be assigned to a newuser_id property in existing webhooks.
Build logic to support handling multiple identifiers (phone numbers from non-username adopters; BSUIDs from username adopters if phone number is not present in webhooks), and map relevant fields back to your CRM/database.
Update internal and external systems related to these integrations to be able to handle BSUIDs and join with previous identifiers; primarily CRM (either 3P or internal database) and any tools or workflows triggered off of CRM (e.g., triggered campaign messages, campaign management, measurement, billing, etc.).
If you still require customer phone numbers, update your messaging bots/journeys (if used) to request phone numbers, handle scenarios where users do not share phone numbers, and iterate on these new conversation journeys.
If you have multiple business portfolios with Meta, you may want to implement a solution to enable central CRM access across multiple portfolios, to minimize the operational overhead that comes with using and storing BSUIDs.
When will I receive a BSUID vs. a phone number?
When a user adopts a username, they will have phone number privacy meaning their phone number will not be displayed in the app, and their phone number will not be included in webhooks. If the user’s phone number is not present (the wa_id property is set to an empty string), you can use their BSUID, which will be included and assigned to a new user_id property.
If a user has not adopted usernames, you will receive both their phone number and their BSUID.
We will continue to share the phone number in a few cases, primarily for existing customer interactions. We’ll automatically include or return the user’s phone number on a rolling 30 days after any interaction between you and the user’s phone number, or if your business phone number is in the user’s WhatsApp contacts list.
Per our Cloud API Terms of Service, however, phone numbers and related data are retained for a maximum of 30 days to support features like message redelivery. There may be situations where you receive messages from existing users outside of this 30 day window, which may look like a new user thread to you. Therefore, it is essential that you begin supporting BSUIDs as soon as possible, to minimize losing any conversation context.
Why do partners and directly-integrated businesses using the Cloud API, including directly integrated ads that click to WhatsApp advertisers, have to adopt BSUID?
Partners and businesses must adopt BSUID to continue processing incoming messages from WhatsApp username adopters. Once BSUID is adopted and user messages from username adopters are processed, message webhooks will no longer include phone numbers in some cases as part of the webhook such as wa_id, so partners and businesses must ensure all connected systems can handle BSUID. They will also be able to ask for a user’s phone number in-thread.
If a business has not yet adopted BSUID and starts to receive messages from username adopters which they cannot process, will there be any recourse or corrective action?
If a business has not yet adopted BSUID and is not able to process messages from username adopters, there will not be any recourse or corrective action.
For messages from new customers of the business: Meta will continue to send the webhook of an incoming message. Depending on the specifics of the implementation, this may impact systems that are not equipped to handle an empty string being sent in the wa_id field when phone number is not present, and BSUID being sent through a new field.
For messages from existing customers of the business: we will continue to share the phone number in a few cases, primarily for existing customer interactions.
How do business usernames differ from display names? When will a user see a business username vs a display name?
Business usernames will provide an ability for the users to reach the business by the business’ username, meaning an end user can search for a business username using their exact username and reach out to the businesses. Since end users cannot search by display names, business usernames offer a clear advantage as a searchable and unique identifier for users to reliably find the correct business.
Business usernames must follow specific formatting rules on length and allowed characters, while display names have some more leeway in terms of formatting.
Business usernames are unique and are tied 1-1 to phone numbers, meaning @JaspersMarket would be tied to one phone number while @JaspersMarketCustomerSupport would be tied to another phone number. Display names are not tied 1-1 to phone numbers, meaning the display name Jasper’s Market can have 10 phone numbers under this display name.
When a business has both a username and display name, display name will be shown first (e.g., in Profile, Chat list, Messages, etc), for the businesses to build trust with the users and for users to recognize the business when business reaches out to the user.
Did you find this page helpful?
ON THIS PAGE
User usernames
Business-scoped user ID
Phone numbers
Country codes
Business usernames
Reserved usernames
Chat window display priority
Support
Adopt or change a business username
Get current username
Get reserved usernames
Delete a username
Response syntax:
Cancel pending username request
Response syntax:
phone_number_username_update webhook
Messages
Send message requests
Send message response
Error codes
Marketing Messages API for WhatsApp
Send marketing message requests
Send marketing message response
Messages webhooks
Status messages webhooks
Incoming messages webhooks
System status messages webhooks
User_preferences webhooks
Groups API
Get group info
Get group join requests
Remove group participants
Groups API webhooks
group_participants_update webhooks
Blosk Users API
Block or unblock user requests
Calling API
Businesses-initiated call requests
Get call permissions
Send call permission request
Call permission request webhooks
Business-initiated connected calls webhooks
User-initiated connected calls webhooks
Business-initiated terminated calls webhooks
User-initiated terminated calls webhooks
Business-initiated calls status webhooks
SIP invites for business-initiated calls
SIP invites for user-initiated calls
SIP OK responses for business-initiated calls
SIP BYE responses for business- and user-initiated calls
Coexistence
History webhooks
smb_message_echoes webhooks
smb_app_state_sync webhooks
Analytics
Billing and invoicing
FAQs