WhatsApp's BSUID Migration Starts July 7 — A Five-Point Checklist for Inbound-Only Teams — UnifyPort
Meta is changing how WhatsApp identifies users in its API. Starting July 7, 2026 (Wave 1), a new field called the Business-Scoped User ID (BSUID) will appear in every webhook payload — and for users who adopt WhatsApp usernames, the phone number may stop appearing entirely.
If you receive WhatsApp messages as part of a support queue, CRM integration, or AI agent pipeline, this migration touches your code. How much it touches depends on which path your WhatsApp messages travel before they reach your backend.
This article is a checklist. Five areas to audit, one decision matrix, and a clear answer to the question most small teams are actually asking: “Do I need to do anything before July 7?”
What BSUID actually is
Every WhatsApp user is getting a new identifier: a Business-Scoped User ID. The format is a two-letter country code, a dot, and up to 128 alphanumeric characters — like BR.1A2B3C4D5E6F7G8H9I0J. The key property: the same person gets a different BSUID for every business they interact with. Your BSUID for user Alice is not the same as another company’s BSUID for Alice.
Meta’s rollout timeline:
| Wave | Date | Scope |
|---|---|---|
| Wave 1 | July 7, 2026 | Initial markets |
| Wave 2 | July 20, 2026 | Expanded rollout |
| Global | September 2026 | All remaining markets |
BSUIDs already started appearing in webhook payloads on March 31, 2026 as a new user_id field. But the breaking change comes with Wave 1: once a user adopts a WhatsApp username, their phone number may no longer appear in the wa_id and from fields.
The checklist: five areas to audit
1. Webhook payload parsing
What changes: A new user_id field appears in every message webhook. For username-enabled users, the wa_id and from fields that previously contained a phone number may instead contain the BSUID — or be absent entirely.
What to check: Does your webhook handler assume from is always a phone number? Does it regex-match for digits, use it as a database key, or pass it to a phone-number validation library? Any of those will break when from contains BR.1A2B3C4D5E... instead of 5511999887766.
2. CRM and contact matching
What changes: If your CRM stores customer records keyed by phone number, a message from a username-enabled user may arrive with no phone number at all. You can’t look up the customer.
What to check: Can your contact database store and match on BSUIDs alongside phone numbers? Meta provides a Contact Book API that preserves the phone-to-BSUID mapping from prior conversations — but you need to have called it before the phone number disappears from new webhooks.
3. Conversation history and threading
What changes: If you thread conversations by phone number (e.g., “show me all messages from +5511999887766”), the same person’s messages will start arriving under a BSUID identifier instead. Your conversation history splits in two unless you’ve linked the old phone-based records to the new BSUID.
What to check: Does your message store use phone number as the primary key for conversation threads? If so, plan a backfill: use the Contact Book mapping to link existing phone-keyed records to their BSUIDs before Wave 1.
4. Template and outbound addressing
What changes: When sending template messages (outbound), you’ll eventually need to address recipients by BSUID instead of phone number — particularly for users who’ve adopted usernames and whose phone numbers are no longer exposed.
What to check: If you send proactive messages (order confirmations, shipping updates, appointment reminders), does your send logic resolve the recipient by phone number? You’ll need to store the BSUID from the most recent inbound message and use it for future outbound calls.
5. Data storage and compliance
What changes: BSUIDs are a new form of personally identifiable data. They’re scoped per-business (so they can’t be used to cross-reference users across companies), but they’re still PII under most privacy frameworks.
What to check: Does your data retention policy cover a new identifier type? If you have GDPR/PDPA deletion flows that enumerate all stored identifiers for a user, BSUIDs need to be included.
Which path are you on?
Not every team needs to act on all five checklist items. It depends on how WhatsApp messages reach your backend.
| Integration path | Checklist items that apply | Migration effort |
|---|---|---|
| Cloud API (direct) | All five | High — you parse Meta’s raw webhooks, so every payload change hits your code directly |
| BSP (Wati, 360dialog, etc.) | Items 2, 3, 4, 5 | Medium — your BSP may abstract the webhook format, but your CRM and send logic still need updating |
| Unofficial inbound interface | None | Zero — read on |
Why unofficial inbound isn’t affected
If your WhatsApp messages arrive through UnifyPort’s unofficial interface, the BSUID migration doesn’t touch your pipeline. Here’s why: UnifyPort doesn’t route messages through Meta’s Cloud API. The unofficial path connects to WhatsApp directly — the same way a phone running WhatsApp does — so the messages your webhook receives were never in the Cloud API payload format to begin with.
Your webhook still receives the same message.received event it always has:
{
"event": "message.received",
"account_id": "acct_3qPmRz",
"provider": "whatsapp",
"from": "user_88c1ae",
"text": "Hi, is order #2241 shipped yet?",
"timestamp": 1751875200,
"message_id": "wa_msg_f4e29a"
}The from field is UnifyPort’s own normalized user identifier — not a phone number, not a BSUID. It was never a phone number to begin with, so there’s no migration to perform when Meta changes its identifier scheme. Your CRM matching, conversation threading, and webhook parsing all continue to work unchanged.
The HMAC-SHA256 signature verification on your webhook endpoint is also unaffected — the signing secret and signature format are UnifyPort’s, not Meta’s.
What to do this week
If you’re on the Cloud API or a BSP: start with checklist item 1 (webhook parsing). Log a sample of incoming webhooks and check whether the user_id field is already present — it’s been rolling out since March 31. If it’s there, you know your payloads are already changing. Work through items 2-5 before July 7.
If you’re on an unofficial inbound path: nothing changes. The BSUID migration is a Cloud API concern, and your messages don’t travel through the Cloud API. Keep building.