WhatsApp username rollout in: --d --h --m --s  —  Is your WhatsApp setup safe?

WhatsApp BSUID Migration Guide for MENA Agencies (2026)

By: ShiftKit Team Reading time: 12 min Last updated: 2026-05-11

TL;DR — In one paragraph: Meta rolled BSUIDs (BSP-scoped user IDs) into production on March 31, 2026. Every WhatsApp Business Platform integration in MENA that keys customer identity by phone number — which is most of them — will break silently when WhatsApp usernames go live in the second half of 2026. The migration is not optional and the window closes faster than most operators realize. This guide is the field manual: what changed, who's affected, the new data model, the exact migration path, and the mistakes we keep seeing in MENA agency code reviews.

What changed and when

Meta has spent 2025–2026 quietly replacing the foundation of WhatsApp Business Platform identity. Three timeline milestones matter:

A BSUID is a BSP-scoped User ID — meaning each Business Solution Provider (BSP) sees a different ID for the same underlying end-customer. If your business sends messages through both Twilio and 360Dialog, the same shopper has two BSUIDs in your data. This is intentional on Meta's side (it makes cross-BSP correlation harder and improves user privacy), and it means the migration is not just a column-rename. It changes how contact resolution works across your stack.

The relevant Meta-published references are:

BSUID webhook payload before and after migration — showing the shift from phone-number-keyed to BSUID-keyed webhook fields

Who is affected (and who isn't)

The honest answer: most MENA WhatsApp Business deployments are exposed. The specific exposure varies by integration pattern.

Integration patternBSUID exposureWhat breaks
Phone number as primary key in CRM, in-house code, or PHP/Laravel integrationHighWebhook handler can no longer reliably find the contact record from inbound messages once a user changes phone number or chooses a username. Reconciliation drifts. Marketing automations target wrong records.
Salla / Zid / Shopify / WooCommerce store with WhatsApp plugin, plugin not yet BSUID-awareHighSame as above. Most plugins as of May 2026 are not yet BSUID-aware — confirm with your platform support before assuming you're safe.
BSP-managed contact identity (Twilio Conversations, 360Dialog managed contact book, YCloud, Hubtype)MediumThe BSP carries the BSUID mapping internally. Your CRM is one layer removed, but you still need to consume the BSUID via webhook and store it. Your BSP's transition guide is the source of truth for your specific case.
Stateless broadcast-only (you only send templates, never store inbound responses)LowIf you never reconcile inbound messages to customers, you have no broken state. But you also have no two-way relationship — and if you ever plan to enable two-way (which most agencies are pushed toward in 2026), the migration becomes blocking.
Just-launched on Meta Cloud API + Contact Book API directlyNoneIf you build directly on Meta's Cloud API and adopted Contact Book API as your contact pattern from day one, you're already in the new model.

Who isn't affected: Businesses using only static template broadcasts with no inbound reconciliation. Businesses on Meta Cloud API directly that adopted Contact Book API from day one. Everyone else needs to migrate.

MENA-specific factors:

Three reasons MENA agencies are disproportionately exposed:

  1. Custom integrations are common. Many KSA and Egyptian agencies built bespoke PHP/Laravel webhook handlers for their WhatsApp Business stack in 2022–2024, before BSPs offered turnkey Contact Book management. These bespoke handlers are typically phone-keyed.
  2. Platform updates lag. Salla and Zid push BSUID-aware integration updates on their own cadence, which trails Meta's deadline. Confirm-by-asking is the only way to know if your platform has caught up.
  3. Saudi merchants are higher-volume. KSA merchants tend to run higher message volumes per business, so reconciliation drift compounds faster. A 2% identification failure on 1,000 messages/month is invisible. The same rate on 100,000 messages/month is operationally serious.
MENA integration exposure matrix — risk tiers by integration pattern for KSA and Egyptian agencies

The new data model

Three concepts to internalize, then we'll show the actual webhook payload changes.

BSUID (BSP-scoped User ID)

A stable, opaque identifier issued by Meta and surfaced in WhatsApp Cloud API webhooks. Format: an alphanumeric string up to 128 characters. Each BSP sees a different BSUID for the same underlying customer, which is by design.

{
  "messages": [{
    "from": "+966501234567",
    "bsuid": "wamid_BSUID_abc123def456...",
    "id": "wamid.HBgMOTY2NTAxMjM0NTY3FQIAEhgUM...",
    ...
  }]
}

The phone number remains in the payload (Meta has not announced removal) but is documented as non-canonical and may change when the user changes their phone or chooses a username.

Contact Book API

Meta's new contact management surface. You call it to read, update, and group your contact identifiers. Replaces the implicit "your CRM is the source of truth" pattern with an explicit Meta-side contact registry that your CRM mirrors.

Key endpoints in the BSP-mediated flow:

REQUEST_CONTACT_INFO template

A Meta-provided template type your business can send at appropriate moments (first conversation, post-purchase, etc.) that asks the customer to share their phone number and/or contact name with you in a way Meta tracks. Lets you keep a phone-number copy in your CRM legitimately while staying in the new model.

{
  "messaging_product": "whatsapp",
  "to": "BSUID:wamid_BSUID_abc123def456...",
  "type": "template",
  "template": {
    "name": "REQUEST_CONTACT_INFO",
    "language": { "code": "ar_SA" }
  }
}

Note the to field is no longer a phone number — it's the BSUID prefixed with BSUID:. (Phone-number addressing is still accepted for backward compatibility through Q4 2026 per Meta's current published deprecation timeline, but planning around the new pattern from day one is the correct call.)

Step-by-step migration path

We've run this migration on enough MENA WhatsApp stacks to converge on a five-day shape. Yours may be faster or slower depending on stack complexity, but the steps are consistent.

5-day WhatsApp BSUID migration sprint timeline

Day 1 — Audit

Map every phone-number reference in your stack:

Output: a single inventory document listing every component, what it does with phone numbers today, and the migration action required.

Day 2 — Schema and BSP-side prep

In your database:

ALTER TABLE wa_contacts
ADD COLUMN bsuid VARCHAR(128),
ADD COLUMN bsuid_seen_at TIMESTAMP,
ADD INDEX idx_wa_contacts_bsuid (bsuid);

ALTER TABLE wa_messages
ADD COLUMN bsuid VARCHAR(128),
ADD INDEX idx_wa_messages_bsuid (bsuid);

In parallel, confirm with your BSP that:

If any of the above is "no" or "not yet," your migration is blocked at the BSP, not in your code.

Day 3 — Webhook handler update

Modify your inbound webhook handler to:

  1. Read bsuid from every inbound message.
  2. Look up the contact by bsuid first, then by phone_number as fallback.
  3. If found by phone_number only (the contact hasn't been BSUID-stamped yet), backfill the bsuid column on that contact.
  4. If found by neither, create a new contact record with bsuid as the canonical key and phone_number as a secondary field. Send a REQUEST_CONTACT_INFO template within the conversation context to capture contact name and any other fields you need.

Pseudocode shape (language-agnostic):

on webhook(inbound):
  bsuid = inbound.messages[0].bsuid
  phone = inbound.messages[0].from

  contact = db.find_by_bsuid(bsuid)
  if not contact:
    contact = db.find_by_phone(phone)
    if contact:
      contact.bsuid = bsuid
      contact.bsuid_seen_at = now()
      db.save(contact)

  if not contact:
    contact = db.create(bsuid=bsuid, phone=phone, status='new')
    enqueue_request_contact_info(bsuid)

  process_message(contact, inbound.messages[0])

This shape preserves backward compatibility with your existing phone-keyed flows while moving the canonical key forward.

Day 4 — Outbound and analytics update

Update outbound code paths:

Day 5 — Monitor and verify

For the first 30 days post-cutover, monitor:

If any of the above is off-target, you have specific signal to debug rather than wholesale failure.

Common mistakes we keep seeing in MENA agency code reviews

These are real (anonymized) failure modes we've audited.

1. Treating BSUID as a phone-number column rename

The most common mistake. An agency adds a bsuid column, copies their phone numbers into it, and assumes they're done. They aren't — the BSUID is a Meta-issued identifier, not derived from the phone. Until you actually read a BSUID from a webhook and store it, your bsuid column is empty regardless of what you copied into it. Concrete example: a Riyadh-based agency we audited had a bsuid column populated with what they thought were BSUIDs but were actually just E.164-format phone numbers with a BSUID_ prefix they'd added themselves. None of their webhook handlers ever wrote a real BSUID.

2. Ignoring the BSP-scoped scope

A merchant we audited operates two BSPs in parallel (Twilio for KSA, 360Dialog for Egypt). They built a unified customer record keyed by BSUID. When a customer messaged via Twilio one day and 360Dialog the next, their CRM saw two different customers. The fix: BSUID is BSP-scoped. Your contact record needs bsuid_twilio, bsuid_360dialog, etc. — or a separate "BSUID-to-contact" join table that supports many-to-one.

3. Sending REQUEST_CONTACT_INFO at the wrong time

The template is designed to be sent in conversation context — i.e., when the customer is actively engaged and expecting a touch. We've seen agencies send it as the first message of a cold outbound, which violates Meta's guidance and degrades template approval rates. Send it after a customer-initiated message, or after a known opt-in event (post-purchase, post-form-submit). Not as a cold opener.

4. Forgetting analytics/BI joins

The CRM gets migrated, but the BigQuery / Snowflake / Metabase joins to WhatsApp event data still key on phone number. Dashboards silently undercount or split customers. Fix: schema-level audit covering every consumer of WhatsApp data, not just the operational CRM.

5. Hard-coded phone-number routing in middleware

A Saudi-based fintech we worked with had a Node.js middleware layer that routed inbound WhatsApp messages to internal queues based on the leading country code in the phone number (+966 → KSA queue, +971 → UAE queue, etc.). Once BSUIDs entered the payload and phone numbers became non-canonical, the routing logic broke for any customer whose phone changed. Fix: route on customer record attributes (country, account, segment), not on the raw incoming phone.

6. Not budgeting for the BSP-side rollout lag

We've seen at least three smaller MENA BSPs (Saudi-only and Egypt-only operators) lag Meta's BSUID rollout by 6–10 weeks. Agencies who built their migration plan against Meta's calendar but not their actual BSP's calendar hit a wall: the migration is ready in their code, but the BSUID isn't yet present in their inbound payloads. Always verify with the BSP, not just with Meta.

7. Skipping the test plan

The migration is mechanical enough that some teams attempt it without a test plan. The test we recommend: take the most active 20 customer records in production, write a script that simulates the new-shape webhook (BSUID + phone) against the migrated handler, and confirm each record is found, the BSUID is backfilled, and downstream events fire correctly. Do this in staging. Most "we migrated and it broke" reports we've audited traced back to a missing test for an edge case (suspended numbers, ported numbers, customers who deleted and re-installed WhatsApp).

FAQ

Q: What is a BSUID?
A: BSUID (BSP-scoped User ID) is the new identifier Meta issues for every WhatsApp Business conversation as of March 31, 2026. It replaces the customer phone number as the stable key in WhatsApp Business Platform webhooks. Each BSP sees a different BSUID for the same end customer.

Q: Will my WhatsApp Business CRM break?
A: If your CRM uses the customer phone number as the primary key for WhatsApp contacts, yes — silently — when usernames roll out in H2 2026. The migration path is to add a BSUID column, map historical phone-keyed records, and adopt the Contact Book API for new conversations.

Q: When does WhatsApp usernames actually launch?
A: Meta has scheduled username rollout for H2 2026 without a specific public day-zero date as of May 2026. Plan around the existing BSUID model now; usernames are an additional change layered on top once they're live.

Q: My BSP says they'll handle the migration for me. Is that enough?
A: It can be, if your stack is BSP-managed end-to-end (you only operate through the BSP's UI, you don't have a self-hosted CRM, you don't run BI queries against WhatsApp data). If you have any code or analytics layer that touches WhatsApp contact identity, your BSP's migration covers their side and yours is still on your plate.

Q: Can I keep using phone numbers in to for outbound messages?
A: Yes, through Meta's current published deprecation timeline (end of Q4 2026). Planning around the BSUID-addressed pattern from day one is the recommended path because the deprecation timeline may compress, and because phone-addressed outbound to a user who has chosen a username will eventually fail.

Q: Do BSUIDs work with WhatsApp Cloud API and On-Premise API?
A: BSUIDs are a Cloud API concept. On-Premise API customers should consult Meta's migration timeline for moving to Cloud API, as On-Premise is itself being deprecated.

Q: How do I know if my Salla / Zid / Shopify / WooCommerce store is BSUID-aware?
A: Ask your platform support directly. Most as of May 2026 are not yet fully BSUID-aware. The audit (see below) confirms in a single pass.

Q: How long does the migration take for a typical MENA agency?
A: Five working days for a mid-sized agency with one BSP and one CRM. Two to three weeks for an agency managing 10+ merchant clients with bespoke per-client integrations. We've never seen a single-stack migration take more than 10 days unless the BSP itself was lagging.

Q: What does this cost if I do it myself?
A: Engineering time only. A senior backend engineer can do the work in a 5-day sprint at standard agency rates. The cost is usually the missed work elsewhere, the BSP coordination overhead, and the risk of silently miscounting customers during the cutover.

References

(Links updated for every cornerstone refresh. If any reference 404s, file a note via the contact page and we'll re-source.)

Get a free audit

We've audited dozens of MENA WhatsApp Business stacks under BSUID rollout pressure. The audit takes 3 minutes for a verdict and 5–7 days for the full delivery.

Step 1 — Free 3-minute verdict.
Eight questions about your stack. We tell you which exposure bucket you're in and which specific failure modes apply. No commitment. Email captured only if you want the full PDF report.

[ Start the free audit ]

Step 2 — Paid full audit ($499).
A 5-day deliverable. Webhook payload analysis on your actual production traffic, CRM remediation plan, migration timeline tailored to your stack, code samples for your specific platform + BSP combination.

Step 3 — Migration sprint ($2,500).
We run the migration for you over 5 working days. Schema changes, webhook handler updates, outbound code updates, analytics layer fixes. 30 days of post-migration monitoring included.

Step 4 — Ongoing monitoring ($99/month).
Dashboard + alerting for BSUID state, webhook failure rate, Contact Book API errors, and Meta policy updates that affect your migration. 7-day free trial. Cancel any time.

ShiftKit is the MENA WhatsApp compliance studio operated by ExAutomatica, a venture studio based in Cairo. ShiftKit / Migrate is one of three products serving WhatsApp Business operators through Meta's 2026 platform changes (BSUID, Saudi rate restructure, Business Verification overhaul). Read about ShiftKit or book a free consultation.

— ShiftKit Team · 2026-05-11

Ready to migrate?

Run the free audit → Book the $499 diagnostic →