# WhatsApp Usernames & BSUID

WhatsApp is gradually introducing a new identity model for business communication. Over the coming updates, users will increasingly be able to communicate with businesses not only through their phone number, but also through unique usernames such as `@username`.

This change is closely related to WhatsApp’s new privacy-focused architecture, where the personal phone number of the user may no longer be exposed to businesses at all. Instead, WhatsApp introduces new identifiers such as BSUID and expands the use of LID-based identities.

These changes are especially important for developers building CRM systems, automations, chat platforms, analytics pipelines, or customer support tools on top of WhatsApp API.

<figure><img src="/files/23VsT2T6Rqjayve7Zs08" alt=""><figcaption></figcaption></figure>

### What are WhatsApp Usernames?

WhatsApp usernames are a new identity layer that allows users to communicate without sharing their personal phone number.

Instead of exposing a real number like:

```
+1 415 555 0123
```

a user may appear as:

```json
@johnsmith
```

From the business side, this means:

* the original phone number may become inaccessible;
* the conversation will rely on a platform-generated identifier;
* applications must stop assuming that every WhatsApp user always has a visible phone number.

This architecture is already partially visible in WhatsApp today through LID identifiers and is expected to expand further with BSUID and usernames.

### What is BSUID and how is it related to LID?

In practice, BSUID is conceptually the same LID already used by WhatsApp.

You may already be familiar with LID from our article: [WhatsApp LID: Why WhatsApp hides user phone numbers](https://support.whapi.cloud/help-desk/faq/whatsapp-lid-lid?utm_source=chatgpt.com)

LID identifiers look like this:

```json
218876465958956@lid
```

Instead of a traditional phone number:

```
972559645430
```

The key idea is simple:

* WhatsApp internally knows the real number;
* the API consumer does not;
* all communication happens through an abstract identifier.

BSUID continues the same direction. The difference is mostly architectural and related to the upcoming username-based communication model. When a user chooses to communicate with a business through `@username`, WhatsApp can provide LID-style identifiers instead of exposing the personal phone number (this will be BSUID).

{% hint style="info" %}
From the API integration perspective, the important point is: the original user number may not be available anymore.
{% endhint %}

### Why this matters for developers

Historically, many integrations assumed that the WhatsApp phone number was the primary user identity.

For example:

* CRM systems stored phone numbers as unique keys;
* automations routed messages by number;
* databases used the number as the contact identifier;
* analytics pipelines assumed every chat belongs to a phone number.

With the transition to usernames and hidden identifiers, this assumption is no longer safe.

Your application architecture should now be prepared for situations where:

* a user has no visible phone number;
* only LID (BSUID) is available;
* identifiers may differ from classic numeric WhatsApp IDs.

{% hint style="success" %}
We would also like to remind you that LID (BSUID) identifiers can be used in the same way as traditional phone numbers throughout the Whapi.Cloud API.&#x20;

You can continue interacting with users normally — including sending messages, declined calls, managing chats, and using other messaging functionality — even when the original phone number is hidden by WhatsApp.
{% endhint %}

### Whapi.Cloud adaptation strategy

We continue working on preserving two critical goals for our clients:

1. Allow stable communication with users even when their number is hidden by WhatsApp.
2. Provide the original current phone number whenever WhatsApp still makes it available.

As the first step of this migration, Whapi.Cloud now supports configurable identifier output modes through the new channel setting:

```json
{  "data_mode": "..."}
```

Available modes:

```json
replace | original | extend
```

Example of changing channel settings:

```bash
curl --request PATCH \
     --url https://gate.whapi.cloud/settings \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {Your_Tokne}' \
     --header 'content-type: application/json' \
     --data '
{
  "data_mode": "extend"
}
'
```

### Default mode: `replace`

`replace` is the default mode and represents the behavior already used by Whapi.Cloud historically.

In this mode:

* WhatsApp may internally send LID (BSUID) identifiers;
* Whapi.Cloud automatically replaces them with the phone number whenever WhatsApp still provides mapping information.

This mode is designed for backward compatibility and allows older integrations to continue operating without major changes.

In other words:

* your API responses continue looking phone-based;
* your old architecture keeps working;
* Whapi.Cloud handles the identifier translation layer.

### Mode: `original`

In `original` mode, Whapi.Cloud stops replacing identifiers and returns the original WhatsApp identity exactly as provided by WhatsApp.

All identifiers become LID(BSUID)-style IDs.

Examples:

#### Check health

Before:

```json
"id": "84895265481"
```

After:

```json
"id": "139655455036346:56@lid"
```

#### Get messages

Before:

```json
"from": "972559645430"
```

After:

```json
"from": "218876465955956@lid"
```

#### Get chats / Get contacts

Before:

```json
"id": "905309174539"
```

After:

```json
"id": "128239469124835@lid"
```

This mode is useful if:

* you want maximum compatibility with future WhatsApp architecture;
* you prefer using native WhatsApp identifiers directly;
* you are already adapting your system to a phone-independent identity model.

We continue working to ensure that Whapi.Cloud endpoints operate correctly with both phone numbers and LID identifiers interchangeably.

### Mode: `extend` (Beta)

`extend` is an experimental beta mode intended for future-proof integrations.

This mode attempts to provide the fullest possible identity information simultaneously:

* LID (BSUID) identifier;
* phone number (when available);
* future username support.

Example message response:

```json
{  "chat_id": "120363420392164172@g.us",  "from": "218876465954956@lid",  "phone": "972559645430"}
```

Example contact response:

```json
{  "id": "128239469124435@lid",  "phone": "14512456538"}
```

This mode is currently under active development.

We do not recommend using it yet for production-critical systems. However, it is already useful for developers who want to start redesigning their architecture for the future WhatsApp identity model.

{% hint style="warning" %}
Most importantly, your system should no longer assume that: every WhatsApp user always has a phone number because in the upcoming WhatsApp ecosystem this may no longer be true.
{% endhint %}

As soon as WhatsApp fully exposes usernames through the API, Whapi.Cloud plans to extend this mode further by including username information directly in responses.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.whapi.cloud/help-desk/faq/whatsapp-usernames-and-bsuid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.