WhatsApp API BSUID: no more customer phone numbers

WhatsApp API BSUID answers a question no integration used to have to ask: what happens when an inbound webhook has no phone number to hand you at all? Since April 2026 the answer is a stable per-business identifier. This piece treats that as the biggest identity change since this platform first launched, bigger than any single field addition, because the phone number stops being the one thing every message is guaranteed to carry.

Sending a message to a phone number already on file keeps working exactly as before; what changed is whether a brand-new inbound conversation is guaranteed to arrive with one. For the engineer who owns the WhatsApp send and webhook code, 1MSG, an official WhatsApp Business API platform, absorbs that shift for every channel it runs, so a contact layer built on the old assumption does not need a rebuild to keep functioning.

What actually changed: the phone number stops being the key

Every inbound WhatsApp message used to carry a phone number in the wa_id field, and CRMs, helpdesks, and campaign tools were built to key on it. Meta's optional WhatsApp usernames feature breaks that: a user hiding behind a username can send a message with wa_id absent, unless the business messaged or was messaged by that number in the last 30 days, or the Contact Book already has it on file.

Meta's own developer documentation spells out this 30-day visibility rule and the Contact Book exception in full, worth reading before assuming the phone field is gone for good. A phone number missing from the webhook is now the normal case to code for. Resolve a contact by BSUID first, then fall back to phone number: this BSUID-first matching is the pattern every phone-only integration now needs, because phone number is the field that can be absent here, never the other way around. Meta's documentation states the obligation directly: "Because you cannot control whether your users adopt usernames, you must support BSUID to avoid losing the ability to process their messages."

BSUID vs phone number, in plain terms

BSUID vs phone number is really a trade of portability for stability. A phone number was global, user-owned, and reusable across businesses: good for cross-channel matching, bad for privacy. A BSUID in WhatsApp Business API is an ISO country-code prefix plus up to 128 characters, for example US.13491208655302741918, scoped to one portfolio: the same person gets a different BSUID for every business they message.

The BSUID's per-portfolio scoping works in the business's favor: a BSUID issued to one portfolio simply fails if used against another, which keeps one business from resolving a user's identity in someone else's contact book. A BSUID survives a hidden phone number and a changed username; it just cannot travel outside the single relationship that issued it.

What breaks in an integration that only knows phone numbers

An integration that resolves contacts only by phone number breaks the moment a webhook arrives with a BSUID and no phone field at all. Chatwoot, an open-source customer engagement platform, hit this directly in production: a username-adopting user with no stored phone number would spawn a duplicate contact, and a reply could fail outright if the code assumed the incoming ID was always a phone number in E.164 format.

A completely different WhatsApp client hit the identical wall and asked for help on its own GitHub tracker — proof this isn't a one-off Chatwoot bug: "Now all users using a username do not return a phone number; they return just a lid. How to handle?" Chatwoot's fix, once it shipped, was to add BSUID as a second identifier next to the existing phone-keyed one rather than overwrite it, because that phone-based ID was the lookup key across "inbound processing, conversations, APIs, webhooks, and outbound sends" — the dual-key pattern any phone-only integration now needs to copy.

The CRM-scale cost: duplicate contacts and misrouted replies

A CRM that matches contacts strictly by phone number will file a BSUID-only message under a brand-new contact record, even for a returning customer, since there's no phone number in that payload to match against. Multiplied across a support queue, that's a real production failure mode, not a hypothetical one — it's why Azure Communication Services and Vonage each shipped dedicated BSUID migration guides once usernames appeared in the wild.

A username-only message with no phone number can land on a new contact instead of the customer's existing record.

A follow-up bug in Chatwoot's own tracker showed this is easy to get wrong even after a fix ships: merging two contacts in the dashboard left the conversation pointing at a stale routing identifier, so a reply could land with the wrong person, and the patch that closed it limited any identity update to only the identifiers named in that specific webhook event instead of touching the whole merged contact. It took at least 4 separate releases between March and August 2026 to get contact storage, rotation handling, and merge-safe routing right — a sign of how many edge cases one identifier change can surface.

How the BSUID-to-phone mapping keeps sends and webhooks working

A BSUID-to-phone mapping layer turns both failure modes above into a non-event: it stores both identifiers side by side, so a webhook with no phone field still resolves to the right contact, with no stale ID left to misroute a reply. 1MSG has run this mapping since May 2026 — a webhook carrying a BSUID and no phone number is checked against it before your code ever sees the payload.

Without a mapping layer, a phone-only lookup either creates a duplicate contact or misroutes the reply; the mapping resolves the same webhook to the existing conversation.

What the webhook payload actually carries

The webhook payload carries the raw identifier as bsuid (or authorBsuid for the sender) alongside a phone field once the mapping resolves one: a handler that reads phone needs no rewrite, and one that wants the raw identifier still has it in the same payload. You can also address the BSUID directly to send without a phone number, once your integration supports it.

What still depends on your own code

A send call addressed by phone number keeps working as before whenever a BSUID-to-phone mapping already exists for that contact, because the routing is already resolved, so the integration never branches on which identifier a customer happens to expose today. What's left is everything downstream: a support-ticket rule or an audience list built on an "always present" phone number still has to read the contact it's handed, not re-derive an identifier from a field that may be absent.

What still needs a real phone number, no exceptions

One case keeps a hard phone-number requirement no matter what: one-tap, zero-tap, and copy-code authentication templates cannot target a BSUID, so an OTP or 2FA login flow still has to collect and hold a real number. Click-to-WhatsApp ads carry a related but softer risk: a BSUID-only lead from a CTWA click is the same missing-phone situation as any other inbound chat, not a separate hard requirement.

Neither limitation is new risk introduced by BSUID: both existed the moment a user could first hide a phone number behind a username. Nothing about BSUID-first matching removes the need to ask for a phone number directly when the message type demands one.

Is your WhatsApp integration BSUID-safe? A 6-point check

A WhatsApp Business Platform integration is BSUID-safe when contact resolution no longer assumes a phone number is present on every message. Run these 6 checks against your own send, webhook, and contact-matching code: each one maps to a failure mode a real WhatsApp integration has already shipped and fixed in production.

• Contact lookup: does your matching code check BSUID before it checks phone number, or does it assume phone number arrives first?

• Missing-field handling: does an inbound webhook with no phone field get processed, or does it throw or get silently dropped?

• Write path: when a BSUID resolves to an existing contact, does your code add it as a second identifier, or overwrite the phone-based one?

• Outbound sends: a send to a phone number you already hold should need zero code changes on your side.

• Auth flows: do OTP and login templates still collect a phone number directly, independent of any BSUID the webhook might carry?

• Rotation events: your system should update only the identifiers named in a given identity-change event, not an entire merged contact's history. That gap is exactly what the merge-bug case above exposed in production.

No migration needed: what's already handled for you

The job here is narrow: keep every existing send, webhook, and conversation thread working while WhatsApp's identifier model changes underneath it, without a migration project. On 1MSG's official Cloud API channel, that job is done — the BSUID-to-phone mapping a support team already depends on sits on the same platform as the send and webhook APIs it already uses, so this shift is not a reason to touch working send or webhook code.

Talking to Meta's Cloud API directly, or through a gateway that only forwards the raw BSUID without mapping it, is where the checklist above earns its keep: contact lookup is the one place this gap actually bites. The webhook use-case examples cover the exact payload shape a BSUID-first handler should expect.

Next step: run your webhook payloads against a free test channel and confirm contact matching holds with a BSUID-only message before your production traffic ever sees one. See 1MSG pricing & free test number Sources Business-scoped user IDs — Meta for Developers, 2026 WhatsApp Business-Scoped User IDs (BSUID) support needed before June 2026 — Chatwoot GitHub issue #13837, 2026 feat: Store WhatsApp BSUID identifiers from inbound webhooks — Chatwoot GitHub PR #14436, 2026 Merged WhatsApp contacts can route replies to the wrong destination — Chatwoot GitHub issue #15359, 2026 Support for WhatsApp Usernames and Business-Scoped User IDs (BSUID) — whatsapp-web.js GitHub issue #201728, 2026 WhatsApp username support overview — Azure Communication Services docs, 2026 Understanding WhatsApp usernames — Vonage Developer docs, 2026 (developer.vonage.com/en/messages/concepts/whatsapp/understanding-usernames) BSUID: new WhatsApp user identifier and changes — 1MSG Help Center, 2026