WhatsApp Business-Scoped User ID BSUID changes how businesses identify customers across the WhatsApp Business Platform. Prepare your webhooks, CRM keys, and message
routing for the new scoped identifier before phone numbers disappear from payloads.
WhatsApp is introducing usernames and a new backend identifier called the Business-Scoped User ID, or BSUID, across the Business Platform in 2026.
Any WhatsApp Business API integration, chatbot, CRM sync, or SaaS platform that assumes every customer is identified only by a phone number
needs to update how it stores, matches, and messages users.
Businesses that do not prepare risk broken customer records and missed delivery when phone numbers disappear from payloads.
WhatsApp Business-Scoped User ID BSUID: what is changing
Meta documented these changes as part of the WhatsApp Business Platform BSUID rollout. Here is what matters for your integration:
New identifier formatEvery WhatsApp user gets a BSUID: a two-letter country code, a period, then up to 128 alphanumeric characters
(example: US.13491208655302741918).
Assigned automaticallyBSUIDs appear in the user_id field of every messages webhook, whether or not that user has set a username.
Scoped to your portfolioA BSUID only works with phone numbers inside the same business portfolio. Using it from a different
portfolio's number fails the request.
Parent BSUID for linked accountsManaged businesses with linked portfolios also receive a parent_user_id, formatted with .ENT. in the middle, that
works across every linked number.
Phone numbers can disappearOnce a user adopts a username, their phone number only appears in webhooks if you messaged them,
they messaged you, or they are in your contact book within the last 30 days.
Staged rolloutBSUIDs began appearing in webhooks in April 2026. Sending messages by BSUID follows from May 2026. Usernames themselves roll
out later in the year.
Mandatory for partnersSupporting BSUID is required for Business Platform partners, directly integrated businesses, and click-to-WhatsApp ad advertisers.
Regenerates on number changeIf a user changes their WhatsApp phone number, their BSUID regenerates and a system webhook fires. Old
identifiers stop working.
Where Integrations Get Stuck Phone number as the primary key Most CRMs, chatbot platforms, and order systems use the phone number as
the unique customer identifier.
When a webhook withholds that number, the integration either creates a duplicate contact or drops the message entirely.
Webhook parsers built for the old payload shape user_id, parent_user_id, recipient_user_id, and from_user_id are new fields spread across incoming messages,
status updates, group events, and system webhooks.A parser that only reads wa_id or from will silently miss data on any
payload that omits the phone number.
Third-party tooling lags behind Open-source WhatsApp libraries and older Business Solution Provider integrations are still catching up to BSUID support,
which means the gap between whatMeta ships and what your stack handles often has to be closed manually.
Multi-portfolio confusion Businesses running several WhatsApp Business Accounts under one company need to decide whether to enable parent BSUIDs, then
handle both regular andparent identifiers correctly across every number.
How a BSUID-Ready Migration Is Approached 1 Audit every place phone numbers are used as an identifier: database schema, CRM sync, chatbot
logic, and analytics. 2 Map the exact webhook and API response fields affected for your account type: standard versus parent BSUID, solution
provider versus direct business. 3 Update identity storage and matching logic so BSUID and phone number can both resolve to the same
customer record. 4 Run every scenario in Meta's webhook testing tool: no username, username with phone visible, username with phone hidden, and
parent BSUID. 5 Schedule the cutover around Meta's staged rollout dates so nothing breaks mid-conversation with a live customer. Webhook changes since
April 2026, BSUID messaging from May 2026 What a Correct Migration Gets You No customer conversation loses its history when a phone
number is withheld from a webhook Delivery and read receipts keep matching to the right customer even after a BSUID changes Your
integration stays aligned with Meta's BSUID support requirement for partners and advertisers Support and CRM teams stop seeing unknown-contact tickets caused by
missing phone numbers Common Mistakes Businesses Make With BSUID Hardcoding the phone number field and ignoring user_id and from_user_id entirely Treating a
BSUID as permanent, when it regenerates whenever a user changes their WhatsApp number Sending messages using only the phone number parameter and
never testing the newer BSUID recipient parameter Not subscribing to the user_id_update webhook, so identifier changes go unnoticed Assuming parent BSUID and
regular BSUID are interchangeable, when each is scoped differently Compare your rollout plan with the official WhatsApp Cloud API webhook documentation before
deploying identifier changes.
The WhatsApp Business-Scoped User ID BSUID should become a first-class identity in webhook parsing and customer records, not a temporary field used
only during the rollout.
For a reliable WhatsApp Business-Scoped User ID BSUID migration, keep the scoped identifier and phone number available together while your CRM matching
logic is updated.
Test the WhatsApp Business-Scoped User ID BSUID with message, status, and user-id update webhooks before enabling the change for every number.
Document how the WhatsApp Business-Scoped User ID BSUID maps to a contact, conversation, and portfolio so support teams can trace records after
a number change.
A production-ready WhatsApp Business-Scoped User ID BSUID implementation should cover linked portfolios and parent identifiers instead of assuming one scope fits every
account.
Pair the WhatsApp Business-Scoped User ID BSUID rollout with the WhatsApp Cloud API rate-limit guidance so identity migration and delivery monitoring are
reviewed together.
If a WhatsApp Business API integration still assumes a phone number is always available, 2026 is the year that assumption breaks. Auditing
webhook handling, identity storage, and permission scopes against BSUID is part of the WhatsApp Cloud API setup and support work handled here.
Read the official WhatsApp Cloud API webhook documentation for rollout details.
See our WhatsApp Cloud API rate-limit guide for related delivery checks.
Need Us to Get Your Meta App 100% Approved?
Stop losing weeks to repeated rejections. With 500+ apps approved, we handle your entire submission from start to finish. You get 100% Approval or a 100% Refund — and for your complete safety, you can hire us directly through Upwork or Fiverr Escrow (or use the WhatsApp / Calendar buttons in the header & footer).
Chat on WhatsApp