Whatsapp usernames & BSUIDs¶

In 2026 Meta is rolling out a major change to the WhatsApp Business Platform: end users can adopt a username and hide their phone number from the businesses they chat with. To keep messaging working, Meta introduces a new identifier called a Business-Scoped User ID (BSUID) that takes the place of the phone number in webhooks and API calls.

This page summarises what this change means for bot creators on our platform. For the underlying technical specification see the Meta documentation on BSUIDs and the 360dialog overview article.

TL;DR

Most bots keep working. Users that don't adopt a username still arrive with their phone number, exactly like today.
For users that do adopt a username, your bot may no longer receive their phone number. The user.phone variable will then be empty.
The user identifier our platform uses (visible in conversations and in user.user_id) will be a BSUID such as US.13491208655302741918 instead of a phone number like 16505551234 for those users.
Existing customers are protected automatically by Meta's Contact Book: phone numbers we already received in the last 30 days, or that were captured by the Contact Book, keep flowing through in webhooks.
Action: claim your reserved business username, and audit any bot logic that assumes user.phone is always set.

Timeline¶

Meta is rolling out the change in phases throughout 2026. The dates below come from Meta and 360dialog and may shift.

Date	What happens
March 16, 2026	Contact Book setting visible in Business Manager (leave it enabled — default on).
March 31, 2026	BSUIDs appear in all live webhook responses, alongside phone numbers. Observation window.
April 2026	Contact Book starts recording phone ↔ BSUID mappings automatically.
May 2026	WhatsApp APIs start accepting BSUIDs as a message recipient.
June 2026	Username adoption begins for end users in test countries.
H2 2026	Gradual global rollout to end users and businesses.

During April–June you will see BSUIDs appear in webhooks, but until users start adopting usernames in June there is no functional change to your bot.

What changes for your bot¶

The user identifier¶

Today, every WhatsApp conversation in our platform is keyed by the user's phone number (their wa_id). For username-adopted users, Meta no longer sends the phone number in the webhook. Instead the conversation is keyed by the BSUID:

US.13491208655302741918

The first two characters are the user's ISO-3166 country code, followed by a period and an opaque numeric identifier. BSUIDs are unique per business portfolio — the same end user has a different BSUID with every business they talk to.

Practical consequences for bot creators:

user.user_id (the identifier you see in the inbox and in the REST API) will be the BSUID for username-adopted users. Existing users keep their numeric phone-based identifier.
A user that switches from phone-only to having a username will keep their existing conversation as long as the Contact Book has their phone number on file (see Conversation continuity below).
If you store or sync user IDs to an external system (CRM, data warehouse, authentication backend) you must treat both formats as valid identifiers.

`user.phone` may be empty¶

Several built-in variables and helpers depend on the phone number. They will behave differently for username-adopted users that have no phone available:

Variable / helper	Behaviour for username-only users
`user.phone`	Will be empty if Meta does not include the phone number in the webhook.
`user.locale`	Cannot be inferred from the dial prefix; falls back to the bot default.
`sms(user.phone, ...)`	Will fail to send because there is no phone number to send to.
`show contact(user.phone, ...)`	Cannot pre-fill the user's own number.
The `__error__` SMS fallback	Will not work; see the error handling pattern.

Always guard logic that depends on the phone number, for example:

dialog __error__ when error.action do
  if user.phone do
    sms(user.phone, "We cannot reach you on WhatsApp, here is an SMS fallback.")
  else
    log "No phone number available for user #{user.user_id}, skipping SMS fallback."
  end
end

Asking the user for their phone number¶

If your flow genuinely needs the phone number (for an SMS fallback, identity verification, third-party integration, …) you can request it explicitly inside the WhatsApp chat using a request contact information button. Tapping the button shares the user's phone number (and only the phone number) with your bot through a contacts webhook, and adds the user to your Contact Book so future messages also include their phone.

This is the recommended way to recover the phone number for username-adopted users once the feature lands.

Profile name and username¶

The user's WhatsApp profile name is still mapped to user.first_name and user.last_name exactly like today. In addition, when a user has adopted a username it is exposed to BubbleScript as user.username (for example @pablomorales). Usernames can change at any time, so do not use them as a stable identifier — always key your records on user.user_id (which is the BSUID for username-only users) instead.

dialog main when message do
  if user.username do
    say "Hi #{user.username}!"
  else
    say "Hi #{user.first_name}!"
  end
end

Conversation continuity (Contact Book)¶

Meta provides a Contact Book that is enabled by default for every business portfolio. From April 2026 onward, every time we exchange a message with a user using their phone number, Meta stores the phone ↔ BSUID mapping. After that, Meta will keep including the phone number in webhooks even if the user later adopts a username.

The implications for bot creators:

For everyone you have already chatted with after April 2026, nothing visibly changes — user.phone keeps working.
For new contacts that arrive after adopting a username (typically through an unsolicited inbound message), only the BSUID is available until they share their phone number explicitly.
Keep the Contact Book enabled in Meta Business Suite → Business settings → Business info. Disabling it removes the mapping and reverts you to the BSUID-only behaviour for all future conversations.

Re-engagement and templates¶

The 24-hour re-engagement window keeps working: re-engagement templates can be sent to a BSUID, so a user that talked to your bot once will keep receiving operator messages and re-engagement prompts beyond 24 hours.

Multiple bots / business portfolios¶

BSUIDs are scoped to a business portfolio (formerly Business Manager). The same end user will have a different BSUID in each of your portfolios. If you run multiple bots or brands across separate portfolios and want a single identifier per user:

Ask your Meta point-of-contact to enrol your portfolios in a Parent BSUID account. Once enabled, every webhook will additionally contain a parent_user_id that is stable across all enrolled portfolios.
Until then, treat a user identified in one portfolio as a distinct contact from the same user identified in another.

Action items¶

Claim a business username. Before the username feature goes live in your country, log in to WhatsApp Manager or Meta Business Suite and either claim your reserved username or pick one that matches your branding. Your phone number is not hidden when you adopt a business username — only end-user usernames hide phone numbers.
Audit your bot for user.phone usage. Any dialog, integration or flow that assumes user.phone is always set must handle the case where it is empty. The SMS fallback pattern in error handling is the most common offender.
Audit external integrations. CRMs, data warehouses, support inboxes and any other system you forward conversations to must accept BSUIDs (strings such as US.13491208655302741918) as a valid user identifier in addition to phone numbers.
Plan an explicit phone-collection step for flows that truly require a phone number (SMS OTP, authentication templates, postal address verification, …). The native request contact information button is the recommended way to ask.
Keep the Contact Book enabled in Meta Business Suite so that existing customers keep arriving with their phone number after they adopt a username.
Review authentication-template flows. One-tap, zero-tap and copy-code templates will not work for username-only users. Provide a fallback.
Locale fallbacks. For users without a phone number, user.locale defaults to the bot locale. If language detection matters, rely on auto-translation or ask the user for their preferred language inside the conversation.

What does not change¶

To keep the picture balanced, the following continues to work exactly as documented in the WhatsApp channel guide:

All existing template types (text, interactive buttons, list, CTA URL, product, product list).
Sending and receiving media, contact cards, location pins.
The 24-hour conversation window and re-engagement template behaviour.
Delivery status tracking and the __error__ dialog (only the SMS fallback inside it needs to handle a missing phone).
Outbound messaging to existing customers whose phone numbers you already know.
Your business display name and business profile information shown in WhatsApp chats.

FAQ¶

Will my existing bots break in June 2026? No. Username adoption is gradual and opt-in for end users. Existing conversations keep their phone-based identifier, and the Contact Book bridges recently-active customers automatically. The only flows that can break are those that depend on the phone number for new username-adopted users.

Do I need to write code to handle BSUIDs? No bot-side code changes are required for the standard cases. The platform treats the BSUID as the user identifier transparently. Code changes are only required if you (a) use user.phone in a flow that should also work for username-only users, or (b) integrate with external systems that need to accept BSUIDs.

Can I message a user using their username? No. Usernames are a discovery feature for end users; businesses always message users using either a phone number or a BSUID. The username is shown in the WhatsApp app, not used as an API parameter.

Can a user change their username? Yes, periodically. Their BSUID does not change when they change their username, so the BSUID remains the correct stable identifier for your records.