WhatsApp Business Usernames

WhatsApp business usernames are searchable identifiers for business phone numbers. They are related to the BSUID rollout, but they are not a privacy feature for businesses.

Business vs User Usernames

User usernames let WhatsApp users show a username instead of a phone number. Business usernames let users search for and reach a business by username.

Key differences:

Business usernames are unique across WhatsApp. A business phone number can have only one username at a time, and no two phone numbers can use the same username.

Display Priority

Meta documents this chat-window display priority, from highest to lowest:

1. Saved contact name
2. Verified business name or Official Business Account name
3. Username
4. Phone number

Your business phone number still appears in the business profile.

Format Rules

Business usernames:

• may contain English letters, digits, periods, and underscores;
• do not support non-English characters;
• must be 3 to 35 characters;
• must contain at least one English letter;
• must not start or end with a period;
• must not contain two consecutive periods;
• must not start with www.;
• must not end with a domain suffix: .com, .org, .net, .int, .edu, .gov, .mil, .arpa, .html, .htm, .txt, or .xml.

Case is ignored for comparison. Periods and underscores are significant, so myid, my.id, and my_id are distinct.

Reserved Usernames

Since June 29, 2026, businesses can claim a username that WhatsApp reserved for them, or adopt a different one. You can claim a reserved username through WhatsApp Manager, Meta Business Suite, or the API. Approved claims become active once the username feature is available to users.

If the reserved username is already used by your Facebook Page or Instagram account, the business phone number must be linked to that Page or account before claiming. The person linking it needs sufficient control or manage_phone permission.

Adopt or Change Username

Since June 29, 2026, you can adopt or change a business username in Meta Business Suite, WhatsApp Manager, the WhatsApp Business app, or with Meta's username API:

POST /<BUSINESS_PHONE_NUMBER_ID>/username

{
  "username": "<DESIRED_USERNAME>",
  "transfer_action": "none"
}

username is required. transfer_action is optional:

Successful responses return a status:

Username Change Limit

Each business phone number can set a new username up to 2 times in any rolling 14-day period, or 10 times when the requested username comes back with reserved status. Requests over the limit fail with error 130429 and subcode 2655131.

• The limit applies per business phone number, not per business portfolio.
• Deleting a username does not reset the limit.
• A force_transfer counts as a change for the phone number that receives the username.
• A reserved username becoming approved does not count as a change.
• The error has no Retry-After header. You can set a new username again 14 days after the earliest change in the current window.

Read and Delete Username

Read the current username:

GET /<BUSINESS_PHONE_NUMBER_ID>/username

Response:

{
  "username": "<USERNAME>",
  "status": "approved"
}

Get reserved username suggestions:

GET /<BUSINESS_PHONE_NUMBER_ID>/username_suggestions

Delete the current business username:

DELETE /<BUSINESS_PHONE_NUMBER_ID>/username

Response:

{
  "success": true
}

business_username_updates Webhook

Meta sends the business_username_updates webhook field when a business username status changes.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "time": 1739321024,
      "changes": [
        {
          "field": "business_username_updates",
          "value": {
            "display_phone_number": "15550783881",
            "username": "jaspersmarket",
            "status": "reserved"
          }
        }
      ]
    }
  ]
}

Statuses:

The optional context property is only present when there is more to report than the status. Its only current value is revoked: Meta revoked the username and either removed it (deleted) or replaced it with a generated one (approved). A missing context does not tell you who made the change.

Subscribe each relevant app to this field if you need to track business username lifecycle.

Errors

Common username API error codes:

Dualhook Boundary

Dualhook documents business usernames but does not offer username management. There is no username editor in the dashboard, and the Runtime API does not expose the username, username suggestions, or change endpoints. Manage usernames in Meta Business Suite, WhatsApp Manager, or the WhatsApp Business app, or call Meta's API from your own Meta app.

Business username events are distinct from user BSUID message-path payloads. If Meta sends business username webhooks to your integration, treat them as management metadata; they do not contain customer message content.