WhatsApp usernames | Feb. 18, 2026
WhatsApp usernames: New Business Scoped User ID (BSUID) field required starting June 2026
Starting in June 2026, WhatsApp will start rolling out usernames, an optional feature that allows users to hide their phone numbers when messaging or calling businesses. When a user adopts a username, their phone number may no longer appear in webhook payloads. Instead, a Business Scoped User ID (BSUID) will be provided in the to and from field, as well as the new ExternalUserId field.
What's changing with WhatsApp usernames
Twilio will map the BSUID to a new Messaging API field named ExternalUserId. This field is included in all message webhooks, whether or not the user has adopted a username. When relevant, Twilio also populates the existing to and from parameters with the BSUID:
If a phone number is present, to or from contains only the phone number, and ExternalUserId contains the BSUID.
If no phone number is present, Twilio populates to, from, and ExternalUserId with the BSUID.
The BSUID is up to 128 alphanumeric characters (excluding the two-letter country code), unique per business portfolio-user pair, in the format whatsapp:CC.BSUID. The to, from, and ExternalUserId fields are prefixed with whatsapp:, whether the value is a phone number or BSUID. The length of the ExternalUserId field including the whatsapp: prefix is a maximum of 140 characters. Here’s how this looks:
If a user sends a message/call to a business on WhatsApp:
- to: whatsapp:+1800555XXXX
- from: whatsapp:BR.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T
- ExternalUserId: whatsapp:BR.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T
If a business sends a message/call to a user on WhatsApp:
- to: whatsapp:BR.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T
- from: whatsapp:+1800555XXXX
- ExternalUserId: whatsapp:BR.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T
For more information and examples, check out our WhatsApp usernames docs.
Meta is also launching a contact book feature in early April 2026 that automatically stores user phone number and BSUID pairs from prior interactions. Once a user is in a business's contact book, their phone number will continue to appear in webhooks regardless of whether they've adopted a username. Phone numbers will also still be shared if the business is saved in the user's WhatsApp contacts, or if the user hasn't adopted a username.
Here's how to get ready for WhatsApp usernames
Core messaging workflows should keep working if systems read and reuse the to and from values without assuming they're always phone numbers. Depending on their setup, customers may also want to:
Update systems of record to prepare to capture and store the ExternalUserId (BSUID) from webhook payloads alongside phone numbers in customer profiles
Update any messaging/calling logic that assumes to or from is always an E.164 phone number to also handle BSUIDs
Map BSUIDs to existing customer profiles for consistent user identification
Note: One-tap, zero-tap, and copy code authentication templates still require phone numbers and can’t use BSUIDs.
Need a hand?
These resources will help: