# WhatsApp usernames and BSUIDs: what changes for OTP, CRM and webhooks > WhatsApp usernames mean a business may no longer see a customer's phone number. Meta's answer is the business-scoped user ID (BSUID). Here is what it is, what still needs a phone number, and how to migrate webhooks, CRM and OTP flows. - Canonical URL: https://www.broadnet.me/blog/whatsapp-usernames-bsuid-developer-guide - Language: en - Last updated: 2026-09-26 - Publisher: BroadNet (https://www.broadnet.me) - Published: 2026-09-26 - Author: BroadNet Engineering A business-scoped user ID (BSUID) is the identifier Meta now puts in every WhatsApp webhook so a business can message a user without knowing their phone number. It exists because WhatsApp is introducing usernames: once a user turns one on, a business that has not been in touch recently may no longer receive the number. This guide from the BroadNet engineering team explains the format, the timeline, what still requires a phone number, and how to migrate webhooks, CRM records and OTP flows. ## Key takeaways - BSUIDs have appeared in WhatsApp webhooks since early April 2026, for every user, whether or not they use a username. - A BSUID looks like US.13491208655302741918: an ISO 3166 alpha-2 country code, a period, then up to 128 alphanumeric characters. - It is unique to each business portfolio and user pair, and it is regenerated if the user changes their phone number. - Since July 2026 you can send messages to a BSUID, except one-tap, zero-tap and copy-code authentication templates, which still need the phone number. - Meta says partners and directly integrated businesses must support BSUIDs to avoid losing the ability to process messages from username users. - Keep the verified E.164 phone number as the identity anchor for OTP, SMS fallback and fraud checks. Treat the BSUID as a WhatsApp-channel key. ## What is a business-scoped user ID? Meta defines a BSUID as "a unique user identifier that can be used to message a WhatsApp user when you don't know their phone number" ([Meta, business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)). The format is the user's country as an ISO 3166 alpha-2 code, a period, and up to 128 alphanumeric characters, for example US.13491208655302741918. Three properties matter for system design: - Scope. A BSUID is unique to one business portfolio and one user. The same person has a different BSUID for every business portfolio they talk to, so you cannot use it to match customers across unrelated portfolios. - Stability. It is regenerated when the user changes their phone number. Meta sends a system message webhook with type user_changed_user_id, and a separate user_id_update webhook, when that happens. - Parent BSUIDs. Managed businesses with several portfolios can ask their Meta point of contact to enrol in parent BSUIDs, which contain ENT (for example US.ENT.11815799212886844830) and work across all enrolled portfolios. ## Why is WhatsApp introducing usernames? For privacy. Meta announced on 29 June 2026 that people can reserve a username to use "later this year", and that when a user has enabled one, a person or business they message for the first time will no longer see their phone number ([About Meta](https://about.fb.com/news/2026/06/its-time-to-reserve-your-whatsapp-username/)). Meta's developer documentation says usernames will roll out gradually in 2026. Businesses can have usernames too. From 29 June 2026 a business can claim a username WhatsApp has reserved for it through WhatsApp Manager, Meta Business Suite or the Username API, and approved usernames become active when the feature launches. A business username does not hide the business phone number. ## What is the timeline? | Date | What happened or happens | What developers should do | |---|---|---| | Early April 2026 | BSUIDs start appearing in messages webhooks (user_id) | Store the BSUID alongside the phone number on every inbound event | | 29 June 2026 | Username reservation opens for users and businesses | Reserve your business username; plan for number-less users | | July 2026 | Sending messages to a BSUID is supported in the API | Add the recipient parameter to your send path | | During 2026 (gradual) | Usernames roll out to users | Expect inbound webhooks with a BSUID and no phone number | ## Will you lose the customer's phone number? Sometimes. The BSUID appears in all messages webhooks. The phone number (wa_id, and from on inbound messages) is included only when at least one of these is true, according to Meta: - you messaged or called the user's phone number within the 30 days before the webhook was triggered; - you received a message or call from the user's phone number within those 30 days; or - the user is in your contact book. The 30-day lookback is evaluated per business phone number, so a customer known to your sales line may be unknown to your support line. The contact book is a Meta-hosted feature that stores phone numbers and BSUIDs after a first interaction, so later webhooks can keep carrying the number even after the user adopts a username. It is on by default and can be switched off in Meta Business Suite under Business settings, Business info. Leave it on unless you have a reason not to. ## What still needs a phone number? Meta is explicit: BSUIDs "can be used to send any type of message except for one-tap, zero-tap, and copy code authentication templates, which require user phone numbers". Outside WhatsApp, anything that runs on the mobile network also needs the number. | Task | Works with a BSUID only? | What you need | |---|---|---| | Free-form replies, media, interactive messages | Yes | BSUID in the recipient parameter | | Marketing and utility templates | Yes | BSUID in the recipient parameter | | One-tap, zero-tap and copy-code authentication templates (OTP) | No | The user's phone number | | SMS or RCS fallback when WhatsApp fails | No | E.164 phone number | | HLR lookup, SIM swap check, number verification | No | E.164 phone number | | Matching the customer to the same person in another business portfolio | No | Your own customer ID or phone number | ## What does the webhook look like before and after? Before BSUIDs, the contacts block in a messages webhook carried the phone number in wa_id, and most integrations used it as the customer key. Meta's example of the new contacts object adds the username, the BSUID and, where enabled, the parent BSUID; wa_id is present only when the number can be shared: ``` "contacts": [ { "profile": { "name": "", "username": "" }, "wa_id": "", "user_id": "", "parent_user_id": "" } ] ``` Inbound messages also carry from_user_id (and from_parent_user_id if enabled), and status webhooks carry recipient_user_id, which Meta says is always set to the user's BSUID. To send, put the BSUID in the new recipient parameter. You can set the to parameter (phone number), the recipient parameter (BSUID), or both; when both are present, the phone number takes precedence: ``` { "messaging_product": "whatsapp", "recipient_type": "individual", "recipient": "", "type": "text", "text": { "body": "" } } ``` The send response then includes user_id in its contacts array, and wa_id becomes optional. If your parser assumes wa_id is always present, it will fail on the first username user. You can paste real payloads into our [webhook payload inspector](https://www.broadnet.me/tools/webhook-payload-inspector) to check which fields your integration actually receives. ## What breaks for OTP? Authentication templates with one-tap, zero-tap or copy-code buttons cannot be sent to a BSUID. If a username user reaches you over WhatsApp and you have no phone number for them, you cannot send them a WhatsApp OTP of those types. That has two consequences for verification flows: - Collect and verify the phone number at sign-up, in E.164 format, and store it as the account's verification address. Do not rely on the WhatsApp webhook to hand it to you later. See [what E.164 is](https://www.broadnet.me/answers/what-is-e164). - Keep a channel that works on the number itself. SMS OTP, voice OTP and silent network checks all run on the phone number, which is why a multichannel design with automatic fallback survives this change unchanged. Our [multichannel OTP guide](https://www.broadnet.me/blog/multichannel-otp-verification-api-2026) and the [BroadNet OTP product](https://www.broadnet.me/products/otp) cover the pattern. ## What breaks for CRM and customer deduplication? Most CRMs key a WhatsApp contact on the phone number because SMS, voice and WhatsApp all used to share it. After usernames, a new inbound contact may arrive with only a BSUID. If you create a new CRM record for it, you will slowly duplicate customers. Four rules keep the data clean: 1. Model the BSUID as a channel identity, not as the customer ID. One customer can hold several BSUIDs (one per business portfolio) and a new one after a number change. 2. Keep a mapping table of BSUID, portfolio, phone number when known, first seen and last seen, and update it on every webhook, including user_id_update. 3. Merge on evidence, not on guesswork: a verified phone number, a login, or an order reference the customer gives in the chat. 4. Never treat the absence of wa_id as a new customer. It only means the number cannot be shared on that event. ## How do you migrate? A step-by-step checklist 1. Update webhook parsers to read user_id, from_user_id, recipient_user_id and username, and to treat wa_id and from as optional. 2. Add a BSUID column (and parent BSUID if you are a managed business) wherever you store WhatsApp contacts. 3. Backfill: for every inbound event since early April 2026, link the BSUID to the phone number you already hold. 4. Handle the user_changed_user_id system message and the user_id_update webhook by re-linking the new BSUID to the customer. 5. Add the recipient parameter to your send path, and fall back to it when you have no phone number. 6. Route OTP to the phone number, never to a BSUID, and keep SMS or voice as the fallback channel. 7. Reserve your business username in WhatsApp Manager, Meta Business Suite or through the Username API. 8. Test with a username-enabled account before usernames reach your customers. If BroadNet is your WhatsApp provider, request test access and confirm how the BSUID fields appear in the webhooks for your account before you change production code. Our [developer hub](https://www.broadnet.me/developers) and [WhatsApp Business API page](https://www.broadnet.me/products/whatsapp-business-api) have the details, and [omnichannel routing](https://www.broadnet.me/products/omnichannel) handles the SMS fallback that authentication flows now depend on. ## Frequently asked questions ### What is a WhatsApp BSUID? A business-scoped user ID: an identifier Meta assigns to each WhatsApp user for each business portfolio, so the business can message the user without knowing their phone number. It appears as user_id in webhooks. ### What does a BSUID look like? An ISO 3166 alpha-2 country code, a period, then up to 128 alphanumeric characters, for example US.13491208655302741918. Parent BSUIDs for managed businesses include ENT, for example US.ENT.11815799212886844830. ### Will I lose the customer's phone number when they adopt a username? Only in some webhooks. The number is still included if you exchanged a message or call with that number in the last 30 days, or if the user is in your contact book. Otherwise wa_id is omitted and you receive only the BSUID. ### Can I send messages to a BSUID? Yes, since July 2026, using the recipient parameter of the send API. Every message type works except one-tap, zero-tap and copy-code authentication templates, which require the user's phone number. ### Can I send authentication (OTP) templates to a BSUID? No. One-tap, zero-tap and copy-code authentication templates require the phone number. Keep a verified phone number for every account and use SMS or voice OTP as the fallback. ### Do BSUIDs work across business portfolios? No. A BSUID is unique to one business portfolio and user pair. Managed businesses can ask Meta about parent BSUIDs, which work across the portfolios enrolled together. ### Does a BSUID ever change? Yes. It is regenerated when the user changes their phone number, and Meta signals this with a user_changed_user_id system message and a user_id_update webhook. ### How do I reserve my business username? Since 29 June 2026, through WhatsApp Manager, Meta Business Suite or the Username API. An approved username becomes active when the username feature launches, and it does not hide your business phone number. ## Sources - Meta for Developers, [Business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/) (format, timeline, webhook fields, contact book, send parameter, authentication-template exception), accessed 26 September 2026. - About Meta, [It's time to reserve your WhatsApp username](https://about.fb.com/news/2026/06/its-time-to-reserve-your-whatsapp-username/), 29 June 2026, accessed 26 September 2026.