WhatsApp usernames and Business-scoped user IDs (BSUID)
WhatsApp is introducing usernames. A user can pick a username and be identified by it instead of by their phone number. When that happens, Meta stops sending you their phone number and identifies them to your business by a Business-scoped user ID (BSUID) instead.
Your conversations keep working. Yellow.ai recognises these users, keeps their history, and your AI agents keep replying — no configuration is required. This page explains what Meta changed, what Yellow.ai does about it, what you will see, and the few places where you need to check your own setup.
1. What Meta changed
| Before | After a user adopts a username |
|---|---|
| Every webhook carried the user's phone number | The phone number may be absent |
| You identified a user by their phone number | Meta identifies them by a BSUID, always present |
| A user was the same person to every business | A user has a different BSUID for each business |
Two separate things arrived together, and it helps to keep them apart:
- A username is what the user chose, like
akhil.singh. It is a display handle. They can change it. - A BSUID is what Meta assigns. It is a permanent-ish identifier scoped to your business. The user never sees it.
Adopting a username is the user's decision. You cannot request it, see who has one before they message you, or opt out of receiving BSUIDs.
2. What a BSUID looks like
IN.25509570302052184
The first two letters are the user's country (ISO 3166 alpha-2), then a dot, then up to 128 letters and digits. Businesses using parent-level identifiers also see an ENT. form:
IN.ENT.11815799212886844830
What matters about it:
- It is not a phone number. It cannot be dialled, formatted as a number, or matched against a contact list. Any phone-number validation will reject it.
- It is unique to your business. The same person has a different BSUID with every business they message. You cannot share, resell or cross-reference BSUIDs between businesses, and a BSUID from one WhatsApp Business Account will not work from another.
- It arrives for every user, not only those with usernames. Meta includes it in all incoming message webhooks.
- It changes if the user changes their phone number. See Limitations.
3. When the phone number is missing
Only for users who have adopted a username, and only outside a 30-day activity window. Meta still sends you the phone number if any of these is true:
- You messaged or called the user in the last 30 days.
- The user messaged or called you in the last 30 days.
- The user is already in your contact book.
The 30-day window is counted per business phone number, not per account. A user who is active on one of your WhatsApp numbers shows a phone number there, and may still show only a BSUID on a conversation with a different number of yours.
This is why the behaviour can look inconsistent: an active customer keeps showing a phone number, while one who has been quiet for a few months suddenly appears as IN.2550…. Both are normal.
4. How Yellow.ai keeps the conversation together
This is the part you do not have to configure, and the part worth understanding.
When a message arrives with only a BSUID, Yellow.ai looks that BSUID up against the users it already knows for your bot. If it finds the person, the message continues their existing conversation. If it does not, the person is new and a profile is created for them.
| Situation | What happens |
|---|---|
| A customer you already know adopts a username, and their phone number stops arriving | Recognised as the same person. Same conversation, same history, same profile. |
| A brand-new user messages you with a username and no phone number | A new profile is created, identified by their BSUID. Your agent replies normally. |
| That user later shares their phone number | The number is added to their profile. Their identity does not change, so the conversation does not split in two. |
| Your agent replies to a user who has no phone number | The reply is addressed by BSUID and delivered normally. |
| Delivery receipts (sent, delivered, read, failed) | Attributed to the right conversation either way. |
The guarantee that matters: a customer who adopts a username does not turn into a new contact. Their history stays intact and your reporting does not double-count them.
5. Where the identity is stored, and what you can use
Every WhatsApp user profile can carry three identity values. You can read all of them in flows and see them in the user's profile.
| On the profile | Flow variable | Present when |
|---|---|---|
| Phone number | {{profile.phone}} | Meta sent it, or the user shared it with you |
| Username | {{profile.username}} | The user has adopted one |
| BSUID | stored on the profile | Always, once the user has messaged you |
{{profile.phone}} can be empty for a username user. If a flow branches on the phone number, sends an SMS, or hands the number to another system, add a fallback — or ask for the number using the node in the next section.
What you see where
- Inbox — a conversation with no known phone number is identified by the BSUID, so agents see
IN.25509570302052184where a number would normally be. The username, if the user has one, is on their profile. - Reports and exports — the user identifier column may contain a BSUID. Treat that column as an opaque string, not a number.
- Search — you can find these users by BSUID or username. Searching by phone number only works if the number is known to us.
6. Asking a user for their phone number
If you need a phone number that Meta is not sending you, ask for it. WhatsApp has a built-in way to do this, and Yellow.ai exposes it as a flow node.
Studio → Build → Flows → add node → Prompts → Others → WhatsApp Request Contact Info
Configure one thing: the message body, the text shown above the button. WhatsApp supplies and translates the button itself, so there is nothing else to set.
When the user taps it, WhatsApp shows them their own contact card and asks them to confirm. If they share:
- the number is captured into the variable you chose in Store response in;
- for a user identified only by a BSUID, it is also saved to their profile, so
{{profile.phone}}works from then on; - the flow continues to the next node.
If they decline, or type something instead of tapping, the flow takes the node's fallback branch — nothing is stored. Design that branch as you would for any other question the user can refuse.
This node only works on WhatsApp. It does nothing on other channels, so put it behind a channel check if the flow is shared.
7. What you need to check
For normal conversations, nothing — it works out of the box. Review these only if they apply to you.
Your own integrations
This is the one place that may need changes on your side. If you built anything that assumes the user identifier is always a phone number, review it:
- Webhooks and API integrations that parse, validate or reformat the user ID.
- CRM or database lookups keyed on phone number.
- Custom code or functions in flows that apply phone formatting — adding a country code, stripping a
+, checking the length.
A BSUID fails every phone-number validation. Code that assumes digits may error, or quietly mishandle these users.
One-time passwords
Authentication templates cannot be delivered to a user who has only a BSUID. Meta requires a phone number for them, and every authentication template — copy-code, one-tap and zero-tap alike — is refused with error 131062.
If you send OTPs on WhatsApp, plan for this: collect the number first with the node in section 6, then send the OTP once {{profile.phone}} is populated.
Campaigns and notifications
Outbound campaigns currently target phone numbers. A user you only know by BSUID is not reachable by campaign yet. Collecting their number brings them back into your reachable audience.
On-premise and third-party providers
BSUID messaging requires the WhatsApp Cloud API. On an on-premise or third-party BSP connection, a message addressed to a BSUID is rejected with a clear error rather than sent incorrectly. Migrating to Cloud API is the fix.
8. How to check it is working
- Open a conversation in the Inbox for a user with a username. You should see one conversation with its full history, not a new empty one.
- Check that user's profile. It should show the username and the BSUID; the phone number may be empty.
- In a test flow, print
{{profile.phone}}and{{profile.username}}to see what is populated for that user. - Add the WhatsApp Request Contact Info node, store the response in a variable, and confirm the number arrives and the flow moves on.
- Share a contact card by hand from the WhatsApp attachment menu — that is a different thing and should behave exactly as it always has.
9. Limitations
| Limitation | Detail |
|---|---|
| Cloud API only | Messaging a BSUID requires the WhatsApp Cloud API. On-premise and third-party BSP connections reject it. |
| Authentication templates | Cannot be sent to a BSUID. Meta rejects every OTP template type with 131062. Collect the phone number first. |
| Campaigns | Outbound campaigns target phone numbers, so BSUID-only users are not yet reachable by campaign. |
| Identity changes | If a user changes their phone number, Meta issues a new BSUID. The event is recorded but the old and new identities are not linked automatically, so that user may appear as a new contact. |
| Cross-business | A BSUID is meaningful only to your business, and only from the WhatsApp Business Account it was issued for. |
| Group messaging | Not affected — the WhatsApp channel does not currently support group messaging. |
10. Errors you may see
| Code | Meaning | What to do |
|---|---|---|
131062 | This message type cannot be sent to a BSUID. | Authentication templates need a phone number. Collect it first, then send. |
Other WhatsApp errors are unchanged — see Common WhatsApp message errors.
11. Frequently asked questions
Do I need to enable anything? No. Support is active on your WhatsApp channel with no configuration.
Will my existing conversations break? No. A customer who adopts a username keeps the same conversation, history and profile.
Why do some users show a phone number and others a BSUID? Because of the 30-day activity window in section 3. Recently active users keep showing a phone number.
Can I still send messages to a phone number? Yes. Nothing changes for users whose phone number is available, which is the large majority today.
Is the BSUID the same as the username?
No. The username is what the user chose to display, like akhil.singh, and they can change it. The BSUID is the identifier Meta assigns your business, like IN.25509570302052184, and the user never sees it.
A user changed their username. Do I lose them? No. The username changes; the BSUID does not, so the conversation continues.
Can I look up a user by BSUID in another system? Only in your own. A BSUID has no meaning outside your business.
Will my WhatsApp pricing or messaging limits change? No. Usernames and BSUIDs do not affect pricing or messaging limits.
How do I get a user's phone number if they have not shared it? Use the WhatsApp Request Contact Info node — see section 6.