← Back to blog

WhatsApp usernames are coming: your business integration may stop getting the customer's phone number

AnuraCode

Open card index drawer full of blank cards, one raised with a red tab, next to a smartphone on a dark desk

For many businesses that sell on WhatsApp, the customer’s phone number is the key to everything. The CRM record is filed under it. The order lookup asks for it. The chatbot and the ad report rely on it. WhatsApp usernames break that assumption.

In June 2026, Meta announced that people can reserve a WhatsApp username, and said that once the feature launches, “when you message a person or business for the first time they will no longer see your phone number, if you enabled your username.” For businesses on the WhatsApp Business Platform, some new customers will arrive with a business-scoped user ID (BSUID) instead of a phone number.

This post explains what changes, who must act, and what to check in an integration. Every fact here is as of November 2026, and Meta says its documentation on this topic is subject to change.

What is changing

  • Usernames are optional, and they arrive slowly. Meta’s announcement says: “We’ll be rolling out usernames gradually over the coming months and will notify you in WhatsApp when they’re available in your country.” As of November 2026, we found no official date for a full global launch. And because usernames are optional, some customers will turn one on and others will not.
  • The phone number can be missing from webhooks. Meta’s developer documentation says: “If a WhatsApp user enables the username feature, their phone number will not be included in webhooks, unless you have interacted with the user before.”
  • A new ID is always there. “BSUIDs began appearing in webhooks in early April 2026.” The ID is in the user_id field of every messages webhook, whether or not the user has a username.

So your integration will see two kinds of customers for a long time: those who arrive with a phone number and a BSUID, and those who arrive with only a BSUID.

Who needs to act

Meta’s developer page says that supporting BSUIDs “is required for all partners and directly-integrated businesses on the WhatsApp Business Platform”. The same rule covers businesses that advertise with Click-to-WhatsApp (CTWA) ads. Meta also gives the reason: “Because you cannot control whether your users adopt usernames, you must support BSUID to avoid losing the ability to process their messages.”

In practice:

  • If a provider runs your WhatsApp integration (a business solution provider, a CRM with a WhatsApp connector, a chatbot platform), ask them how they handle BSUIDs and whether they pass the ID through to your systems.
  • If your team built the integration on the Cloud API, the work is yours.
  • If you only use the free WhatsApp Business app, the checks below do not apply: the app is a different product, and the BSUID requirements are for the Platform. Per Meta’s announcement, though, a first-time customer with a username will not show you their phone number there either.

Note that a business username hides nothing. Meta’s page says: “Business usernames are not intended for privacy, however. If you adopt a business username, it will not cause your business phone number to be hidden in the app.”

The new ID: the 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.” A few details matter for anyone who stores it:

  • Format. It starts with the user’s two-letter ISO country code (CO for Colombia, for example) and a period, “followed by up to 128 alphanumeric characters (for example, US.13491208655302741918)”. A database column sized for a phone number is too short.
  • Scope. “BSUIDs are scoped to individual business portfolios.” A company with several portfolios sees the same customer under different IDs. Meta also offers a parent BSUID that stays the same across enrolled portfolios; ask your Meta point of contact about eligibility.
  • It can change. Meta says a BSUID is “regenerated if a user changes their phone number (which triggers a system messages webhook).” Since an August 11, 2026 update, these changes arrive on the messages webhook field as system messages. Meta notes that user_id_update “is not a subscribable webhook field”.

Here is an excerpt from Meta’s example of an incoming message from a user with a username. It is illustrative only; see Meta’s page for the full payload.

"contacts": [
  {
    "profile": {
      "name": "Sheena Nelson",
      "username": "realsheenanelson"
    },
    "user_id": "US.13491208655302741918",
    "parent_user_id": "US.ENT.11815799212886844830"
  }
]

Notice what is missing: there is no wa_id with the phone number. In the same example, the message itself carries the BSUID in from_user_id and has no from field. parent_user_id appears only for businesses that use parent BSUIDs.

When you still get the phone number

Meta lists three cases where the number is still included, even for a user with a username:

  • “You have messaged or called the user’s phone number within the last 30 days of the webhook being triggered”
  • “You have received a message or call from the user’s phone number within the last 30 days of the webhook being triggered”
  • “The user is in your contact book”

The 30-day checks are made per business phone number. The contact book is a feature that Meta hosts: when you message or call a user’s phone number, or they message or call you from it, “the user’s phone number and BSUID will be added to your contact book.” Meta says no integration work is required for it, and that “prior interactions will not be retroactively captured.”

So the gap is mostly with first-time customers who have a username, and with past customers who are not in your contact book and have not talked to you recently.

What to check in your integration

1. How does it identify customers? If the phone number is the primary key in your CRM, order system or bot, a customer who arrives with only a BSUID has no key. Meta’s advice is to “build logic to support handling multiple identifiers” and “map relevant fields back to your CRM/database.” A practical approach: give each contact its own internal ID, store the phone number and the BSUID as separate fields, and allow the phone number to be empty.

2. Where does it store the new ID? Check the field length, record which portfolio the ID belongs to, and decide what happens when a system message reports a new BSUID for an existing customer. With several portfolios, look at the parent BSUID.

3. Which flows need a phone number? List where you really need it: delivery, invoices, payment links, account lookup, a sales call. BSUIDs can be used to send any type of message “except for one-tap, zero-tap, and copy code” authentication templates, which need the user’s phone number. For these flows, Meta offers a REQUEST_CONTACT_INFO button for utility and marketing templates, or as an interactive message. “If a user taps this button, their WhatsApp phone number will be shared in the message thread, and a contacts webhook will be triggered containing the user’s phone number.” Meta also tells businesses to “handle scenarios where users do not share phone numbers”. Ask only where the number is truly needed; asking in every chat adds friction for customers who chose not to share it.

4. Can it reply to a BSUID? Meta’s page says its APIs support sending messages to BSUIDs from July 2026, with a new recipient field next to to. If you send both, “to (phone number) will take precedence.” Check that your provider or library supports recipient and handles error 131062, which Meta returns when a message does not support BSUID recipients.

5. Do your reports and ad tracking depend on the number? If your lead reports, attribution or audience lists join on phone numbers, check what they do with a lead that has only a BSUID.

Where to start

Ask your provider, or your developers, three questions: Do we store user_id? Can a contact exist without a phone number? Can we send to recipient? Then re-read Meta’s page before you ship. It changed several times in 2026, most recently on November 5, when Meta added new username error codes and let the Block Users API accept a parent BSUID.

If you want a second pair of eyes on how your WhatsApp integration identifies customers, get in touch.

Sources

Read on 2026-11-08. Meta’s documentation changes often, so check the originals before you decide.