Skip to main content
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

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