Skip to content

BSUID and WhatsApp Usernames: What Has Changed and What to Do Now

Meta already delivers the BSUID in webhooks and has opened business usernames. See the real timeline, what changes in your CRM, and how to ask customers for a phone number when you need one.

Marlos Carmo

Founder of Tolky

Updated on November 15, 2026

12 min read
BSUID and WhatsApp Usernames: What Has Changed and What to Do Now

Share

One change does not show up as a breaking change and will not take your integration down overnight, but it makes obsolete an assumption that many CRMs, bots, and support platforms carry: the customer is their phone number.

That change is called the BSUID, Business-Scoped User ID. It comes with a new WhatsApp feature: usernames. This article was updated on 11/15/2026 to reflect what Meta has already put into production, based on the official BSUID documentation and Meta's changelog.

What are WhatsApp usernames?

Users can pick a unique username on WhatsApp, something like @joaosilva. The rollout is gradual. On 06/29/2026 Meta opened username reservation and adoption to businesses, and trade press (Mobiletime, 07/06/2026) confirmed that users in Brazil can already choose their @username, with access still staggered.

The difference from a phone number is radical: the username is chosen by the user and lets them start a conversation with a business without revealing their number. For anyone running a WhatsApp customer service platform, that flips the information flow: before, you always received the +55 11 9xxxx-xxxx; now you may receive only an identifier.

Generic smartphone with a blank screen beside an abstract customer identity card.

What is the BSUID?

The BSUID is the identifier Meta creates for each unique pair of user and business portfolio. The format is a two-letter country prefix, a dot, and up to 128 alphanumeric characters, for example BR.13491208655302741918.

The key property is scope: the same user has a different BSUID for each business. João, who talks to your company and to a competitor, has two unrelated identifiers, which protects privacy. A BSUID only regenerates when the user changes phone number.

Since early April 2026 (Meta moved the rollout from 03/31 to "early April" in its changelog), the BSUID appears in webhooks whether or not the user has adopted a username. Every customer of yours already has a BSUID; you just need to capture it.

Why is this a structural change?

wa_id has always been the phone number. Every database schema, deduplication rule, automation, and ERP integration was built on that premise: the phone was the contact channel, the system identifier, and the CRM field all at once.

The BSUID breaks that equivalence. The system identifier (user_id) can arrive without the phone, and the more users adopt usernames, the greater the share of conversations without wa_id. Systems that do not adapt do not blow up: they silently lose conversations (we call this "operational silence", a term from this blog, not from Meta). The dashboard shows no error, but a customer with years of history shows up as "new" and the agent serves them without context.

When the phone still appears: contact book and the 30-day rule

Meta maintains a contact book hosted by Meta, at portfolio level and with no integration work, that links phone and BSUID. It only records interactions after its launch.

Per the documentation, the user's phone number keeps appearing in the webhook when:

  • there was a message or call between the user and that business phone number in the last 30 days (the rule is per business number, not per portfolio); or
  • the user is in the contact book.

Outside those conditions, wa_id and the phone in from may be omitted. On 08/24/2026 Meta also released an endpoint to check whether a user is in the contact book.

In practice: customers who have already talked to you tend to be protected; new customers who use a username arrive with only a BSUID.

Timeline (per Meta)

DateWhat happened
Early Apr 2026BSUID starts appearing in webhooks (rollout moved from 03/31)
Apr 2026Meta's contact book starts mapping phone and BSUID
05/28/2026contact_request renamed to request_contact_info
06/29/2026Businesses can reserve and adopt usernames (WhatsApp Manager, Business Suite, Business app, or Username API); sending to BSUID moved from May to July
Jul 2026Sending messages to a BSUID and the button to request a phone number become available
08/11/2026user_id_update stops being a webhook; BSUID changes arrive as user_changed_user_id system messages with previous_user_id
08/24/2026Endpoint to check contact book presence
09/15/2026business_username_updates webhook gains context: revoked
10/23/2026Limit of 2 username changes per 14 days per number (error 130429)
11/05/2026Block Users accepts parent BSUID

In short, the "get ready" window is over. The job now is to confirm that what you implemented works in production.

How the webhook changes in practice

{
  "contacts": [
    {
      "profile": { "name": "João Silva" },
      "wa_id": "5511999991234",
      "user_id": "BR.13491208655302741918",
      "username": "joaosilva"
    }
  ],
  "messages": [
    {
      "from": "BR.13491208655302741918",
      "id": "wamid.xxx",
      "timestamp": "1748822400",
      "text": { "body": "Hi, I need help" },
      "type": "text"
    }
  ]
}

That is the case where the phone is still available. When the 30-day or contact-book conditions do not hold, wa_id simply does not come:

{
  "contacts": [
    {
      "profile": { "name": "Maria Oliveira" },
      "user_id": "BR.98765432109876543210",
      "username": "mariaoliveira"
    }
  ],
  "messages": [
    {
      "from": "BR.98765432109876543210",
      "id": "wamid.yyy",
      "text": { "body": "I want to check my order status" },
      "type": "text"
    }
  ]
}

There are also new fields: parent_user_id and from_parent_user_id (the parent BSUID, in the format US.ENT.…, used across linked portfolios) and recipient_user_id in send statuses. Any code that does const customerId = message.from assuming a phone number must be reviewed.

Example: the ad lead who arrives without a phone number

Picture a lead who clicks a Click-to-WhatsApp ad and writes to the company. They use a username, have never talked to you, and so arrive with only the BSUID. A phone-bound system drops the message or creates a "ghost" record. A prepared flow does three things: creates the contact with the BSUID, asks for the phone at the right moment with the "Share contact" button (only if the process really needs it), and, once the number arrives, merges it with the existing record. This is an illustrative scenario, but it is exactly the kind of case this change makes common.

When you need the phone: the contact request button

For OTP, delivery, billing, or legacy systems, Meta offers REQUEST_CONTACT_INFO: a button in utility or marketing templates, or the request_contact_info interactive message (named so since 05/28/2026). The label is fixed ("Share Contact Info") and cannot be customized, and the phone number reaches you by webhook when the user taps the button. It has been available since early July 2026.

{
  "type": "interactive",
  "interactive": {
    "type": "request_contact_info",
    "body": {
      "text": "To continue, we need your phone number."
    }
  }
}

Two cautions. First, authentication templates (OTP: one-tap, zero-tap, and copy code) cannot be sent to a BSUID, only to a phone number; if your onboarding relies on OTP, ask for the number first. Second, the request should be contextual and optional whenever possible: Meta expects users to stay in control, and blocking service over the phone number goes against the platform's privacy direction.

CRM impact: identity with phone and BSUID

The deepest change is in the data model. The CRM must treat phone and BSUID as independent fields, either usable as a lookup key, with one internal canonical key per contact. For anyone using an AI CRM, this directly affects AI-CRM integration. The minimum steps:

  1. add a bsuid field to contacts;
  2. allow nulls (some customers have no recent interaction);
  3. index the field, since lookups must be fast;
  4. implement merge: when BSUID and phone arrive together, match against existing records.
ALTER TABLE contacts ADD COLUMN whatsapp_bsuid VARCHAR(135) UNIQUE;
CREATE INDEX idx_contacts_bsuid ON contacts (whatsapp_bsuid);

The recommended identification order is: look up by BSUID (user_id); if not found, by phone (wa_id); if neither matches, create a new record; if found by phone without a BSUID, store the BSUID.

async function resolveContact(webhook: WhatsAppWebhook): Promise<Contact> {
  const bsuid = webhook.contacts[0]?.user_id;
  const phone = webhook.contacts[0]?.wa_id;
 
  if (bsuid) {
    const byBsuid = await db.contacts.findByBsuid(bsuid);
    if (byBsuid) return byBsuid;
  }
 
  if (phone) {
    const byPhone = await db.contacts.findByPhone(phone);
    if (byPhone) {
      if (bsuid && !byPhone.bsuid) {
        await db.contacts.update(byPhone.id, { bsuid });
      }
      return byPhone;
    }
  }
 
  return db.contacts.create({ phone, bsuid });
}

Without this, the same customer enters by phone in February and by username in August, and you end up with two profiles and two histories. To see why the phone number was never a good CRM identifier, also read WhatsApp is not a CRM.

Privacy and identifier scope

The BSUID is a privacy protection: by adopting a username, the user can talk to many businesses without exposing their phone. Even if two companies shared all their BSUIDs, they could not tell which users are the same. For businesses, the era of treating the phone as WhatsApp's "national ID" is over: the BSUID is valid within your business portfolio and regenerates if the user changes number. Meta reports that WhatsApp has more than 3 billion monthly users, which explains the caution about a universal identifier.

Switching providers: validate continuity

An earlier version of this text claimed that moving your WABA to another provider generates new BSUIDs. Meta's documentation does not say that: BSUIDs are scoped to the business portfolio and only regenerate when the user changes number. Even so, if you plan to switch providers, ask how the contact book and the BSUID-to-phone mapping will be exported and preserved. Also remember that sending to a BSUID tied to a number in another portfolio fails, and that the parent BSUID can be used across linked portfolios.

Click-to-WhatsApp ads, chatbots, and automations

In CTWA ads, the from of a user with a username is a BSUID unknown to your CRM. If you use the phone number to match the lead to your sales CRM and measure CAC, attribution must accept the BSUID as the primary identifier.

In chatbots, do not assume the phone will be available from the start. Bots that call lookupCustomer(message.from) must handle both cases. For most flows (opening a ticket, checking an order, FAQ), what always mattered was a unique customer identifier, not the phone itself. If the bot confirms identity with a tax ID or e-mail and uses the phone as a secondary check, adapt the flow to ask for the data only when needed.

Usernames for businesses

Businesses can reserve and adopt a username since 06/29/2026, through WhatsApp Manager, Business Suite, the Business app, or the Username API. A username makes the brand easier to find without relying on the number. Requirements cited in the documentation include:

  • a sufficient portfolio messaging limit (error 147002 otherwise);
  • a number registered on the API;
  • a link to the Page or Instagram account if the username is already used there;
  • at most 2 changes per 14 days per number (error 130429, since 10/23/2026).

Mind the link format: the official documentation does not describe a wa.me/c/... pattern, and third-party guides cite wa.me/<username>. Check the link generated by WhatsApp Manager itself before using it in ads, bios, and QR codes. The documentation also does not mention priority for verified businesses.

Impact by type of operation

Customer service: medium impact. Existing customers tend to be in the contact book; the risk is in new customers without a phone. Adjusting deduplication solves it.

Sales and SDR: high impact, because qualification crosses WhatsApp with the CRM. See how to redesign the journey in B2B lead qualification with AI.

Marketing and campaigns: high impact. Known lists do not change, but new CTWA leads may arrive without a phone, affecting segmentation and nurturing. Remember that re-engaging outside the 24-hour window requires a template and opt-in, and every message is charged: see the new WhatsApp Business pricing.

Support and CX: low to medium impact, as long as the platform adapts. A customer who changes number but keeps the username stays recognizable.

Revised action plan

  1. Diagnosis: list every place where the phone is assumed mandatory (database, validations, deduplication, queries, APIs).
  2. Schema: add the BSUID, make the phone optional where possible, and implement dual lookup.
  3. Capture: confirm in production that user_id is stored from every webhook, and use the contact book to enrich the base.
  4. End-to-end test: simulate a conversation that arrives with only a BSUID, check deduplication, history, and reply delivery, and test the phone request with request_contact_info.
  5. Monitoring: track contact duplication, lost conversations, and the user_changed_user_id system message.

Where Tolky fits

For Tolky, identity is part of the service chain: the goal is to keep the customer's history unified, with the AI and human agents seeing the same contact whether the conversation arrives with a phone or a BSUID. The exact behavior with BSUID, the contact book, and the phone request button in your operation should be validated with the team. If you use another platform, ask your provider: has the BSUID been captured since April? Is there a field on the contact profile? Does deduplication consider both identifiers? The answer says a lot about the solution's maturity.

Want to validate your contact base for the BSUID? Talk to the Tolky team. To understand the per-message cost impact, also see the new WhatsApp Business pricing and our review of Gupshup's BSUID announcement.


The BSUID is not the end of the phone number on WhatsApp: most of your customers will still show up with a phone for a long time. But user identity now belongs to the user, and teams that adapted avoid CRM duplicates, lost history, and automations that "just stopped working" for a growing share of contacts.

Share

Tags

Cited in

About the author

Marlos Carmo

Founder of Tolky

Marlos Carmo is an AI entrepreneur and founder of Tolky, the conversational-era infrastructure and AI CRM that unifies intelligent service, multi-channel support (such as WhatsApp and voice), live CRM, and operational intelligence in a single ecosystem. He is a finalist for the SXSW Innovation Awards and a member of Francesco's Economy, a global network of young entrepreneurs focused on innovation and social impact. He works connecting Artificial Intelligence and digital transformation in projects for large organizations.

Next step

Want to bring this to your operation?

Tati, Tolky's AI assistant, understands your scenario in a few questions, suggests the best path and connects you with someone from the team, with full context.

Read also