With the introduction of Usernames, Meta is shifting from raw phone numbers to Business Scoped User IDs (BSUIDs) for all API interactions. If you are new to the username ecosystem, start with our guide on what a WhatsApp username is for foundational context.
A Business Scoped User ID (BSUID) is a unique string identifier assigned to a user specifically within the context of a single WhatsApp Business Account (WABA). If a user messages Business A, they receive BSUID 123 for that interaction; if the same user messages Business B, they receive a completely different BSUID 456. This architecture prevents data brokers and advertisers from tracking users across multiple businesses using a universal WhatsApp identifier.
BSUIDs are mathematically hashed using the WABA ID as a salt value, meaning the same user generates entirely different IDs for every business they contact. This isolation layer is a fundamental privacy improvement over the legacy wa_id system, which returned the user's raw phone number in every API webhook payload. For developers, this means three critical changes: inbound webhooks now return user_id instead of wa_id in the contacts array, database schemas must add a nullable whatsapp_bsuid column, and outbound messages must use the BSUID string in the to field instead of a phone number.
What Is the Architecture of a BSUID?
A BSUID is a unique string that identifies a user only within the context of your specific WhatsApp Business Account (WABA). If a user messages Business A, they get BSUID 123. If that same user messages Business B, they get BSUID 456.
This prevents data brokers from tracking users across multiple businesses using their WhatsApp identifier. According to Meta's Cloud API webhook documentation, BSUIDs are mathematically hashed using your WABA ID as a salt—meaning the same user generates different IDs for different businesses.
Why Do BSUIDs Matter for Privacy?
- Privacy by Design: Users are protected from cross-business profiling
- GDPR/CCPA Compliance: Reduced PII surface in your database
- Migration Ready: BSUIDs persist for the lifetime of the user-WABA relationship
- API Future-Proofing: Legacy
wa_idfields are being deprecated in Q4 2026—see the Migration Timeline
What Payload Structural Changes Do BSUIDs Introduce?
In the legacy API, the contacts array returned a wa_id which was literally the user's phone number. Under the new architecture, webhooks will return a user_id:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "YOUR_WABA_ID",
"changes": [
{
"value": {
"contacts": [
{
"user_id": "bsuid_987654321",
"profile": { "name": "John Doe" }
}
]
}
}
]
}
]
}
If your webhook parser relies on wa_id, it will break once Meta completes the deprecation. Use our BSUID Audit Tool to test your existing payloads.
How Do BSUID Security Isolation Layers Work?
BSUIDs provide a distinct isolation layer:
- No Cross-Business Tracking: BSUIDs are mathematically hashed using your WABA ID as salt. This is fundamentally different from device-level identifiers like IDFA or GAID.
- Portability: If you migrate your business to a new WABA, you must use the Meta Migration API to translate your BSUIDs. There is no automatic portability between accounts.
How Do BSUIDs Impact My Integration?
BSUIDs affect three major areas of your WhatsApp Business integration:
| Area | Legacy (wa_id) | New (BSUID) |
|------|---------------|-------------|
| Inbound Webhooks | contacts[0].wa_id — plain phone number | contacts[0].user_id — scoped hash |
| Database Schema | Phone number required | BSUID column, phone optional |
| Outbound Messages | "to": "1234567890" | "to": "bsuid_987654321" |
| Cross-Business Identity | Trackable via phone | Isolated per WABA |
How Do I Get Ready for BSUIDs?
- Audit Your Webhooks: Paste your payloads into the BSUID Audit Tool to check for compatibility
- Update Your Schema: Add a
whatsapp_bsuidcolumn that can store string identifiers (see the Integration Checklist) - Plan Your Migration: Review the BSUID Migration Timeline for key deadlines
- Configure Routing: If you use RezervSpot's API Proxy Gateway, BSUID-based routing is supported at the Pro tier and above
Test your webhook readiness with our BSUID Audit Tool or return to the Business Hub for more resources.