Reserve and check a WhatsApp account username

Set & Get WhatsApp account username via API

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

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.

Reserve a username

Set account usernameWhapi Cloud - Whatsapp API for developers

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

Example request:

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

Get account usernameWhapi Cloud - Whatsapp API for developers

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, it can also be used to check the username state of a customer’s connected number.

Example request:

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

Example response

{
  "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.