How to Prepare Your CRM for WhatsApp BSUID Before June 2026

If your CRM still assumes every WhatsApp conversation comes with a phone number, you have a quiet problem on the horizon.

Starting in June 2026, WhatsApp will roll out usernames, an optional feature that lets users message businesses without sharing their phone number. When that happens, Twilio delivers a Business-Scoped User ID (BSUID) instead of a phone number. Twilio stores this identifier in a field called ExternalUserId.

That may sound like a small technical change, but the downstream effects are significant.

When your CRM, help desk, or automation stack depends on phone-number-only matching, identity can start breaking without any visible outage. Messages still arrive. Agents still reply. But behind the scenes, records can split, duplicates can appear, and customer history can become harder to track. That risk follows directly from Twilio’s guidance to store BSUID, stop assuming to , and from are always phone numbers, and map BSUIDs to existing customer profiles.

This guide walks you through the best migration path: what BSUID is, what changes in payloads, how to update your data model, and how to keep your CRM clean when WhatsApp usernames roll out.

TL;DR: Key Takeaways

• WhatsApp usernames start rolling out in June 2026, with a broader global rollout planned for August 2026.
• A user may message your business without exposing a phone number, so your system may receive a BSUID instead.
• Twilio includes the BSUID in all message webhooks through ExternalUserId, whether or not the user has turned on usernames.
• The fix is simple: store BSUID, keep phone numbers when available, and update matching logic to prefer BSUID.

What’s Actually Changing in WhatsApp

The biggest mistake brands make is thinking this change means “phone numbers are gone.” That’s not what the documentation says.

Here’s what is changing: phone number is no longer something your systems can safely assume will always be available. When a user adopts a username, their phone number may no longer appear in webhook payloads. Instead, WhatsApp provides a BSUID.

Twilio also confirms that all message webhooks include the BSUID, whether or not the user has turned on usernames. This isn’t a niche edge case for privacy-conscious users. It’s a new identity layer your systems need to handle.

Think of it this way: your CRM used to recognize customers by street address. Now WhatsApp may send a secure ID instead—and if your system only reads addresses, it won’t always know who’s knocking.

What Is a Business-Scoped User ID (BSUID)?

A BSUID is a unique WhatsApp identifier generated for a specific business portfolio–user pair. According to Twilio’s documentation, it can contain up to 128 alphanumeric characters and is valid only for the portfolio that generated it. If the user changes their phone number, Meta regenerates the BSUID.

That “scoped” part matters.

A BSUID is not a universal internet identity. It’s more like a private membership number your business uses to recognize a WhatsApp user within your own environment. If you operate multiple portfolios, a BSUID from one portfolio won’t work in another.

If the phone number was your old shortcut, BSUID is your new durable key.

How BSUID Shows Up in Webhooks

This is the part your technical team needs to understand most clearly.

Twilio stores the BSUID in a field called ExternalUserId—this is the value your systems should capture and store. The documentation also explains these payload rules:

• If a phone number is present, to or from contains the phone number and ExternalUserId contains the BSUID.
• If no phone number is present, to, from, and ExternalUserId are all populated with the BSUID.

That means any logic that assumes from is always an E.164 phone number is now fragile.

The same applies to workflows that:

• Route messages by country code
• deduplicate contacts by phone number
• Create CRM records only from phone-based lookups

If you use Twilio, ExternalUserId is the field to store. If you use another BSP, the field name may differ but the principle doesn’t change. Your CRM needs to support a stable WhatsApp user identifier that isn’t always a phone number.

Why CRMs Break Quietly

Most CRM failures don’t look dramatic. They look annoying.

A message arrives. Your platform replies. But instead of attaching the conversation to the existing customer, your CRM creates a new record. Support sees an “unknown” contact. A nurture workflow fails because the system thinks this is a brand-new lead.

These are the likely outcomes when a CRM expects phone-number-only matching and receives BSUID instead. They’re exactly the kind of issue Twilio’s preparation guidance aims to prevent.

That’s why this matters across teams:

• Marketing loses attribution continuity.
• Support loses conversation history.
• Sales creates duplicate leads.
• Ops wastes time merging bad records.

It’s like the same customer arriving with a different ID badge every visit—your front desk keeps creating a new visitor pass.

The Right Strategy: Don’t Replace Phone Numbers, Add BSUID Alongside Them

So what’s the safest migration model? Keep phone numbers, but stop depending on them as the only identifier.

Twilio’s guidance is to capture and store the BSUID from webhook payloads alongside phone numbers in customer profiles, update logic that assumes to and from are always E.164 numbers, and map BSUIDs to existing profiles for consistent identification.

That means your data model should include:

• Your internal CRM contact ID
• A dedicated WhatsApp BSUID field
• A phone number field, when available
• Optional source and timestamp fields for debugging and attribution

Avoid overwriting phone numbers with BSUID, stuffing BSUID into a notes field, or creating a vague “WhatsApp ID” field that mixes old and new values.

Clean data structures are boring—but boring wins.

The Best Matching Logic for WhatsApp BSUID

If you only change one thing, change your lookup order.

The strongest practical pattern is:

1. Match by BSUID
2. If no match exists, match by phone number
3. If matched by phone, write the BSUID back to that contact
4. If no match exists at all, create a new record

This sequence is an implementation recommendation, but it’s the cleanest way to apply Twilio’s published guidance to store BSUID and map it to existing customer profiles.

That writeback step is the key. It means your system “learns” the new identifier over time. The first message may require a fallback lookup. The second one won’t.

It’s like updating a contact after they change jobs. Once you save the new details, future calls go to the right place automatically.

What to Audit in Your Stack Right Now

Before your team writes code, run a 90-minute audit.

1. List Every WhatsApp Entry Point

Map where conversations begin:

• Click-to-WhatsApp ads
• Website widgets
• QR codes
• Support inboxes
• Sales numbers
• Post-purchase messaging flows

2. Identify Your Source of Truth

Decide where customer identity really lives:

• CRM
• CDP
• Support platform
• Custom customer database

3. Find Every Phone-Number Dependency

Search for phone-based logic in:

• Webhook handlers
• Middleware tools
• CRM dedupe rules
• Help desk matching
• Reporting queries
• Automation rules

Twilio specifically warns teams to update any messaging or calling logic that assumes to or from is always an E.164 phone number. That warning should guide your audit scope.

How to Update Your CRM Data Model

Your CRM doesn’t need a complete rebuild. It needs a clean identity upgrade.

At a minimum, add these fields:

Field Name	Purpose
whatsapp_bsuid	Stores the BSUID from ExternalUserId
whatsapp_phone_e164	Stores phone number when available
last_whatsapp_interaction_at	Tracks recency for segmentation
first_whatsapp_source	Captures original entry point

If you use Twilio, store the value exactly as it appears in ExternalUserId. That’s the field Twilio uses to expose BSUID in the Messaging API and webhooks.

If your team uses Salesforce, HubSpot, or another CRM with custom properties, keep BSUID in a dedicated field so it can be indexed, matched, and reused by workflows. If your stack uses middleware, make sure the middleware passes BSUID through instead of dropping it.

Backfilling BSUID for Existing Contacts

You don’t need a high-pressure migration week to make this work.

The smarter approach is incremental:

• Store BSUID for every new inbound conversation
• If you match a contact by phone, write the BSUID back immediately
• Process recent logs where both phone and BSUID are available
• Update existing records gradually

Twilio explicitly recommends mapping BSUIDs to existing customer profiles for consistent identification. That supports a phased backfill strategy rather than a risky all-at-once migration.

This is the kind of migration that gets cleaner as you go. Each new conversation improves your identity map.

---

Testing: How to Know You’re Ready

“Send a test message” isn’t enough.

You need a BSUID-first test case:

1. An existing contact exists in the CRM
2. An inbound WhatsApp event contains BSUID
3. The phone number is missing or not used for matching
4. The conversation still attaches to the correct contact
5. No duplicate record is created

That test directly reflects Twilio’s documented payload behavior, where ExternalUserId always contains BSUID and to/from may contain BSUID instead of phone number when no number is present.

Also regression-test:

• Lead routing
• Support assignment
• Welcome flows
• CRM automations
• Analytics attribution
• Deduplication rules

If any of those still depend on phone-only logic, the bug may not surface until production.

Contact Book Changes the Risk, Not the Requirement

There’s one nuance that matters a lot.

Twilio says Meta plans a contact book feature that stores phone numbers and BSUID pairs from prior interactions.

Once a contact is stored, webhook payloads and API responses include both identifiers—even if the user has enabled usernames. Phone numbers also continue to be shared if the business is saved in the user’s WhatsApp contacts or if the user hasn’t adopted usernames.

That’s helpful. But it doesn’t remove the need to support BSUID.

Why? Because the documentation still tells businesses to store BSUID and update logic that assumes phone numbers. Contact book is a safety net not a substitute for proper identity design.

Important Limitations Teams Should Know

There are a few details worth highlighting in your internal migration doc.

Authentication Templates Still Need Phone Numbers

Twilio says one-tap, zero-tap, and copy-code authentication templates still require phone numbers and cannot use BSUIDs. If your team uses WhatsApp for verification or OTP flows, phone number support still matters.

BSUIDs Are Portfolio-Scoped

A BSUID is valid only for the business portfolio that generated it. If your company uses multiple portfolios, resolve cross-portfolio identity at the CRM or data layer—don’t assume one BSUID works everywhere.

The Timeline Is Tight

Twilio’s rollout timeline shows the initial rollout beginning in June 2026 and the global rollout following in August 2026. Twilio advises making sure your integration is updated by early June 2026.

There’s still time, but not a lot of it.

A 30-Day Action Plan

Here’s the practical version.

Week 1: Audit

• Map all WhatsApp entry points
• Identify every phone-number-based lookup
• Choose your system of record

Week 2: Model

• Add a dedicated BSUID field
• Update webhook parsing
• Update field mappings in middleware and CRM

Week 3: Match

• Implement BSUID-first lookup
• Add phone fallback
• Write BSUID back when matched by phone

Week 4: Test and Monitor

• Run BSUID-first test cases
• Monitor duplicate creation rates
• Monitor unknown-contact rates
• Brief support and sales teams on the change

This plan isn’t copied from vendor docs, but it’s the most practical execution model for the prep steps Twilio recommends.

The Strategic Lesson: Become Identifier-Agnostic

The deepest takeaway here is bigger than WhatsApp.

Any customer system built around one fragile identifier will eventually struggle. Today it’s phone numbers. Tomorrow it could be another privacy-driven change. The best CRM architecture is identifier-agnostic: it recognizes a customer through multiple validated IDs without falling apart when one of them becomes optional.

That’s the real opportunity in this migration. You’re not just preparing for WhatsApp usernames. You’re building a cleaner customer identity layer.

And that pays off far beyond one channel.

Conclusion

WhatsApp usernames aren’t just a UX update. They’re an identity change.

According to Twilio’s current documentation, businesses should be ready for a June 2026 rollout where users may hide phone numbers and interact through BSUID. Twilio exposes that value through ExternalUserId and advises teams to store it, support it in logic, and map it to existing customer profiles.

If your CRM still assumes phone number is the only reliable WhatsApp identifier, now is the time to fix it.

The right move is simple:

• Keep phone numbers when you have them
• Add BSUID as a first-class field
• Update matching logic
• Test before rollout
• Stop treating one identifier like the whole customer

Do that, and June 2026 becomes a smooth migration—not a scramble.

FAQs