A business-scoped user ID. It uniquely identifies a WhatsApp user within the context of one business portfolio. Meta's June 10, 2026 documentation describes BSUIDs appearing in messages webhooks via the user_id field as part of the early April 2026 rollout.

What is the difference between wa_id and user_id?

wa_id is the user's phone number. user_id is the user's BSUID. After WhatsApp user usernames launch, wa_id may be omitted from webhooks if the user has a username and none of Meta's phone-number inclusion conditions are met. user_id is the stable identifier for your integration.

Will I lose access to my existing customers' phone numbers?

Not automatically, but you must stop assuming phone numbers always appear. Phone numbers can still appear after qualifying message or call interactions within the last 30 days, or when the user is stored in Meta's portfolio-level contact book. The contact book is populated from qualifying interactions after rollout; older interactions are not retroactively imported. For users who adopt usernames and fall outside these conditions, use REQUEST_CONTACT_INFO flows to request their phone number.

Do I need to change my webhook handler code?

Yes. Your code should handle webhooks where wa_id, from, recipient_id, or phone_number fields may be absent, and it should capture user_id plus parent_user_id when present. Messages API and Marketing Messages API support BSUID recipients through the recipient field, while phone-number sends still use to.

How does the BSUID transition affect authentication messages (OTP)?

One-tap, zero-tap, and copy-code authentication templates still require phone numbers. BSUIDs cannot be used for these message types. Error code 131062 is returned if you attempt to use a BSUID for an unsupported message type.

What is the WhatsApp contact book?

A Meta-managed, portfolio-scoped feature that stores phone number and BSUID pairs from qualifying message and call interactions after rollout. If a user is in your contact book, their phone number can continue to appear in webhooks even after they adopt a username. Disabling the feature deletes the stored entries.

WhatsApp BSUID, Usernames and Contact Book Transition Guide

Overview of Meta's WhatsApp BSUID rollout: usernames, contact book behavior, parent BSUIDs, API recipient support, webhook changes, and migration timeline.

WhatsApp is adding usernames and business-scoped user IDs (BSUIDs) so a user can interact with businesses without always exposing a phone number in API payloads. This guide is the overview. The detailed implementation references are split into dedicated pages:

What's Changing

Historically, most WhatsApp Cloud API integrations used phone numbers as the main user identifier: wa_id in webhooks and to in send requests. Meta is moving toward a model where WhatsApp users can adopt optional usernames. When a user has a username, their phone number may be omitted from API payloads unless one of Meta's phone-number inclusion conditions applies.

To keep API integrations working, Meta is adding business-scoped user IDs, or BSUIDs. A BSUID uniquely identifies a WhatsApp user within the context of a business portfolio. It appears in webhook payloads as user_id and can be used as a recipient identifier on supported API requests.

BSUIDs appear whether or not the user has adopted a username. Usernames control phone-number visibility in the app and in some payloads; BSUIDs are the backend identifier you use for continuity.

Timeline

Meta updated its BSUID documentation on June 10, 2026. Exact rollout dates remain subject to Meta changes.

Timing	Change
Early April 2026	BSUIDs begin appearing in messages webhooks.
Early April 2026	Meta contact book starts rolling out.
May 2026	Messages API and Marketing Messages API add BSUID recipient support.
Early May 2026	`REQUEST_CONTACT_INFO` support becomes available for requesting phone numbers.
Later 2026	WhatsApp user usernames become available.
Later 2026	Business username adopt/change APIs become available.

If your production behavior depends on a specific rollout date, confirm current availability in Meta's live documentation and in your App Dashboard test webhooks.

Identifier Model

Identifier	Meaning
`wa_id`	The user's phone number. Can be omitted when the user has a username and phone-number inclusion conditions are not met.
`user_id`	The user's BSUID scoped to one business portfolio.
`parent_user_id`	A parent BSUID shared across enrolled business portfolios. Only present for eligible managed businesses that have enrolled.
`username`	The user's optional WhatsApp username. Changing it does not change phone number or BSUID.
`recipient`	New API request field that accepts a BSUID or parent BSUID on supported endpoints.
`to`	Existing phone-number recipient field. If both `to` and `recipient` are sent, `to` takes precedence.

BSUID format is a two-letter ISO 3166 alpha-2 country code, a period, and up to 128 alphanumeric characters, for example US.13491208655302741918. Parent BSUIDs add ENT after the country code, for example US.ENT.11815799212886844830.

Use the full BSUID value exactly as received. Do not strip the country code or period.

Implementation Areas

Webhook Parsing

Update webhook handlers so they do not require phone-number fields. Incoming messages, statuses, system events, contact messages, user preferences, groups, calls, history, and app echoes can all carry BSUID-related fields.

Start with BSUID webhook changes.

Sending and API Requests

Supported APIs add recipient for BSUID or parent BSUID sends. Phone-number sends still use to, and to wins if both are present.

Start with BSUID API and sending changes.

Contact Recovery

If you still need phone numbers, use Meta's contact book behavior and REQUEST_CONTACT_INFO flows rather than assuming wa_id always exists.

Start with BSUID contact book and contact requests.

Multi-Portfolio Identity

If you operate multiple business portfolios and need one stable user identifier across them, evaluate parent BSUIDs.

Start with Parent BSUIDs.

Business Username Management

Business usernames are separate from user privacy usernames. They make a business searchable by username, but they do not hide the business phone number.

Start with WhatsApp business usernames.

When Phone Numbers Still Appear

If a user enables a username, their phone number is still included in webhooks when at least one of these conditions applies:

You have messaged or called the user's phone number within the last 30 days of the webhook.
You have received a message or call from the user's phone number within the last 30 days of the webhook.
The user is in your Meta-hosted contact book.

The 30-day lookback is evaluated per business phone number. If one number in a portfolio interacted with the user, that does not automatically make the phone number appear for webhooks tied to another business phone number. The contact book is portfolio-scoped and can make phone numbers available across phone numbers in the same portfolio once populated.

Dualhook Boundary

Dualhook uses Webhook Override so message-path webhooks go directly from Meta to your endpoint. That matters for BSUID adoption:

Dualhook does not ingest your messages webhooks.
Dualhook does not store BSUIDs from message-path payloads as product data.
Dualhook does not populate or manage Meta's contact book for you.
Dualhook does not migrate your CRM identifiers automatically.
Dualhook can help by documenting the field changes, surfacing operational context, and providing the BSUID Transition Checker.

Your webhook receiver, CRM, campaign tools, support tools, and analytics pipelines must be updated to store and join on BSUIDs.

Migration Checklist

Add user_id and parent_user_id columns or equivalent identifier storage.
Stop treating wa_id, from, recipient_id, and phone_number as required fields.
Update inbound message, status, system, group, calling, history, echo, and preference webhook parsers.
Update send code to support recipient while keeping to for known phone numbers.
Handle error 131062 for message types that do not support BSUID recipients.
Decide how your CRM maps phone numbers, BSUIDs, parent BSUIDs, and usernames.
Add contact-request flows if your business process still needs phone numbers.
Test username and no-phone-number scenarios in App Dashboard webhook testing.

FAQ

What is a BSUID?

A business-scoped user ID. It uniquely identifies a WhatsApp user within one business portfolio and appears as user_id in webhook payloads.

Is a BSUID global?

No. A regular BSUID is scoped to a business portfolio. The same WhatsApp user has different regular BSUIDs for different business portfolios. Parent BSUIDs are the cross-portfolio option for eligible managed businesses.

Does a username change the BSUID?

No. A user can change their username without changing their phone number or BSUID. A phone-number change can regenerate the BSUID.

Can I keep using phone numbers?

Yes, when you know the phone number and Meta is allowed to include it. For supported sends, to still works and takes precedence over recipient. Your webhook parser still needs to handle payloads where the phone number is omitted.

Can I use BSUIDs for authentication templates?

Not for one-tap, zero-tap, or copy-code authentication templates. Those still require phone numbers. Meta returns error 131062 when a BSUID recipient is unsupported for the message type.

Does Dualhook see or store my customers' BSUIDs?

Not for message-path traffic. Meta routes message webhooks directly to your server through Webhook Override, and Dualhook does not store those payloads.

Meta BSUID, Usernames & Contact Book Transition Guide