Usernames & BSUID
This page describes the implementation of WhatsApp usernames and business-scoped user IDs (BSUIDs), including API changes, webhooks, and migration requirements
Key Concepts
The following terms define the core mechanics of the username rollout:
User Username - An optional handle that a WhatsApp user can set. If a user sets a username, the handle is displayed instead of a phone number, and the phone number is withheld from businesses in webhook payloads (with certain exceptions).
Business-Scoped User ID (BSUID) - A stable, unique user identifier scoped to an individual business portfolio. It is assigned to the
user_idparameter and is generated automatically. The format consists of a two-letter ISO country code, a period, and up to 128 alphanumeric characters (for example,BR.1502576394655843). If a user changes a phone number, a new BSUID is generated.Parent BSUID - A single BSUID shared across multiple business portfolios for eligible managed businesses enrolled with Meta. The format includes
ENT(for example,US.ENT.11815799212886844830).Meta Contact Book - A Meta-hosted database that automatically records phone-to-BSUID mappings for any message or call exchanged after early April 2026. While a contact remains in the contact book, the associated phone number will continue to appear in webhooks.
30-Day Cache - A rolling cache evaluated per business phone number. If a specific business phone number messages or calls a user within a 30-day window, the user's phone number continues to be included in webhooks.
Business Username - A handle for a business phone number used for brand discoverability and search. Adopting a business username does not hide the business phone number.
Webhooks and Payloads
Webhooks will undergo structural modifications once usernames are generally available.
Inbound Message Webhooks
When a user messages a business, the payload contains the stable user_id (BSUID). The wa_id and from fields may be omitted after General Availability if the user has a username and no prior interaction history exists.
{
"contacts": [{
"profile": {
"name": "Nehemiah",
"username": "nehemiah.babel"
},
"wa_id": "310601600963",
"user_id": "RS.1502576394655843"
}],
"messages": [{
"from": "310601600963",
"from_user_id": "RS.1502576394655843",
"type": "text",
"text": { "body": "Hello!" }
}]
}Status Webhooks
For sent, delivered, and read status messages, a contacts array is added, and the statuses block gains BSUID fields.
For failed status messages, the contacts array is completely omitted, and recipient_user_id is omitted if the message was sent to a phone number.
Identifier Availability Quick Reference
This section outlines when user identifiers are included in webhooks after General Availability:
Inbound Webhooks
User has username - The payload includes
user_id,from_user_id, andusername. Thewa_idandfromfields are only included if the user meets the contact book or 30-day cache conditions.User has no username - The payload includes
wa_id,from,user_id, andfrom_user_id. Theusernamefield is not included.
Outbound Status Webhooks
Sent to phone - The payload includes
wa_idandrecipient_id.Sent to BSUID - The payload includes
user_idandrecipient_user_id. Thewa_idandrecipient_idfields are only included if the phone number is available via the contact book or 30-day cache.Username Field - Only included in delivered and read statuses if the user has enabled a username.
Sending Messages
To message a user using a BSUID, use the recipient field instead of the to field.
Use the following 360dialog endpoint to send messages:
Request Payload Example
Sending Rules
Response Payloads
The response payload structure depends on the identifier targeted:
Sent to phone (or phone + BSUID)
Sent to BSUID only
A successful send always returns a message ID (wamid), which must be stored as the primary correlation key.
Recovering Phone Numbers
When a system holds only a BSUID, the phone number can be requested using the REQUEST_CONTACT_INFO button.
Utility and Marketing Templates
Add a request contact information button to the template components:
Interactive Messages
Send an interactive message block directly using the request_contact_info type:
Use the following 360dialog endpoint to send messages:
When a user taps the button, the system receives a contacts webhook with origin set to contact_request and the phone number contained in the phones array. No vCard is included.
Managing Business Usernames
Businesses can claim reserved usernames or change them via 360dialog endpoints.
Format Rules
Endpoints
Use the following 360dialog paths to manage business usernames:
List Reserved Suggestions - Please use this endpoint.
Claim or Change Username - Please use this endpoint.
Check Current Status - Please use this endpoint.
Delete Username - Please use this endpoint.
The available status transitions for usernames are reserved to approved, and finally active upon General Availability.
Error Codes
The following errors are associated with business username registration and BSUID messaging:
Error 10 - Application does not have permission for this action. Confirm that the system user has Full control or Phone number access for the WhatsApp Business Account assets.
Error 33 - Invalid ID. The business phone number ID is invalid, the account has been deleted, or the required whatsapp_business_management permission is missing.
Error 100 - Param Invalid. The format of the requested business username is invalid.
Error 147001 - Username not available. The username is claimed, blocked by internal checks, or otherwise unavailable.
Error 147002 - Account not eligible. The business portfolio must have a higher messaging limit to request a username.
Error 147003 - FB Account not linked. The phone number must be linked to the Facebook Page that currently uses the username.
Error 147004 - IG Account not linked. The phone number must be linked to the Instagram account that currently uses the username.
Error 147005 - Username transfer required. The username is in use on another phone number in the portfolio. Request must be resent with transfer_action set to force_transfer.
Error 133010 - Account not registered. The business phone number must be registered for API use first.
Error 131062 - BSUID recipients not supported. Returned when attempting to send authentication templates (such as one-tap, zero-tap, or copy-code buttons) to a BSUID recipient instead of a phone number.
Error 131047 - Window closed. Initiating a conversation with a free-form message to a BSUID outside of the 24-hour service window will fail; a template must be used.
Frequently Asked Questions
Timeline and Rollout
When exactly does this start affecting me?
You may see username fields in webhooks any time from now, as Meta enables adoption in selected (undisclosed) countries, but phone numbers remain in webhooks throughout this pre-GA rollout, so nothing breaks yet. Phone withholding starts at full GA. Even then, existing active conversations are protected (contact book + 30-day cache); the breaking case is new inbound contacts who adopted a username: BSUID-only from the first message.
What are the firm key dates and the mandatory migration deadline?
Confirmed live: BSUID in webhooks (March-April 2026), Meta Contact Book (April 2026), sending to BSUIDs (early July 2026), REQUEST_CONTACT_INFO buttons (early July 2026). Username adoption then rolls out country-by-country, not disclosed in advance. There is no strict mandatory cutover date and no forced API-version upgrade - username adoption is optional for consumers, so the timeline is consumer-driven rather than enforced by Meta. That said, migration is a functional necessity, not optional in practice: once end users in a country can hide their phone numbers, any integration that has not been updated to accept BSUIDs and tolerate an empty phone number will start failing and conversations will break. Meta therefore strongly advises completing the integration by late June 2026 - when the first users in test countries gain the ability to hide their numbers. Full global GA is targeted for the second half of 2026.
During the transition, will webhooks still carry both the phone number and the BSUID when available?
Yes. Pre-GA, phone numbers remain in all webhooks alongside the BSUID. Post-GA, the phone number is included if any of: that business number messaged the user in the last 30 days, the user messaged that business number in the last 30 days, or the user is in the portfolio's contact book - otherwise BSUID only.
Identifiers and Mapping
Is the BSUID the same across my clients?
No. It is scoped per business portfolio. The same consumer has a different BSUID for each client. Never deduplicate or share BSUIDs across portfolios.
Does a username change break my mapping?
No. Usernames can change; the BSUID stays stable. Switching to a new device or handset (same phone number) does not change it either. Only a user changing their phone number regenerates the BSUID - and a system webhook is received when that happens.
Can the username feature be turned off by the user, and what happens if they toggle it?
Yes. Consumers can fully remove or delete their username at any time. Deleting a username makes their phone number visible again, and it simply resumes flowing into webhooks. Deleting or disabling a username does not change the user's underlying BSUID, so the mapping stays intact. In fact, if a user had previously hidden their phone number, deleting the username acts as a trigger to share it - populating the Contact Book so the number is available for future interactions.
What is the recommended migration strategy when the phone number is my primary database key?
Make the consumer phone nullable everywhere; persist user_id (BSUID, per portfolio - plus parent_user_id if applicable) from every webhook starting now; build a BSUID-to-phone mapping table and treat phone as enrichment, not identity. Route on field name (wa_id = phone, user_id = BSUID) rather than E.164 validation, and correlate sends by wamid.
Can I match a brand-new username-only user to my historical phone-based records?
Not automatically. A user who only messaged the business before launch and returns username-only with no recent history arrives as BSUID only - unrecoverable by mapping alone. Use REQUEST_CONTACT_INFO to ask the user to share the number, then map. Users with any post-launch interaction stay matchable via the contact book or 30-day cache.
Sending Messages
Where does the BSUID go in the send request - in to?
No. The to field is phone-only. BSUIDs go in the separate recipient field (omit to for a BSUID-only send). Putting a BSUID in to fails.
Can I keep messaging by phone number - and for how long?
Yes, wherever it is available - and it is recommended, since phone-based interactions keep the phone visible in webhooks via the 30-day cache/contact book. No deprecation or sunset date for phone-based sending has been published.
I collected a phone number outside WhatsApp (web form, CRM, etc.). Can I still start the conversation if that user is username-only?
Yes. Send a template to the phone number as usual. Because the message was sent to the phone number, the send response and the user's reply include both the phone number (wa_id / from) and the BSUID - and that first business-initiated contact creates the contact book entry, so the phone number keeps appearing in subsequent webhooks. Store the BSUID from the first reply and the mapping is complete. Username privacy only hides numbers WhatsApp would have to reveal to the business; numbers already collected keep working.
Do utility templates and the 24-hour service window behave differently for BSUID-only users?
No window difference - a BSUID send into a closed 24-hour window fails with error 131047; a template must be used. Utility and marketing templates work to BSUIDs. The exception is authentication templates (one-tap, zero-tap, copy-code), which require a phone and fail with error 131062.
What breaks for authentication / identity-verification flows?
Authentication templates are not supported for BSUID recipients (error 131062). Recover the phone number via REQUEST_CONTACT_INFO first, then send the authentication template.
Can I start a conversation using the user's username instead of their phone number?
No. The username is display-only and can change over time - never use it to address a message. Send to a phone number (to) or a BSUID (recipient). The BSUID is the stable identifier and does not change when the user changes their username. Standard initiation rules still apply: to open a conversation with a BSUID-only user, a template is required (a free-form send into a closed 24-hour window fails with error 131047), and authentication templates are not supported for BSUIDs (error 131062).
Phone Recovery and Contact Book
If I ask via REQUEST_CONTACT_INFO, does the phone come back in all subsequent webhooks?
Yes - a shared number is automatically added to the contact book, so later webhooks include the phone again. Caveat: as of June 2026, REQUEST_CONTACT_INFO is not yet reliable in production - stage it but do not depend on it in live traffic until stability is confirmed.
Can I clear a phone number from the 30-day cache or contact book?
No. The 30-day cache remains even after DELETE /contact_book is requested. There is no supported API or workaround to bypass or clear the 30-day rolling cache once the feature is live. Plan testing and data flows around the cache window rather than expecting to flush it on demand.
Business Usernames
Do business usernames hide my clients' business numbers?
No. Business usernames are for branding and discoverability only.
How does the business display name work in chat?
Chat-header display priority is: saved contact name -> verified business / OBA name -> username -> phone number. Claim the reserved handle now; it becomes visible/searchable at GA.
How do API clients reserve a business username?
Starting June 29, 2026, a business username can be adopted or changed via Meta Business Suite, WhatsApp Manager, the WhatsApp Business app, or the Username API. API clients can reserve directly today through the 360dialog API (POST /username) - no need to go through the app. A 360dialog UI for this is coming.
If a client reserves the username in the WhatsApp Business app and later migrates to the API, is it retained?
The username is attached to the business account/phone-number asset, so it is expected to persist through migration and not need re-reserving. We are confirming this with Meta and will update here.
Groups
What about group messages?
Send responses echo the group ID in input; group flows are otherwise unaffected by this guide's scope.
Account Types and Migration
Does this apply to WhatsApp Business API accounts, and what about Coexistence?
Yes. BSUIDs and usernames are a platform-level change across the whole WhatsApp ecosystem - Cloud API, and Coexistence setups all get BSUIDs in webhooks and can be addressed by BSUID. The migration steps apply to any integration that consumes webhooks or sends messages.
We are migrating between the WhatsApp Business app and the API - does anything break?
The BSUID is tied to the user-to-business-portfolio relationship, not to how the account is accessed, so identity mapping is not expected to change on migration. One item being confirmed with Meta is whether Contact Book entries and the 30-day cache carry over across the migration (they may reset, which would flip some contacts to BSUID-only until the next interaction).
System Integration Checklist
Last updated
Was this helpful?