Business usernames - Kapso Documentation

Use the Username API to reserve, read, change, or delete the username for a WhatsApp business phone number. Base URL:

https://api.kapso.ai/meta/whatsapp/v24.0

Get current username

curl 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "username": "kapso_support",
  "status": "reserved"
}

username is omitted when the phone number has no username.

Get reserved suggestions

curl 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username_suggestions' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "data": [
    {
      "username_suggestions": ["kapso_support", "kapso_ai"]
    }
  ]
}

Claim or change username

curl -X POST 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "kapso_support",
    "transfer_action": "none"
  }'

transfer_action is optional:

none: default. Fail if the username belongs to another phone number in the same business portfolio.
force_transfer: move the username from another phone number in the same business portfolio.

Success response:

{
  "status": "reserved"
}

Delete username

curl -X DELETE 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/username' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "success": true
}

Statuses

reserved: approved but not visible until usernames are available in the user’s region.
approved: visible to WhatsApp users.
deleted: username was removed.

Kapso records username state when requests go through the Meta proxy. Kapso also processes Meta business_username_updates webhooks and updates the visible username on the WhatsApp configuration.

Format

Usernames:

are 3-35 characters
use English letters, digits, periods, and underscores
contain at least one English letter
do not start or end with a period
do not contain consecutive periods
do not start with www
do not end with a domain suffix like .com, .org, .net, .io, or .ai

Case is ignored for comparisons. Periods and underscores are distinct.

Common errors

Code	Meaning
`10`	Token or business asset permissions are missing
`33`	Phone number or WABA access is invalid
`100`	Username format is invalid
`147001`	Username is not available
`147002`	Account is not eligible to request a username
`147003`	Facebook account must be linked
`147004`	Instagram account must be linked
`147005`	Use `force_transfer` to move the username inside the same portfolio
`133010`	Phone number is not registered for API use

​Get current username

​Get reserved suggestions

​Claim or change username

​Delete username

​Statuses

​Format

​Common errors

​Related docs