WhatsApp BSUID Webhook Changes: What Your Payload Will Look Like

What Is Changing

Starting in Q3 2026, WhatsApp Cloud API webhooks will include Business Scoped User IDs (BSUIDs) in message payloads. The from field, which previously always contained a phone number, may now contain a scoped identifier when the user contacts you via a username.

Before BSUID: Legacy Payload

{"messages":[{"from":"1234567890","id":"wamid.ABC123","text":{"body":"Hello"}}]}

After BSUID: New Payload

{"messages":[{"from":"BSUID.a1b2c3d4e5f6","id":"wamid.ABC123","text":{"body":"Hello"}}]}

How to Handle the Transition

During the dual-mode period (Q3 2026), the from field will contain the phone number for legacy conversations and the BSUID for username-initiated conversations. Your backend must parse the from field without assuming it is a numeric value.

Recommended Migration Path

Update your webhook parser to detect BSUID prefix patterns
Add a user_id field to your CRM records alongside wa_id
Implement a link table to map BSUIDs to phone numbers during the dual-mode period
Test your updated webhook using our BSUID Audit Tool

Frequently Asked Questions

When will BSUIDs become mandatory?

Meta plans to deprecate the legacy wa_id in Q4 2026. After this date, all new conversations will use BSUIDs instead of phone numbers.

Can I still get the users phone number?

Phone numbers are not included in BSUID payloads. You must implement an in-chat opt-in flow if your CRM requires phone numbers for matching.

Does BSUID affect existing conversations?

Existing conversations retain their original wa_id. Only new conversations initiated via username will receive BSUIDs. During the dual-mode period, both formats coexist.