WhatsApp BSUIDs and usernames: what developers need to change in 2026

Meta is rolling out WhatsApp usernames in 2026. To support that, the WhatsApp Business Platform is adding a new identity field: the business-scoped user ID, usually shortened to BSUID.

For developers, this is not a cosmetic change. WhatsApp identity can no longer be treated as “always a phone number.” Inbound webhooks can include BSUIDs, usernames can appear in payloads, and phone numbers can be missing in some username-related cases.

If your product stores WhatsApp contacts, routes conversations, syncs CRM records, or runs automations from inbound messages, you should update your identity model now.

TL;DR

• A BSUID identifies a WhatsApp user inside a specific business portfolio.
• BSUIDs started appearing in inbound webhooks in early April 2026.
• Phone numbers can be omitted from some webhook payloads when users adopt usernames.
• Store BSUIDs and usernames, but do not treat usernames as stable IDs.
• Match contacts by BSUID first, then phone number.
• Make phone-number fields nullable where your system reads inbound WhatsApp identity.
• In Kapso, inbound/read/workflow surfaces expose BSUID fields. Keep outbound sending phone-based unless Kapso documents otherwise.

Why BSUIDs exist

WhatsApp usernames let users show a username instead of their phone number in the app. That creates a platform problem: businesses still need a stable way to identify a user even when the phone number is not available in every payload.

BSUIDs solve that problem. They are backend identifiers tied to the pair of:

• a WhatsApp user
• a business portfolio

That scope matters. The same WhatsApp user can have different BSUIDs for different business portfolios. A BSUID from one portfolio should not be assumed to work with a phone number owned by another portfolio.

Timeline

As of June 6, 2026, this is the practical timeline developers should use:

The safe interpretation is: prepare your inbound systems now; be conservative with outbound BSUID sends until your provider’s public contract says they are supported.

What a BSUID looks like

A normal BSUID uses a country-code prefix followed by a period and an identifier:

US.13491208655302741918

Some managed businesses can also receive parent BSUIDs, which are designed to work across enrolled business portfolios:

US.ENT.11815799212886844830

You should store both when they appear, but for most single-portfolio integrations, the normal business_scoped_user_id is the primary identity field.

New identity fields to expect

Depending on the surface, you may see fields like:

Kapso exposes these as additive fields on the relevant read, webhook, and workflow surfaces:

Workflow context can also include:

context.whatsapp_business_scoped_user_id
context.whatsapp_parent_business_scoped_user_id
context.whatsapp_username

Phone numbers can be missing

This is the part that breaks old integrations.

If a user enables a WhatsApp username, their phone number may not be included in webhook payloads unless one of the documented exceptions applies. The main exceptions are recent interactions with that user’s phone number or the user being present in Meta’s contact book.

That means an integration should handle all of these shapes:

• phone number and BSUID together
• BSUID with no phone number
• username with BSUID and no phone number
• status webhook with a recipient BSUID
• identity-change events that connect old and new identifiers

If your database requires phone_number NOT NULL for every WhatsApp contact or conversation, the rollout can create bad behavior: dropped events, duplicate contacts, broken conversation routing, or CRM records that fail to sync.

Recommended data model

Treat WhatsApp identity as a set of identifiers, not one field.

At minimum, store:

• phone_number
• wa_id
• business_scoped_user_id
• parent_business_scoped_user_id
• username
• business_portfolio_id when you need to reason about scope

Then update your matching order:

1. Match by business_scoped_user_id when present.
2. Match by parent_business_scoped_user_id when your business case uses parent accounts.
3. Match by wa_id or phone number when present.
4. Merge identities when a later payload proves they belong to the same logical contact.

Do not key your entire WhatsApp user model by phone number anymore.

Identity-change events

Meta can send identity-change signals such as user_id_update and user_changed_user_id.

If you only use Kapso’s normalized contact, conversation, and message records, Kapso handles identity reconciliation internally for its own surfaces.

If you mirror WhatsApp identity into your own database or forward raw Meta webhooks into your own system, treat these events as reconciliation events:

• update the existing user/contact record
• keep historical identifiers where they are useful for auditing
• avoid creating a brand-new customer blindly
• move your primary matching logic toward BSUID-first lookup

What Kapso handles today

Kapso already exposes BSUID and username fields across relevant inbound and read surfaces:

• conversations
• contacts
• messages
• webhook payloads
• workflow context
• inbox identity display

Kapso also supports nullable phone identity internally, so a contact or conversation can still be represented when Meta provides BSUID-based identity without a phone number.

For outbound sends, use the conservative public contract: keep sending by phone number unless Kapso’s docs for your specific API surface say BSUID targeting is supported.

Migration checklist

Use this as a practical engineering checklist:

• Add columns for business_scoped_user_id, parent_business_scoped_user_id, and username.
• Allow phone-number fields to be nullable on inbound identity records.
• Update webhook parsers so they do not require from, to, wa_id, or phone_number in every event.
• Match by BSUID before phone number.
• Handle identity-change events if you consume raw Meta webhooks.
• Update CRM sync logic so missing phone number does not drop the contact.
• Update workflow and agent context so agents can read BSUID fields when present.
• Test with payloads that include BSUID only.
• Keep outbound sending phone-based until your provider’s documented API contract changes.

Common mistakes

Treating username as a primary key

Usernames can change. They are useful for display and sometimes personalization, but they are not the stable identity key. Use BSUID for identity.

Assuming BSUIDs are global

They are not global user IDs. They are scoped to a business portfolio. Do not mix BSUIDs across portfolios or assume one provider’s BSUID can be used from another provider’s phone number.

Making phone number nullable in one table but not the rest

The failure usually appears downstream. You may update contacts, but your automation table, CRM mapping table, or conversation routing logic may still assume a phone number is always present.

Claiming full outbound BSUID support too early

Meta’s rollout and provider support are not the same thing. Even if Meta exposes a capability, your provider’s API may not expose the same send contract yet.

Bottom line

The WhatsApp identity model is becoming less phone-number-centric.

Developers should move to a BSUID-aware model now: store the new fields, make phone identity nullable, match by BSUID first, and keep outbound sends on the documented path for your provider.

For Kapso users, the immediate action is simple: update any external parser, CRM sync, or custom workflow logic that assumes every WhatsApp user always has a phone number.