BSUID Transition Checker
Meta is rolling out business-scoped user IDs (BSUIDs) across WhatsApp Cloud API webhooks starting March 31, 2026. Depending on your setup — whether users have adopted usernames, your contact book status, and how you send messages — the fields in your webhook payloads will look different.
This checker lets you configure your specific scenario and see exactly which fields will be present, omitted, or conditional across incoming message webhooks, status webhooks, and send-message responses. No account needed — it runs entirely in your browser.
- Mar 31, 2026BSUIDs start appearing in message webhooks
- Apr 2026Contact book rolls out (auto-stores phone + BSUID pairs)
- May 2026Send messages to BSUIDs via the new
recipientfield - Later 2026WhatsApp usernames launch — phone numbers may be omitted from webhooks
Configure your scenario to see which webhook fields to expect.
Has the user adopted a username?
WhatsApp usernames launch later in 2026
Message/call interaction in last 30 days?
Are you in the user's WhatsApp contacts?
Is the user in your contact book?
Contact book launches early April 2026
Portfolio type
Linked portfolios with parent BSUIDs?
Sending messages scenario
Which identifier are you sending with?
Before May 2026, phone-number sending is the only supported option
Incoming Message Webhooks
contacts[].user_idExpected present — BSUID — the stable identifiercontacts[].wa_idExpected present — Phone number includedmessages[].fromExpected present — Mirrors wa_id conditionsmessages[].from_user_idExpected present — BSUIDStatus Webhooks (sent / delivered / read)
contacts[].user_idExpected present — BSUIDcontacts[].wa_idExpected present — Present when the message was sent to a phone numberstatuses[].recipient_idExpected present — Set to the user's phone number when sent to a phone numberstatuses[].recipient_user_idWill be omitted — BSUID sending not yet available (May 2026)Sending Messages
toExpected present — Phone number sendrecipientWill be omitted — Not available until May 2026Recommendations
- Update webhook handlers to capture
user_idalongsidewa_id. Treatuser_idas the stable identifier going forward. - Handle webhooks where
wa_idandfrommay be absent. - BSUID-based sending via the
recipientfield is not yet available. Continue sending to phone numbers viato.
What to do with your results
If phone numbers show as omitted or conditional
Your webhook handlers need to work without wa_id and from. Use user_id as your primary identifier and consider enabling Meta's contact book to retain phone numbers from prior interactions. For users who hide their number, the REQUEST_CONTACT_INFO template button lets you ask for it explicitly.
If you are a solution provider
BSUIDs are scoped to the business portfolio that owns the phone number, not yours. Verify WABA and phone number ownership per portfolio before attempting BSUID-based operations.
Regardless of your scenario
Update your webhook handlers now to capture user_id alongside wa_id. Treat user_id as the stable identifier going forward. For the full webhook payload tables and implementation details, read the complete BSUID transition guide.
Frequently asked questions
What does this checker do?
It predicts which webhook fields (user_id, wa_id, from, recipient, etc.) will be present, omitted, or conditional in your incoming message webhooks, status webhooks, and send-message responses based on the scenario you configure.
Do I need an account to use this tool?
No. The checker runs in your browser with no sign-up and no server calls. Your configured scenario is not sent to Dualhook.
When should I start preparing for BSUIDs?
Now. BSUIDs begin appearing in message webhooks on March 31, 2026. Your webhook handlers should be updated to capture the new user_id field and handle cases where wa_id and from may be absent.
What happens if my code ignores the new fields?
Your existing code will keep working until users adopt usernames (later in 2026). At that point, webhooks for username-adopted users may arrive without wa_id or from, which can break handlers that depend on phone numbers being present.
Can I send messages using a BSUID right now?
Not yet. The new recipient field for BSUID-based sending launches in May 2026. Until then, continue sending to phone numbers via the to field.
Where is the full technical documentation?
The complete BSUID transition guide — including webhook payload tables, contact book details, solution provider scoping, and the /contacts endpoint — is available in the Dualhook documentation at /docs/contacts-bsuid.
Keep reading
Dive into the full technical documentation and messaging best practices.
Full BSUID transition guide
Webhook field tables, contact book details, solution provider scoping, and the /contacts endpoint.
Messaging webhook reference
How Dualhook routes message webhooks directly from Meta to your endpoint via Webhook Override.
Messaging best practices
Contact validation, error handling, and delivery patterns for WhatsApp Cloud API messaging.
Ready to set up your WhatsApp integration?
Dualhook configures Coexistence, routes message webhooks directly from Meta to your server, and gives you a dashboard for templates, health, and compliance — with zero message storage.