Business username rules for WhatsApp business phone numbers, including format, display priority, reserved usernames, management APIs, webhook updates, and errors.

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:

Area	User username	Business username
Privacy effect	Can hide the user's phone number in the app and in some payloads.	Does not hide the business phone number.
Mapping	One username per WhatsApp user.	One username per business phone number.
Searchability	User-focused identity.	Users can search the exact business username to reach the business.
API impact	Drives BSUID and optional `wa_id` behavior.	Has username management APIs and status webhook.

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:

Saved contact name
Verified business name or Official Business Account name
Username
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-like suffix such as .com, .org, .net, .edu, .gov, .mil, .us, .in, or .html.

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

Reserved Usernames

Before broad username availability, Meta may reserve usernames for a business. You can claim a reserved username through WhatsApp Manager, Meta Business Suite, or the API.

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

Meta's username API lets you adopt or change a business username:

POST /<BUSINESS_PHONE_NUMBER_ID>/username

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

username is required. transfer_action is optional:

Value	Behavior
`none`	Default. Do not transfer a username already used on another phone number in the same portfolio.
`force_transfer`	Move the username from another phone number in the same portfolio to this phone number.

Successful responses return a status:

Status	Meaning
`approved`	Username has been approved and will be visible when the feature is available.
`reserved`	Username is reserved and approved, but not yet visible to users.

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_update Webhook

Meta is adding a business_username_update webhook field for business username status changes.

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

Statuses:

Status	Meaning
`approved`	Username is approved and visible to WhatsApp users.
`reserved`	Username is reserved but not visible yet.
`deleted`	Username was deleted. `username` can be omitted.

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

Errors

Common username API error codes:

Code	Meaning
`10`	App or system user lacks permission for the action.
`33`	Invalid phone number ID, deleted WABA, or missing `whatsapp_business_management` grant.
`100`	Invalid username format.
`147001`	Username unavailable or failed internal checks.
`147002`	Business portfolio is not eligible; a higher messaging limit may be required.
`147003`	Facebook Page account is not linked.
`147004`	Instagram account is not linked.
`147005`	Username transfer required; retry with `force_transfer` if appropriate.
`133010`	Business phone number is not registered for API use.

Dualhook Boundary

Dualhook documents business username behavior but does not currently provide a dashboard editor for business usernames. Manage usernames in Meta Business Suite, WhatsApp Manager, WhatsApp Business app, or Meta's API.

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.

WhatsApp Business Usernames