WhatsApp Usernames and Business-Scoped User IDs: The 2026 Migration Guide

Meta’s WhatsApp username work changes a basic API assumption: a customer phone number is no longer guaranteed to be visible. Business Scoped User IDs (BSUIDs) are now mandatory and are scoped to the Meta business portfolio that owns the WhatsApp number.

This is not merely a new discovery feature. It affects contact keys, inbound webhooks, delivery statuses, outbound recipients, migrations, and authentication templates.

What developers must change

• Treat the webhook user_id as the WhatsApp identity and from as an optional phone address.
• Namespace raw BSUIDs by business portfolio. The same raw value must never be assumed globally unique.
• Subscribe to and process Meta’s user_id_update webhook.
• Read recipient_user_id from delivery-status webhooks.
• Send phones through Meta’s to field and BSUIDs through the dedicated recipient field. Prefer the phone value when you know both.
• Keep authentication-template sends on phone-number recipients. Meta’s one-tap, zero-tap, and copy-code authentication flows require a phone.
• Use REQUEST_CONTACT_INFO when your workflow genuinely needs the user’s phone number.

Meta may temporarily return a phone after a recent interaction or when it is in the business contact book. That does not make the phone permanent or suitable as the identity key.

What Wabery changed

Wabery now stores WhatsApp identities in a business-portfolio namespace, reconciles user_id_update, backfills identity data from message statuses, and supports phone-hidden conversations without changing the existing API version.

For webhook consumers:

• contact_id remains the stable Wabery key.
• from remains a phone or null; Wabery never places a BSUID in that field.
• user_id, parent_user_id, and username expose Meta identity data.
• contact.identity.updated announces a migrated BSUID.
• Contact-card and system messages are exposed as contacts and system types.

Business username management is available through the channel API and SDK, including Meta suggestions, reserve/change, transfer, delete, current status, and channel.username.updated events. A business username improves discovery; Meta explicitly does not use it to hide the business phone number.

Do existing clients break?

Existing phone-number workflows continue unchanged, and no API-version fork is necessary: no endpoint or existing field is removed or renamed. Wabery still uses the phone-number value in Meta’s to field whenever a phone is known. For conversation-addressed sends to a phone-hidden contact, it maps the stored BSUID to Meta’s dedicated recipient field. The public to input remains an E.164 phone-number input.

Webhook consumers still need a compatibility check before rollout. Clients that already join on contact_id, accept nullable phone fields, and tolerate additive events continue to work. Clients that require from or recipient_id to be an E.164 string—or reject an unknown event name—must remove those assumptions. In particular, accept and acknowledge contact.identity.updated, even if you do not mirror Meta identities.

The safe pattern is straightforward:

const appContactId = event.payload.contact_id;
const phone = event.payload.from;       // string | null
const whatsappUserId = event.payload.user_id ?? null; // string | null

Use the phone only for workflows that require a phone, and ask the user to share it when necessary.

Source of truth

This implementation follows Meta’s official WhatsApp Business Scoped User IDs documentation. Provider-specific transport documentation does not define WhatsApp identity semantics.

Read the Wabery implementation guide for webhook, SDK, REST, and contact-info examples.