BSUID and Usernames on WhatsApp: Meta's Biggest API Change in Years

There is a silent change happening deep within the WhatsApp API. It doesn't appear in the changelog as a breaking change. It won't bring down your integration overnight. But, gradually throughout 2026, it will make obsolete the assumption that every customer service platform, every CRM, and every bot built in recent years carries as a fundamental truth: the customer is their phone number.

This change has a name: BSUID Business-Scoped User ID. And it comes accompanied by a feature that WhatsApp has never had, making it, finally, more similar to Instagram and Telegram: usernames.

What are WhatsApp Usernames?

In June 2026, Meta begins releasing the possibility of creating a unique username on WhatsApp for users in selected countries including Brazil. Think of something like @johnsmith or @maryoliver. The difference from a phone number is radical: the username is chosen by the user, is public by default, and allows someone to start a conversation with a business without ever revealing their number.

This is not a cosmetic change. For the customer service ecosystem, it represents an inversion of the information flow. Today, when a customer sends a message to your WhatsApp Business, you automatically receive their phone number. With usernames, if that customer has adopted a @handle, you might receive only the new identifier without the +55 11 9xxxx-xxxx.

In some aspects, the model is close to email: you can know the person's address without knowing their mobile number. But there is an important difference that we will see below: this identifier is not portable between businesses.

Android home screen with Google search — WhatsApp identifiers are moving beyond phone numbers; mobile remains the entry point

What is BSUID?

The BSUID (Business-Scoped User ID) is the identifier that Meta automatically creates for each unique pair of user + business portfolio. In other words: for each of your customers on WhatsApp, there is a BSUID generated specifically for your business.

The format is standardized: a two-character prefix with the country's ISO code, a dot, and an alphanumeric sequence of up to 128 characters. For example: BR.13491208655302741918. Simple in appearance, but with profound implications for data architecture.

The most important property of the BSUID is precisely what makes it "scoped": the same user has different BSUIDs for each business. The John Smith who talks to your business and to a competitor has one BSUID with you and a completely different one with the competitor. This is intentional and protects user privacy no company can track customer behavior in other companies using this identifier.

Starting March 31, 2026, the BSUID already begins to appear in the API webhooks regardless of whether the user has adopted a username or not. This is important: every customer of yours already has a BSUID being generated, you just need to start capturing it.

Why is This a Structural Change?

To understand the magnitude, think about how most CRM and customer service systems were built. The wa_id field the WhatsApp identifier has always been the phone number. It was simple, convenient, and universal: the same number you kept in the customer register was the same one that arrived in the webhook.

This convention lasted for more than a decade. Every database schema, every deduplication logic, every marketing automation, every bot, and every ERP integration was built on this premise. The phone was simultaneously the contact channel, the system identifier, and the CRM data.

The BSUID breaks this equivalence. From now on, the system identifier (user_id in the webhook) can exist without the phone number. And the more users adopt usernames, the higher the proportion of conversations where the wa_id (phone) will be absent or omitted.

It is no exaggeration to say that this requires an architectural review in every customer service platform that is not prepared. The good news is that the transition is gradual. The bad news is that systems that do not adapt won't explode they will silently lose conversations.

The Real Risk: Operational Silence

A term circulates among Meta API specialists to describe what happens to unprepared systems: "Operational Silence". The system seems to work. The dashboard shows no errors. But some of the conversations simply do not arrive.

This happens in two specific flows. First, in Click-to-WhatsApp ads: when a user with a username clicks on the ad and starts a conversation, the system expects a wa_id that is a phone number, doesn't find it, and either generates a duplicate record or discards the interaction. Second, in inbound service messages: users with usernames who write to your number are not recognized by the deduplication and can end up as "new" customers in the system, losing all history.

The worst-case scenario is not the system breaking you would see the error and fix it. The worst-case scenario is the system accepting the message, creating a duplicate record, and the agent assisting the "new customer" without knowing that they are someone with a 5-year purchase history.

The Contact Book: The Protection Meta Offers

To mitigate the disruption, Meta introduced a feature in April 2026 called Contact Book a contact book at the WABA level that automatically stores the phone number ↔ BSUID pairs of all previous interactions.

The Contact Book works like this: whenever a customer who has already talked to your business adopts a username, Meta maintains the association between their BSUID and the phone number you already know. For 30 days after an interaction, the customer's number continues to appear in webhooks even if they have adopted a username.

This means that your existing customer base is protected during the transition at least for a period. The problem arises with new customers who adopt a username before ever contacting your business. For them, you will receive only the BSUID, without a phone number.

The good news is that the Contact Book is enabled by default. You don't need to do anything to activate it. But you need to start capturing the BSUID now so that the association exists when usernames start to be adopted en masse.

The Change's Complete Timeline

Meta planned the rollout in well-defined phases. Understanding each stage is essential to prioritize your technical team's actions:

The critical point that many companies get wrong is thinking that the change only matters in June. In fact, the golden window is now: from the beginning of April until June, you can capture BSUIDs from your entire active customer base through the Contact Book, without waiting for them to adopt usernames. Those who do this will have the smoothest transition possible.

How the Webhook Changes in Practice

For those who work with the API directly, the change in the webhook payload is concrete. Here is how the inbound message structure looks:

{
  "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": "Olá, preciso de ajuda" },
      "type": "text"
    }
  ]
}

Note that there are now three fields in the contact object: wa_id (which may be absent for users with a username), user_id (the BSUID, always present starting March 2026), and username (the handle, if the user has adopted one). The from field in messages also starts accepting the BSUID directly.

Any system that does const customerId = message.from and assumes that the result is always a phone number must be reviewed. The from field can be a BSUID.

What to Do with Messages Without a Phone Number

One of the most frequent questions is: what about when the customer is identified only by the BSUID, without a phone number? The answer depends on your use case.

For standard customer service, the BSUID is sufficient. You can reply to the conversation, record the history, trigger automations, and even identify the customer if they are already linked to the BSUID in your CRM. The absence of the phone number does not prevent service.

For cases where the phone is necessary OTP authentication, sending confirmation SMS, integration with legacy systems that only accept phone numbers Meta created a native collection flow. WhatsApp offers a CTA button that the user clicks to authorize sharing their number with the company. This is consent-based: the user chooses whether to share it or not.

{
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": {
      "text": "To continue, we need your phone number."
    },
    "action": {
      "name": "phone_number_share",
      "parameters": {}
    }
  }
}

Important: authentication messages (OTP) only work with a phone number. The BSUID does not replace the phone for this type of communication. If your onboarding bot depends on verification via SMS, this flow must be reviewed to request the number before sending the OTP.

Impact on CRM: From Single Dimension to Hybrid Model

The most profound change is not technical it is the data model. Today, most CRMs use the phone as the primary key or as the sole WhatsApp identifier. This model needs to evolve to what specialists call a two-dimensional identity: phone AND BSUID as independent fields, both able to serve as search keys.

The schema migration involves at least four steps. First, adding the bsuid field to the contacts or customers table. Second, ensuring that the field accepts null values (for customers who have never interacted via WhatsApp after March 2026). Third, creating a search index on the BSUID field lookup queries will need to be fast. Fourth, implementing merge logic: when a message arrives with both BSUID and phone, crossing it with existing records to avoid duplicates.

ALTER TABLE contacts ADD COLUMN whatsapp_bsuid VARCHAR(135) UNIQUE;
CREATE INDEX idx_contacts_bsuid ON contacts (whatsapp_bsuid);

The risk of not doing this is the proliferation of duplicate records. The same customer enters via phone in February and via username in August, and you have two profiles in the CRM, two separate histories, and the agent assisting in August does not know that the customer was already served six months earlier.

The Correct Deduplication Logic

The customer identification logic needs to be re-implemented with a fallback strategy. The recommended hierarchy is:

1. Search by BSUID → user_id field from the webhook
2. If not found, search by phone → wa_id field
3. If not found in either, create a new record with the BSUID
4. If found by phone but has no BSUID, update the record with the BSUID

This flow ensures that existing customers are correctly identified regardless of whether they have adopted a username or not, and that the BSUID is progressively filled in your database.

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

BSUID and Privacy: What It Means for the User

From the user's perspective, the BSUID is an elegant privacy protection. By adopting a username, the user can interact with dozens of businesses without ever revealing their phone number data that today is used for SMS spam, identity tracking across platforms, and, in extreme cases, harassment.

The "business-scoped" property of the identifier goes further: even if you, company A, and company B, a competitor, shared all your customers' BSUIDs, it would be impossible to cross-reference which users are the same. John Smith has BR.aaaa1111 with you and BR.bbbb2222 with the competitor they are completely different strings.

This is a clear position from Meta in response to criticism regarding privacy that the platform has received in recent years. WhatsApp, with its 3 billion global users, is too privileged a platform to let the phone serve as a universal tracking vector.

For companies, this means that the era of treating the phone as the "CPF (social security number) of WhatsApp" is over. Identity data becomes the BSUID valid only within your portfolio, not exportable, and renewed if the user changes their number.

WABA Portability: A Critical Detail

There is a detail that most guides on BSUID do not mention, and which can cause severe headaches for companies that switch BSPs (Business Solution Providers): when migrating your WABA to another provider, Meta generates new BSUIDs for all customers.

This means that if you are storing BSUIDs in your CRM and decide to switch customer service platforms, all saved BSUIDs become invalid after the migration. The association must be redone, and the Contact Book starts from scratch.

The practical implication is simple: choose your customer service platform well before starting to store BSUIDs in production. A WABA migration after the customer base is identified by BSUID is significantly more complex than a migration today.

What Changes in Click-to-WhatsApp Ads

Click-to-WhatsApp (CTWA) ads are one of the flows most impacted by the change. Today, when someone clicks on an ad and starts a conversation, the system receives the phone and can immediately identify the lead, cross-reference it with the CRM, and trigger qualification automations.

With usernames, a user who has a @handle and clicks on the ad will start the conversation without revealing their phone. The from in the webhook will be an unknown BSUID for the CRM. The system must create a new profile based only on the BSUID and, if it needs the phone for qualification or follow-up through other channels, explicitly request it.

For performance campaigns that measure CAC (Customer Acquisition Cost) and perform attribution, this complicates tracking. If you currently use the phone to cross-reference the WhatsApp lead with the sales CRM record, this flow must be adapted to accept the BSUID as the primary attribution identifier.

Chatbots and Automations: What Needs to Change

For operations that depend on chatbots whether for lead qualification, self-service, or triage the main change is: do not assume that the phone will be available from the beginning of the conversation.

Bots that do const cpf_check = await buscarCadastro(message.from) and assume that message.from is a phone must be reviewed. Starting in June, message.from can be a BSUID. The lookup must contemplate both scenarios.

In addition, if the bot asks for CPF or email for identification and uses the phone as secondary confirmation, the flow needs to be adapted. The phone ceases to be information that the system automatically has it becomes information that must be requested when necessary.

The good news is that for most service flows opening tickets, order lookup, automated FAQ the phone was never really necessary. What was necessary was the customer's unique identifier, which can now be the BSUID.

How to Request the Phone Number When Necessary

When the business truly needs the phone number for OTP, integration with legacy systems, or delivery confirmation the correct approach is to explicitly request it using WhatsApp's native flow.

The message should be clear and contextualized, explaining why the number is necessary. Meta requires the request to be justified and the user to have control over whether to share it or not. Coercive approaches or those that block service if the number is not provided are against the platform's policy and can result in WABA suspension.

The best practice is to make the phone optional whenever possible and create an alternative service path for those who do not want to share it. In many cases, the BSUID is sufficient to offer a complete service experience and forcing the collection of the phone goes against the privacy trend that Meta is establishing.

What Changes for Those Who Use Customer Service Platforms

If you use a customer service platform (helpdesk, chatbot as a service, etc.) instead of integrating directly with the API, the technical responsibility for adapting webhooks and database schemas lies with the platform not your company.

But that doesn't mean you can just wait. What you need to verify is: is the platform I use adapting to BSUID on the correct timeline? The minimum checklist:

• Is the BSUID field already being captured in webhooks since March 31?
• Does the platform's CRM already have a field for BSUID in the contact profile?
• Does the deduplication already include lookup by BSUID?
• Is there clear communication about when this will be available?

Platforms that do not answer these questions satisfactorily by May 2026 represent a real operational risk for the second half of the year.

Usernames for Businesses: How to Claim Yours

It is not just users who can have usernames businesses can too. Meta is releasing the possibility for businesses to claim a handle based on the display name registered in WABA, the verified Meta Business account, or Facebook and Instagram handles.

Having a business username has direct benefits: customers can find your business by the handle, without needing to save the number. The link wa.me/c/yourhandle works in ads, Instagram bios, email signatures, and QR codes. It is a significant improvement in discovery and conversion.

The window for claiming begins in June 2026. Businesses with a verified WABA account have priority. It is strongly recommended to ensure that the WABA display name is correct and updated before that date the username will be derived from it.

Impact Analysis by Type of Operation

The impact of BSUID varies significantly depending on the profile of the operation:

Customer Service (CS) Medium impact. The history of existing customers is protected by the Contact Book. The biggest risk is in tickets opened by new customers without a phone number. Adaptation in deduplication resolves this.

Sales and SDR via WhatsApp High impact. Lead qualification frequently depends on crossing the WhatsApp contact with the sales CRM. With BSUID as the identifier, the lead journey must be reimagined.

Marketing and campaigns High impact. Existing broadcast lists (outbound to known numbers) do not change. But new leads captured via CTWA may arrive without a phone number, impacting segmentation and nurturing automations.

Technical Support and CX Low to medium impact. Provided the customer service platform adapts correctly, the agent won't feel any difference in service. The unified history is the greatest benefit a customer who changes numbers but keeps their username remains recognizable by the BSUID.

The New Identity Paradigm on WhatsApp

It is useful to take a step back and understand the larger movement that BSUID represents. Meta is building an identity infrastructure that works without depending on the phone number. This is not just about privacy it is preparation for a future where WhatsApp is used on devices without chips, in corporate accounts unlinked to personal numbers, and potentially in other contexts where the phone is not the natural vector.

The BSUID is the first piece of this puzzle. It ensures that even without the phone, the user's identity is stable, verifiable, and unique within a relationship with a business. The logical next step is to imagine passkey authentication, login without a number, and WhatsApp accounts linked to richer digital identities.

For the Brazilian customer service market which, via WhatsApp, is one of the most sophisticated in the world this represents an opportunity. Companies that build a data architecture and service strategy prepared for BSUID today will be years ahead of those that wait for the change to arrive before reacting.

The 5-Step Action Plan

Regardless of your tech stack, this is the recommended roadmap to prepare:

Step 1 Diagnosis (now)
Map all systems that receive or send data via WhatsApp. List all points where the phone is assumed to be mandatory: database fields, form validations, deduplication logic, CRM queries, internal APIs.

Step 2 Schema update (April/May)
Add the BSUID field in all relevant systems. Make the phone optional where possible. Implement two-dimensional lookup logic (BSUID + phone).

Step 3 Collection and enrichment (from April)
Start capturing BSUIDs from webhooks right now. Meta's Contact Book will already be mapping phone ↔ BSUID pairs use this period to enrich your existing customer database.

Step 4 Testing (May/June)
Use Meta's testing window in May to send messages using BSUID. Validate the end-to-end flow: new conversation arrives only with BSUID → deduplication works → correct history → reply is delivered.

Step 5 Post-launch monitoring (June onwards)
Monitor metrics for duplicate contacts, lost conversations, and resolution rates. Issues in these metrics after June may indicate that the BSUID adaptation was not complete.

What Tolky is Doing

Tolky closely monitors Meta's API changes and is adapting its entire contact identification infrastructure to support native BSUID. This includes data schema, smart deduplication, and integration with Meta's Contact Book.

For our customers, the transition will be seamless: service history will remain unified, BSUIDs will be automatically captured, and the platform will know how to search for the correct contact regardless of whether the message arrives with a phone number or a BSUID. No technical action will be required from your team.

If you use a different platform, now is the right time to ask your provider what their plan is for BSUID. The answer you receive will say a lot about the technical maturity of the solution you are using.

The BSUID change is not the end of the phone number on WhatsApp. The vast majority of your customers will still interact with a visible phone number for a long time. But it is the beginning of a new era in which the user's identity belongs to the user not the channel and customer service platforms will need to be more sophisticated to keep up.

Those who prepare now will go through this transition without turbulence. Those who wait will discover the problem by its symptoms: duplicates in the CRM, lost history, and automations that "simply stopped working" for a growing portion of contacts.

The choice, as always, is about when you want to be surprised: now, when there is still time to act calmly, or later, when the problem is already in production.