> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid.md).
# Usernames & BSUID
## Key Concepts
The following terms define the core mechanics of the username rollout:
1. **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).
2. **Business-Scoped User ID (BSUID)** - A stable, unique user identifier scoped to an individual business portfolio. It is assigned to the `user_id` parameter 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.
3. **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`).
4. **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.
5. **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.
6. **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.
```json
{
"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.
```json
{
"contacts": [{
"profile": { "name": "Nehemiah", "username": "nehemiah.babel" },
"wa_id": "310601600963",
"user_id": "RS.1502576394655843"
}],
"statuses": [{
"id": "wamid.XXX",
"status": "delivered",
"recipient_id": "310601600963",
"recipient_user_id": "RS.1502576394655843"
}]
}
```
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
1. **User has username** - The payload includes `user_id`, `from_user_id`, and `username`. The `wa_id` and `from` fields are only included if the user meets the contact book or 30-day cache conditions.
2. **User has no username** - The payload includes `wa_id`, `from`, `user_id`, and `from_user_id`. The `username` field is not included.
#### Outbound Status Webhooks
1. **Sent to phone** - The payload includes `wa_id` and `recipient_id`.
2. **Sent to BSUID** - The payload includes `user_id` and `recipient_user_id`. The `wa_id` and `recipient_id` fields are only included if the phone number is available via the contact book or 30-day cache.
3. **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](/docs/messaging-api/api-reference/messages.md#post-messages) to send messages:
#### Request Payload Example
```json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "310601600963",
"recipient": "RS.1502576394655843",
"type": "text",
"text": { "body": "Hello!" }
}
```
### Sending Rules
{% stepper %}
{% step %}
#### **Provide an identifier**
Provide `to` (phone number), `recipient` (BSUID), or both. If both are supplied, the `to` (phone) parameter takes precedence.
{% endstep %}
{% step %}
#### **Use complete BSUID values**
Complete BSUID values must be used, including the country code, period, and full identifier.
{% endstep %}
{% step %}
#### Authentication template restriction
One-tap, zero-tap, and copy-code authentication templates are not supported for BSUID recipients. Attempting this returns error `131062`.
{% endstep %}
{% step %}
#### Service window restriction
Initiating a conversation with a free-form message to a BSUID outside of the 24-hour service window will fail with error `131047`. A template must be used to open the conversation.
{% endstep %}
{% endstepper %}
### Response Payloads
The response payload structure depends on the identifier targeted:
#### Sent to phone (or phone + BSUID)
```json
{
"contacts": [{ "input": "310601600963", "wa_id": "310601600963" }],
"messages": [{ "id": "wamid.XXX" }]
}
```
#### Sent to BSUID only
```json
{
"contacts": [{ "input": "RS.1502576394655843", "user_id": "RS.1502576394655843" }],
"messages": [{ "id": "wamid.XXX" }]
}
```
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:
```json
{
"name": "request_number",
"category": "utility",
"language": "en_US",
"components": [
{ "type": "BODY", "text": "Please share the phone number so we can continue." },
{ "type": "BUTTONS", "buttons": [
{ "type": "REQUEST_CONTACT_INFO"}
]}
]
}
```
### Interactive Messages
Send an interactive message block directly using the `request_contact_info` type:
Use the following 360dialog [endpoint](/docs/messaging-api/api-reference/messages.md#post-messages) to send messages:
```json
{
"messaging_product": "whatsapp",
"recipient": "RS.1502576394655843",
"type": "interactive",
"interactive": {
"type": "request_contact_info",
"body": { "text": "Please share the phone number so we can continue." },
"action": { "name": "request_contact_info" }
}
}
```
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
{% stepper %}
{% step %}
#### Length
Length must be between 3 and 35 characters.
{% endstep %}
{% step %}
#### Allowed characters
Only English letters (a-z), digits (0-9), periods (.), and underscores (\_) are allowed.
{% endstep %}
{% step %}
#### Letter and period requirements
Must contain at least one letter and cannot start or end with a period, nor contain consecutive periods.
{% endstep %}
{% step %}
#### Restricted prefixes and suffixes
Cannot start with `www.` or end with a domain suffix (such as `.com` or `.net`).
{% endstep %}
{% endstepper %}
### Endpoints
Use the following 360dialog paths to manage business usernames:
1. **List Reserved Suggestions** - Please use this [endpoint](/docs/messaging-api/api-reference/business-username.md#get-username_suggestions).
2. **Claim or Change Username** - Please use this [endpoint](/docs/messaging-api/api-reference/business-username.md#post-username).
3. **Check Current Status** - Please use this [endpoint](/docs/messaging-api/api-reference/business-username.md#get-username).
4. **Delete Username** - Please use this [endpoint](/docs/messaging-api/api-reference/business-username.md#delete-username).
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:
1. **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.
2. **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.
3. **Error 100** - Param Invalid. The format of the requested business username is invalid.
4. **Error 147001** - Username not available. The username is claimed, blocked by internal checks, or otherwise unavailable.
5. **Error 147002** - Account not eligible. The business portfolio must have a higher messaging limit to request a username.
6. **Error 147003** - FB Account not linked. The phone number must be linked to the Facebook Page that currently uses the username.
7. **Error 147004** - IG Account not linked. The phone number must be linked to the Instagram account that currently uses the username.
8. **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.
9. **Error 133010** - Account not registered. The business phone number must be registered for API use first.
10. **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.
11. **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
{% stepper %}
{% step %}
#### Make Phone Number Nullable
The database must support nullable consumer phone numbers. A mapping table linking BSUID and phone number should be established.
{% endstep %}
{% step %}
#### Store BSUID Globally
The system must store `user_id` (BSUID) from webhooks and use it as the primary key for contact records and CRM mapping.
{% endstep %}
{% step %}
#### Adapt Webhook Consumers
Update parser logic to handle payloads where `contacts[0].wa_id`, `messages[0].from`, or `statuses[0].recipient_id` are absent. Fall back to BSUID equivalents.
{% endstep %}
{% step %}
#### Correlate with message ID
Associate outbound sends and status updates using the `wamid` returned in the response payload.
{% endstep %}
{% step %}
#### Implement Phone Recovery UX
Integrate `REQUEST_CONTACT_INFO` flows to retrieve phone numbers when required for authentication templates or external channel matching.
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.