WhatsApp is rolling out usernames: a way to identify a WhatsApp account by name instead of by phone number. This affects two different things, so we've split this article in two:
Your contacts: the people you contact or who message your business
Your business: your own WhatsApp account
What it means for you contacts ?
Until now, every person messaging you was identified by their phone number. Now, people can set a personal username and choose to hide their phone number behind it.
From now on, when you message with a contact on WhatsApp, you'll see one of three things:
Phone number only: the contact hasn't set a username, nothing changes.
Username only: the contact has a username and has chosen to hide their phone number. You'll see their username, not their number.
Username + phone number: the contact has a username, but because you already had a conversation with them, you can still see both.
This is entirely each contact's personal choice, some will start showing a username, others won't.
What changes in your WAX inbox: for contacts who hide their number, you'll see their username where you used to see a phone number.
Behind the scenes, WhatsApp now identifies every contact with a permanent ID (a "business-scoped user ID"), instead of relying only on the phone number. WAX already uses this ID to keep track of your conversations, so:
You won't lose any conversation history.
You can keep messaging these contacts exactly as before.
Nothing breaks if a contact changes their username later, WAX still recognizes them as the same person.
If a contact hides their number and you've never messaged with them before, their phone number simply won't be available to you, only their username and WAX's internal contact ID.
Can I ask new customers for their phone number? Yes. Add the REQUEST_CONTACT_INFO button to your flows (available soon). Once a customer taps it, their number is shared with you instantly.
Will I be able to see the BSUID? BSUID is used internally. It's not visible in WAX. You'll see customer usernames in your inbox instead.
Can I search customer chats by username? Yes. For new customers who connect via username, you can search your WAX inbox using their username, just like you search by phone number today. (available soon)
What does it mean for your WhatsApp business account?
Separately, you can also claim a username for your own business, the same way a company might claim a handle on social media.
The important difference: unlike your contacts, your business phone number cannot be hidden. Claiming a username is purely an added identity.
Your clients will keep seeing your business's phone number exactly as they do today, whether or not you set a username.
In short, usernames give end users a genuine privacy option (hide the number), while for businesses it's a branding/identity option only.
A few practical notes if you're considering claiming one:
They can only contain Latin letters (a-z), numbers (0-9), periods (.), and underscores (_);
Accented characters (such as ñ, é, ü) are not supported and will cause the request to fail;
They must be between three and 35 characters long;
They must contain at least one letter of the Latin alphabet (a-z, A-Z);
They must not start or end with a period, or contain two periods in a row;
They must not start with www;
They must not end with a domain suffix (e.g., .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html, and so on);
Case is not considered when comparing usernames, unlike periods and underscores. For example, myID and myid are considered the same username, while myid, my.id, and my_id are considered different.
If a reserved username is already in use by your Facebook Page or Instagram account, you must link your business phone number to your Facebook Page or Instagram account before you can claim the username.
You have to complete Business Verification: the phone number used must be linked to a business account that has completed the standard business verification process.
You have to have a high messaging limit: the Business Portfolio holding the WABA and the associated number must have a high message limit (min 2,000 contacts/day). If this is not the case, the business receives an "Account not eligible" message.
You have to have a medium or high quality score: this is an internal Meta classification that WAX does not have access to, so we are unable to share your organization's score with you. You may encounter an error when setting your username because of this. We recommend checking regularly.
Each username is globally unique across WhatsApp, first come, first served.
Claiming is done through WAX here (if you don't have direct credit lines) or via your WhatsApp Manager (if you have a direct credit line) following these instructions :
First, go to your WhatsApp account via this page.
Select the WhatsApp account for which you want to reserve a username.
Then click on WhatsApp Manager (at the bottom of the Summary tab). A new tab will open.
Then go to Account tools > Phone numbers > Profile tab > Username.
Set your Username.
This is a platform-level change from WhatsApp, and WAX already supports it under the hood. Your inbox, contact records, and message history keep working as usual, you'll simply start seeing usernames alongside (or instead of) phone numbers for some contacts.
Claiming a username for your own business is entirely optional. |
I can't set up a username for my WhatsApp account, what to do?
These are the main reasons and associated solutions that prevent you from defining a username :
Code | Details | Possible Reasons and Solutions |
| App not authorized to perform this action | Confirm that the system user whose token is used in the request has appropriate access to business assets on the WhatsApp Business Account: either full control or partial access to the phone numbers. |
| Invalid ID | (1) The business phone number ID is not valid, (2) the WhatsApp Business Account associated with this business phone number has been deleted, or (3) the user whose token was used in the request has not granted the app the whatsapp_business_management permission (which requires Advanced Access if you are a solution provider) |
| Invalid parameter | |
| Feature unavailable for your account. | Meta decided not to make this feature available for your account. Please, try again regularly. |
| Profile name unavailable | The profile name has already been claimed, does not meet our internal checks, or is not available on the platform. Try requesting a different one. |
| Account not eligible to request a profile name | The business portfolio that owns the WhatsApp Business Account and the business phone number must have a higher messaging limit. |
| Facebook account not linked | You must link the phone number to the Facebook Page that is already using the requested profile name. |
| Instagram account not linked | You must link the phone number to the Instagram account that is already using the requested profile name. |
| Profile name transfer required | The requested username is currently in use by another business phone number in your business portfolio. To transfer it to this phone number, resend the request replacing transfer_action with force_transfer. |
| Account not registered | The business phone number must first be registered before it can be used with the API. |
Can I change or delete my username?
Having a Business username is completely optional. You can change your username or delete it at any time. Keep in mind that once you change or delete a username, it may become available for others to claim.
Customers can’t find your business username
⚠️ WhatsApp has not yet shipped the feature to every region ⚠️
But once it's done, customers need to enter your exact username (including the @) directly in WhatsApp to find you as there's no searchable directory. If customers can't find your business username:
Make sure your username is active, not just reserved. Reserved usernames aren't visible or searchable until they become active. You'll be notified in WhatsApp when your username is ready to use.
Check for typos. Usernames are case-sensitive to formatting and customers must enter the exact spelling, including any numbers, underscores, or periods.
Share your username proactively. Since there's no directory, customers need to know your exact username.
Link your WhatsApp Business with Facebook and Instagram to give customers another way to reach you via the WhatsApp contact button on your profiles.