> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/users/reserve-and-check-a-whatsapp-account-username.md).

# Reserve and check a WhatsApp account username

WhatsApp is introducing usernames, allowing users to be found by `@username` instead of relying only on phone numbers.

This improves privacy and gives personal accounts, creators, and brands a more recognizable identity inside WhatsApp.

For more context, see: [WhatsApp usernames and BSUID](https://support.whapi.cloud/help-desk/faq/whatsapp-usernames-and-bsuid)

{% hint style="info" %}

### Current status

At the moment, this method allows you to **reserve** a WhatsApp username.

We are monitoring WhatsApp updates and will adapt the API if WhatsApp changes the username registration flow or related architecture.
{% endhint %}

### Reserve a username

{% embed url="<https://whapi.readme.io/reference/setusername>" %}

Use the **Set account username** method: `PATCH https://gate.whapi.cloud/users/username`

Example request:

```bash
curl --request PATCH \
  --url https://gate.whapi.cloud/users/username \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <CHANNEL_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "reserve": true,
    "username": "coolnickname"
  }'
```

### Request body

* `reserve` — set to `true` to reserve the username.
* `username` — the username you want to reserve for the connected WhatsApp account.

### Check the current username

{% embed url="<https://whapi.readme.io/reference/getusername>" %}

Use the **Get account username** method: `GET https://gate.whapi.cloud/users/username`

This method shows the username state for the WhatsApp account connected to your Whapi.Cloud channel.

For [partners](/help-desk/partner-documentation/partner-program-guidelines/workflow-step-by-step.md), it can also be used to check the username state of a customer’s connected number.

Example request:

```bash
curl --request GET \
  --url https://gate.whapi.cloud/users/username \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <CHANNEL_TOKEN>'
```

### Example response

```json
{
  "username": "whapiassistente",
  "state": "RESERVED",
  "pin": null
}
```

### Response fields

* `username` — the username reserved or assigned to the connected WhatsApp account.
* `state` — the current username state. For example, `RESERVED`.
* `pin` — reserved for additional username-related verification data if required by WhatsApp.

### Important notes

* Username availability and behavior depend on WhatsApp.
* Reserving a username does not necessarily mean that username-based messaging is already available for the account.
* If WhatsApp updates the username flow, Whapi.Cloud will adjust the API behavior accordingly.
* Use `GET /users/username` to check the current state after reservation.