Starting in 2026, the WhatsApp Business Platform introduces significant changes to how businesses identify and communicate with their users. This evolution aims to prioritize privacy, allowing people to interact with businesses without having to share their phone number. Username reservation opens on June 29, 2026 globally, and activation is rolled out in waves by country.

New — now available: requesting the phone number within the flow is now available in Botmaker. With WhatsApp’s Request contact details action you can ask the user for their number directly in the conversation when your operation needs it. See the step by step in the article Request contact details: ask users who reach out without sharing it for their phone number.

You can:

• Reserve your preferred username to protect your brand name before activation.
• Identify your WhatsApp users with the new BSUID, even when they don’t share their phone number.
• Consume the BSUID and the phone number from the bot variables within your flows.
• Access your contacts’ BSUID via API or webhooks to sync it with your external systems.
• Continue sending notifications by phone number, BSUID, or ChatID.
• Gradually adapt your flows and databases to support alphanumeric identifiers of up to 128 characters.

Prerequisites

Have at least one WhatsApp Business Platform channel connected to Botmaker. Access to your Botmaker account with permissions to manage bots, contacts, and integrations.

Key concepts

BSUID (Business Scoped User ID): a unique, anonymous identifier generated by Meta for each specific user-and-business combination. It is an alphanumeric string of up to 128 characters.

Username: a public username that each person can activate on WhatsApp as an alternative to sharing their phone number.

ChatID: a unique identifier for each chat in Botmaker, independent of the channel or the user’s identity.

Contact ID / platformContactId: the user’s identifier in the channel within Botmaker. It can contain the phone number or the BSUID, depending on the case.

${whatsappNumber}: a variable that stores the phone number only when the user shares it explicitly.

Contact Book: a Meta Business Suite feature that keeps your current customers’ numbers visible once they activate their username.

What is the BSUID?

The Business Scoped User ID (BSUID) is a unique, anonymous identifier generated by Meta for each specific user-and-business combination.

• It is an alphanumeric string of up to 128 characters. It uses the user’s two-letter country code (per the ISO 3166 alpha-2 standard) as a prefix, followed by a period and an alphanumeric string (for example: US.13491208655302741918).
• It contains no personal information, only the country associated with the account.
• It is specific to each Meta Business Manager: a user’s ID for “Business A” will be different from the one for “Business B”.

Meta’s confirmed timeline

The change rolls out on two fronts. On one hand, the BSUID infrastructure and the API; on the other, the reservation and activation of end users’ usernames, which is enabled in waves by country.

BSUID infrastructure and API

There is no global phone-number “shutoff” date. The number stops being available on the platform on an individual basis, when each user activates their username (an opt-in feature).

• March 31, 2026: BSUIDs are already available on the platform.
• May 2026: the API supports sending messages by BSUID.
• Later in 2026: widespread adoption of usernames by end users.

Username reservation and activation

Username reservation opens on June 29, 2026 globally. From that date, all businesses worldwide can reserve their preferred username; reserving early protects your brand name before activation.

Activation (when the username becomes usable) is rolled out in waves:

Businesses can reserve or claim their usernames through WhatsApp Manager, Meta Business Suite, or the Username API.

Step by step: if you want to see how to reserve and register your username step by step, inside Botmaker or in Meta’s Business Manager, see the article “How to register your WhatsApp username in Botmaker”.

Important for API-integrated clients: in addition to reserving the username, you must ensure your systems support Business-Scoped User IDs (BSUIDs) alongside phone numbers. The technical documentation is in Business Scoped User IDs (Meta).

What to communicate to your clients: username reservations open in late June 2026, and actual usability depends on their country’s rollout wave. Reserving early protects their preferred name.

Note: when a user activates their username, their phone number stops being available to the business, unless there has been interaction in the last 30 days, the user is in the business’s contact book, or other exceptions defined by Meta apply.

Impact on the Botmaker platform

Botmaker is adapting so this transition is seamless:

• Chats: will always show the BSUID information.
• Contacts: the BSUID appears in the user’s profile within the contacts screen, and contacts are grouped by BSUID to keep the information consistent.
• API and Integrations: you’ll be able to manage conversations using the phone number, the BSUID, or the ChatID.

The user’s unique identifier in Botmaker will become independent of the medium: you’ll be able to message, search chats, or send templates interchangeably by phone number or by BSUID, and the platform handles the rest.

Consuming information on the platform

Botmaker makes the BSUID and the phone number available within the platform through the bot variable ${bsuid}, and it also lets you consume them from external systems via API or webhooks.

As long as the BSUID is available, you can find the data in four places:

• Contacts screen: the BSUID appears in the user’s profile.
• Webhooks: they include the phone number and the BSUID.
• Code actions: available in context.userData.bsuid and context.userData.whatsappNumber.
• API: you can download contacts with their phone number and associated BSUID through the /contacts endpoint (Contacts API, already available).

Variables available on the platform

With this change, Botmaker works with three key variables worth knowing in detail. Each one plays a distinct role:

• ${bsuid}: always contains the user’s BSUID in WhatsApp conversations. It is already available on the platform and you can use it in the bot flows.
• Contact ID / platformContactId (the user’s ID in the channel): will contain the user’s phone number when available. If the user never shared their phone, it will contain the BSUID, and that identifier will persist for the lifetime of that contact.
• ${whatsappNumber} (new variable): will contain the phone number only when the user has shared it explicitly. If the user never shared it, this variable will be empty.
• CHAT_CHANNEL_ID: does not change. It still represents the customer’s line (the business), not the user’s.

Note: starting with the rollout, the platformContactId may stop being a phone number and start containing a BSUID. Any bot logic, validation, or integration that assumes a numeric format will need to be adjusted to support alphanumeric strings of up to 128 characters.

Consuming in code actions

The BSUID and the phone number are already available within code actions. You can access them directly from the user context:

• context.userData.bsuid: the user’s BSUID in the WhatsApp conversation.
• context.userData.whatsappNumber: the user’s phone number, when they have shared it explicitly.

This lets you consume both identifiers within your business logic without requiring any additional configuration.

Information available via API

Botmaker added the /contacts endpoint, which lets you download contact information, including the associated BSUID. The Contacts API is already available.

• It joins the set of endpoints already available (/chats, /e-commerce, etc.).
• It lets you retrieve all of the account’s contacts along with their BSUID and, when available, their phone number.
• The documentation is automatically added to Botmaker’s official API documentation.

In addition to the /contacts endpoint, the existing endpoints already let you reference a user by phone number or by BSUID interchangeably. This applies to sending templates, searching chats, and other operations.

Information in webhooks

Botmaker’s webhooks are already sending the BSUID in their payload, along with the phone number when available. When a user interacts via WhatsApp and Botmaker has the BSUID, it is sent automatically through the corresponding field, with no changes required to your existing webhook configuration.

Usage recommendations

So your integration works before and after the rollout without requiring urgent adjustments:

• Reserve your username as soon as possible (starting June 29, 2026) to protect your brand name, even if activation in your country happens in a later wave.
• Use the Contact ID as the primary identifier in your flows and integrations. The platform will automatically resolve whether it corresponds to the phone number or the BSUID as the case may be.
• Don’t build your flows on the assumption that you’ll have a phone number. As users activate their usernames, the phone number will stop being available for a growing share of contacts.
• Avoid asking the user for the phone number unless strictly necessary (for example, for physical product shipping or legal validations). In those cases, you can capture the data with a utility or marketing template and store it in the ${whatsappNumber} variable.
• Expand the ID fields in your systems to support alphanumeric strings of up to 128 characters.

Note — now available: when you need to ask for the number within the conversation, you can now do it with WhatsApp’s Request contact details action, without relying on a template. Learn how to set it up in the article Request contact details: ask users who reach out without sharing it for their phone number.

Who is affected by this change?

It’s important to identify which processes will be modified and which will stay the same.

Affected:

• WhatsApp channels only: this change does not apply to other social networks connected to Botmaker.
• Outbound campaigns to users who haven’t shared a phone number: specifically marketing or utility ones. The notification can still be sent, but via BSUID.

Not affected:

• User-initiated conversations (User Initiated): when the customer writes first, communication flows normally.
• Authentication templates (OTP): verification code messages have no changes to their structure.
• Historical customers: people who communicated with the bot between March and June 2026 will not have their future relationship with the business affected.
• Users who consented: customers who, after June 2026, explicitly agreed to share their phone number.
• Existing flow actions: trigger intent, change bot, master bot, and external-link authentications do not require changes. The only thing to keep in mind is that the platformContactId or the “user’s ID in the channel” may stop being a phone number.

Notifications to phone numbers

The ability to send notification templates using traditional phone numbers will be maintained, since the system will let you reference WhatsApp conversations by ChatID, phone number, or the new BSUID.

For contacts who already have a number registered from prior interactions, Botmaker will keep both data points to ensure service continuity.

What should businesses do to adapt to this change?

To avoid disruptions, we recommend following these steps:

1. Reserve your brand’s username: starting June 29, 2026 you can reserve it in WhatsApp Manager, Meta Business Suite, or the Username API. Keep in mind that its activation will depend on your country’s wave.
2. Update your databases: expand the ID fields in your systems from 15 to 128 alphanumeric characters to support the BSUID format.
3. Map identity: prepare your CRM to record the BSUID as well as the phone number and email, linking them to a single customer profile.
4. Enable the contact book: configure the Contact Book feature in Meta Business Suite to ensure your current customers’ numbers stay visible.
5. Redesign your flows: adjust the bots so they can initially operate with only the BSUID, without mandatorily depending on the phone number to function.

Also adopt the new variables and data sources on the platform: use ${bsuid}, Contact ID, and ${whatsappNumber} as appropriate in each bot flow, consume context.userData.bsuid and context.userData.whatsappNumber from your code actions, and leverage the API’s /contacts endpoint when you need to consume the data from external systems.

Frequently asked questions (FAQ)

When can I reserve my business’s username?

Reservation opens June 29, 2026 globally: any business worldwide can reserve its preferred username from that date. Reserving early protects your brand name before activation.

Where do I reserve or claim a username?

From three places: WhatsApp Manager, Meta Business Suite, or the Username API.

When does the username become usable in my country?

Activation happens in waves. Wave 1 (July 7): Algeria, Azerbaijan, Ghana, Libya, and Nepal. Wave 2 (July 20): Colombia, Singapore, Peru, Malaysia, and the Dominican Republic. Global availability: end of August 2026. Reserving the username does not depend on the wave; usability does.

I’m an API-integrated client — what do I need to keep in mind?

In addition to reserving the username, make sure your systems support Business-Scoped User IDs (BSUIDs) alongside phone numbers. The technical details are in Meta’s documentation.

Where can I find the BSUID and the phone number within Botmaker?

In four places, as long as the BSUID is available: in the contacts screen; in the webhooks; in code actions (context.userData.bsuid and context.userData.whatsappNumber); and via API, downloading contacts through the /contacts endpoint.

How will notifications be sent?

Businesses will be able to reference WhatsApp conversations and send notifications using three types of identifiers: ChatID, phone number, or BSUID.

What happens if a user doesn’t want to share their phone number? How are templates sent to them?

If the user chooses to hide their number, the business will receive their BSUID. You can keep sending outbound campaigns or messages through the API using this identifier. If for operational reasons you need the number, you can request it via a utility or marketing template. You can also, and this is now available, ask for it within the conversation with the Request contact details action: learn how in the article Request contact details: ask users who reach out without sharing it for their phone number.

Will it still be possible to send templates to users with a phone number?

Yes. If you already have the WhatsApp number registered from prior interactions, Botmaker will keep both data points (phone number and BSUID). In addition, for existing contacts, the number will remain visible and usable if the user is already in your Meta contact book.

How will templates continue to be sent?

The technical process stays similar, but with more flexibility in the identifier. Marketing campaigns and utility messages can be triggered using the BSUID. Authentication templates (OTP) will not change and can be sent only by phone number, not by BSUID.

What is the exact variable within Botmaker that will bring the BSUID in WhatsApp conversations?

The variable is ${bsuid}. It is already available on the platform. Within code actions, the same data is available in context.userData.bsuid.

Is there a variable that contains the phone number when the user shares it?

Yes. The ${whatsappNumber} variable is populated with the number only when the user shares it explicitly. If they never shared it, it will stay empty. In code actions it is in context.userData.whatsappNumber.

Is there an API endpoint to download contacts with their BSUID?

Yes. Botmaker added the /contacts endpoint, which lets you download all contacts along with their BSUID and, when applicable, their phone number. It is already available.

Will the BSUID replace the current value of platformContactId, customerId, or another variable?

Yes, eventually. The platformContactId may start containing a BSUID instead of a number starting with the rollout; don’t assume a numeric format in the bot logic. The ${bsuid} variable always contains the BSUID, and ${whatsappNumber} always the number (when available).

Will CHAT_CHANNEL_ID still represent only the channel/chat?

It does not change. CHAT_CHANNEL_ID represents the customer’s line (the business), not the user’s. It is not affected by the introduction of the BSUID.

In user-initiated conversations, should we assume that in some cases we’ll no longer receive the phone number?

Correct. With the progressive rollout, each time a user activates their username, the phone number will stop being available and only the BSUID will be exposed. There is no single global date: it depends on individual adoption and each country’s wave.

Will any changes be required in actions like trigger intent, change bot, master bot, or external-link authentications?

No changes are required in those actions. The only thing to keep in mind is that the platformContactId may stop being a phone number; any validation that assumes a numeric format should be adjusted.

If a contact I've already saved with their phone number messages me again and the interaction comes in with only the BSUID, will the contact be duplicated or will I lose the conversation history?

No, it won't be duplicated. Botmaker groups contacts by BSUID (unique and stable per user/business) and keeps both the phone number and the BSUID. Since the BSUID is already linked to your existing contacts, the new interaction is tied to the same historical profile: no duplicates and no loss of history.

To request the phone number within the flow, see the article “Request contact details: ask users who reach out without sharing it for their phone number”.

To register your username step by step, see the article “How to register your WhatsApp username in Botmaker”.

Remember to visit our Help Center for further information.