Starting in June 2026, the WhatsApp Business Platform will introduce significant changes to how businesses identify and communicate with their users. This evolution is designed to prioritize privacy, allowing people to interact with businesses without having to share their phone number.

You can:

• Identify your WhatsApp users with the new BSUID, even when they don't share their phone number.
• Consume the BSUID and 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-business combination. It is an alphanumeric string of up to 128 characters.

Username: a public username that each person can enable 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 on 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' phone numbers visible once they enable their username.

What is the BSUID?

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

• It is an alphanumeric string of up to 128 characters. It uses the user's two-letter country code as a prefix, following the ISO 3166 alpha-2 standard, 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 "Company A" will be different from their ID for "Company B."

Meta's confirmed timeline

There is no global "shut-off" date for the phone number. The number becomes unavailable on the platform on an individual basis, when each user enables 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 → The possibility that end users will not share their phone number (username launch). Before this date, current behavior remains unchanged.
• Later in 2026 → Widespread adoption of usernames by end users.

Note: When a user enables their username, their phone number becomes unavailable to the business, unless there has been interaction in the last 30 days, they are in the company's contact book, or other exceptions defined by Meta apply.

Official Meta documentation: Business Scoped User IDs

Impact on the Botmaker platform

Botmaker is adapting to make this transition seamless:

• Chats: the BSUID information will always be visible.
• Contacts: the BSUID appears in the user's profile within the contacts screen (available as of this week), and contacts are grouped by BSUID to keep 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 chat, search for chats, or send templates using either the phone number or the BSUID, and the platform will handle the rest.

Consuming information on the platform

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

As long as the BSUID is provided, you'll find the data in four places:

• Contacts screen: the BSUID appears in the user's profile (available as of this week).
• Webhooks: they include the phone number and the BSUID.
• Code actions: available in context.userData.bsuid and context.userData.whatsappNumber.
• API: you'll be able to download contacts with their phone number and associated BSUID through the /contacts endpoint (Contacts API — now available!).

Variables available on the platform

With this change, Botmaker works with three key variables worth understanding 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 your bot flows.
• Contact ID / platformContactId (the user's ID on the channel) → will contain the user's phone number when available. If the user never shared their phone number, 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 (for example, through a contact-request flow). If the user never shared it, this variable will be empty.
• CHAT_CHANNEL_ID → does not change. It still represents the business's line, not the user's.

Note: After 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 data in code actions

The BSUID and 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 any additional configuration.

Information available via API

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

The endpoint:

• Adds to the set of already available endpoints (/chats, /e-commerce, etc.).
• Lets you retrieve all of the account's contacts along with their BSUID and, when available, their phone number.
• Its documentation is added automatically 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 for chats, and other operations.

Information in webhooks

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

Usage recommendations

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

• Use the Contact ID as your primary identifier in your flows and integrations. The platform will automatically resolve whether it corresponds to the phone number or the BSUID depending on the case.
• Don't build your flows on the guarantee of having a phone number. As users enable their usernames, the phone number will become unavailable for a growing share of contacts.
• Avoid asking the user for their phone number unless it's strictly necessary (for example, for physical shipping of products 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.

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 campaigns. The notification can still be sent, but via BSUID.

Not affected:

• User-initiated conversations: when the customer messages 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 company affected.
• Users who consented: customers who, after June 2026, have explicitly agreed to share their phone number.
• Existing flow actions: trigger intent, change bot, master bot, and authentications via external links require no changes. The only thing to keep in mind is that the platformContactId or the "user's ID on 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 through the ChatID, the phone number, or the new BSUID.

For contacts that already have a number on file from previous interactions, Botmaker will keep both pieces of data to ensure service continuity.

What should companies do to adapt to this change?

To avoid disruptions, we recommend following these steps:

1. Update databases: expand the ID fields in your systems from 15 to 128 alphanumeric characters to support the BSUID format.
2. Identity mapping: prepare your CRM to record the BSUID as well as the phone number and email, linking them to a single customer profile.
3. Enable the contact book: in June 2026, configure the Contact Book feature in Meta Business Suite to ensure your current customers' numbers remain visible.
4. Redesign flows: adjust your bots so they can initially operate with only the BSUID, without necessarily depending on the phone number to function.

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 take advantage of the API's /contacts endpoint when you need to consume the data from external systems.

Frequently Asked Questions (FAQ)

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

In four places, as long as the BSUID is provided: on the contacts screen (it appears in the user's profile, available as of this week); in the webhooks (they include the phone number and BSUID); in the code actions (available in context.userData.bsuid and context.userData.whatsappNumber); and via the API, downloading contacts with their phone number and associated BSUID through the /contacts endpoint.

How will notifications be sent?

Companies will be able to reference WhatsApp conversations and send notifications using three types of identifiers: ChatID, phone number, or BSUID. The platform will let you load any of these to start or maintain communication.

What happens if a user doesn't want to share their phone number? How do you send them templates?

If the user chooses to hide their number, the company will receive their BSUID. You can keep sending outbound campaigns or messages through the API using this identifier instead of the phone number. If, for operational reasons (such as a physical shipment or legal validation), you need the number, you can request it from the user via a utility or marketing template designed to capture that data.

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

Yes. If you already have the WhatsApp number on file from previous interactions, Botmaker will keep both pieces of data (phone number and BSUID). In addition, for existing contacts, the phone 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 greater flexibility in the identifier. Marketing campaigns and utility messages can be triggered using the BSUID. Note that authentication templates (OTP) will not change in their basic operation. These can be sent only by phone number and not by BSUID.

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

The variable is ${bsuid}. It's already available on the platform and you can use it in your bot flows. 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 filled with the phone number only when the user shares it explicitly (for example, through a flow that requests the contact). If the user never shared their number, this variable will remain empty. Within code actions, the same data is available in context.userData.whatsappNumber. This is the recommended way to capture and store phone numbers after the rollout.

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

Yes. Botmaker has added the /contacts endpoint, which lets you download all of the account's contacts along with their BSUID and, where applicable, their phone number. The Contacts API is now available and its documentation is published automatically along with the rest of the API.

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

Yes, eventually. The platformContactId or "user's ID on the channel" may start containing a BSUID instead of a phone number after the rollout — we recommend not assuming a numeric format in your bot logic. The ${bsuid} variable always contains the BSUID, and ${whatsappNumber} always contains the number (when available).

Will CHAT_CHANNEL_ID continue to represent only the channel/chat, or could it also change with this update?

It does not change. CHAT_CHANNEL_ID represents the business's line, not the user's. It is not affected by the introduction of the BSUID.

Is there a real example of a payload, code action, or platform variable where the BSUID is already visible?

Yes. It's already available on the platform and can be tested today through the ${bsuid} variable, in the contact's profile, in the webhook payload, and within code actions via context.userData.bsuid and context.userData.whatsappNumber.

In user-initiated conversations, should we assume that in some cases we will no longer receive the phone number and only the BSUID will arrive?

Correct. With the progressive rollout, each time a user enables their username, the phone number will become unavailable on the platform and only the BSUID will be exposed. There is no single global date — it depends on each user's individual adoption.

For historical contacts, will Botmaker keep exposing both pieces of data (phone number and BSUID) in variables usable within the bot?

Yes. For contacts with previous interactions, Botmaker will keep both the phone number and the BSUID accessible, and both can be used to send notifications.

Is there additional technical documentation, a changelog, a manual, or an expanded FAQ beyond this article?

For now, no additional technical documentation has been published. The Botmaker team is preparing supplementary material that will be shared as the rollout progresses. The official reference source is Meta's documentation on Business Scoped User IDs.

Is there a way to validate this behavior in a test or development environment before the general rollout?

The deployment is general; no separate testing environment is offered. Validation is done directly on the platform using the ${bsuid} variable that is already available.

Will any changes be required in actions such as trigger intent, change bot, master bot, or authentications via external links?

No changes are required in those actions. The only thing to keep in mind is that the platformContactId or the "user's ID on the channel" may stop being a phone number — any validation or logic that assumes a numeric format should be adjusted.

Remember to visit our Help Center for further information.