> For the complete documentation index, see [llms.txt](https://learn.doubletick.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.doubletick.io/meta-business-setup/business-usernames-and-bsuid/understanding-whatsapp-usernames-and-bsuid.md).
# Understanding WhatsApp usernames and BSUID
Learn how WhatsApp's username rollout affects customer identification, how BSUID works, and how to update your workflows while preserving existing message setups.
#### What's covered
* [Why WhatsApp is introducing usernames](#why-whatsapp-is-introducing-usernames)
* [What is BSUID](#what-is-bsuid)
* [What's actually changing](#whats-actually-changing)
* [What's not changing](#whats-not-changing)
* [Important limitation: authentication messages](#important-limitation-authentication-messages)
* [Who can see a customer's BSUID](#who-can-see-a-customers-bsuid)
* [What you need to do to prepare](#what-you-need-to-do-to-prepare)
* [Frequently asked questions](#frequently-asked-questions)
#### Why WhatsApp is introducing usernames
Starting in 2026, WhatsApp is rolling out usernames in phases to give users the option to message businesses without sharing their phone numbers. This feature allows potential customers to browse, ask quick questions, and interact with your business while preserving their privacy.
Key benefits include:
* Easier discovery: Customers can search for and message your business username directly without saving or remembering a phone number.
* Business username adoption: Businesses can also reserve a username for their WhatsApp API numbers to improve brand discovery.
* Protected verification: Green tick verified business status and brand identification remain fully protected throughout this transition.
{% hint style="info" %}
Note: If you haven't reserved your brand username yet, see [How to reserve your business username](/meta-business-setup/business-usernames-and-bsuid/how-to-reserve-your-business-username.md).
{% endhint %}
#### What is BSUID
When a customer messages you using a username instead of their phone number, WhatsApp provides a BSUID (Business-Scoped User ID) in place of that phone number as the primary customer identifier.
**Key characteristics of BSUID:**
* **Unique per business**: The same customer receives a different BSUID for every different business they message to protect their privacy.
* **Automatically generated**: BSUIDs appear in your webhooks automatically the moment an eligible customer initiates contact.
* **Scoped to your business portfolio**: It is tied exclusively to your specific business portfolio and is not shared across unrelated organizations.
* **Format requirements**: A BSUID looks like `US.13491208655302741918` (starts with a two-letter country code, followed by a period, then an alphanumeric string up to 128 characters).
> **Important**: Always use the entire BSUID string exactly as provided. Shortening, truncating, or editing any part of the string will cause API requests to fail.
#### What's actually changing
The primary shift is moving from phone numbers as the sole contact identifier to supporting both phone numbers and BSUIDs.
* **New customer entries**: If a new customer starts a chat via a username, you may only receive their BSUID instead of a phone number.
* **Phone number visibility**: A customer's phone number may still appear if you have interacted recently or if they are already saved in your existing contact records.
* **System requirements**: Your CRM, chatbot logic, and inbox workflows must be updated to handle contacts identified exclusively by BSUID.
#### What's not changing
Most core messaging features, rates, and historical data remain unchanged:
* Message delivery: Sending text, media, and interactive templates works identically using BSUID instead of a phone number.
* Billing and 24-hour windows: Pricing logic and the 24-hour conversation window apply identically whether using phone numbers or BSUIDs.
* Existing contact records: Saved phone numbers from past chats, order forms, or ad leads will continue working as usual.
* Standard users: Customers who have not set up a username will continue to share their phone numbers.
#### Important limitation: authentication messages
You cannot send OTP or verification code messages using a BSUID alone. Authentication templates (including one-tap, zero-tap, and copy-code formats) strictly require a real phone number. If your business relies on sending OTPs or verification codes, you must collect and save the customer's phone number during your conversation flow.
#### Who can see a customer's BSUID
A customer's BSUID shows up in the customer details panel, and who gets to see it there is controlled by a role permission called **View Customer BSUID**.
* Team members with this permission can see the BSUID in the customer details panel.
* Team members without it won't see the BSUID.
* By default, only Owners and Team Leads have this permission.
{% hint style="info" %}
See [How to set permissions for custom organization role](/settings/manage-roles/how-to-set-permissions-for-custom-organization-role.md) to grant this permission to a custom role.
{% endhint %}
**Good to know:** this permission only controls whether the BSUID shows in the customer details panel. If a customer doesn't have a WhatsApp profile name, their BSUID may still appear as their name in the chat list.
#### What you need to do to prepare
To prepare your organization and technical setup for BSUID updates, complete the following preparation checklist:
* **Update system logic**: Adjust your CRM, chatbots, and internal automation logic to accept BSUID as a valid primary key.
* **Build OTP fallback flows**: Add explicit prompt steps in your conversation flows to collect phone numbers whenever authentication is needed.
* **Check third-party integrations**: Verify that external tools connected alongside DoubleTick can process non-numeric contact identifiers.
* **Review contact exports**: Confirm that contact export templates and reporting workflows include the BSUID data field.
* **Review who can see BSUIDs**: Check which custom roles have the View Customer BSUID permission and adjust it if needed.
#### Key takeaways
* BSUIDs replace phone numbers for new customers who initiate conversations using WhatsApp usernames.
* Messaging workflows, template delivery, and 24-hour conversation billing remain completely unchanged.
* Authentication messages (OTPs) strictly require a verified phone number and cannot be delivered via BSUID alone.
* The View Customer BSUID permission controls who can see a customer's BSUID in the customer details panel — only Owners and Team Leads have it by default.
#### Frequently asked questions
**Can I search for or message a customer using just their username?**\
No. A username alone isn't enough to start a conversation. You need either the customer's phone number or their BSUID, and you only receive their BSUID after they've messaged you, tapped an ad, or scanned a QR code that starts the conversation.
**Does changing a username change the customer's BSUID?**\
No. The BSUID is tied to the customer's phone number, not their username. It only changes if the customer changes their actual phone number.
**Can I still message customers using their phone number?**\
Yes. As long as you have a customer's phone number on file, it remains a valid way to message them.
**What if a customer turns on username protection in the middle of an existing conversation?**\
Nothing changes for that conversation. Any phone number you'd already captured stays in your records and continues to work.
**Does this affect my messaging limits or conversation-based pricing?**\
No. Pricing and the 24-hour conversation window work exactly the same, whether a customer is identified by phone number or BSUID.
**Who can see a customer's BSUID?**\
Only team members with the View Customer BSUID permission. Owners and Team Leads have it by default; other roles need it turned on.
#### Related topics
* [How to reserve your business username](/meta-business-setup/business-usernames-and-bsuid/how-to-reserve-your-business-username.md)
* [How to add a share contact info button to a template](/meta-business-setup/business-usernames-and-bsuid/how-to-add-a-share-contact-info-button-to-a-template.md)
* [How to set permissions for custom organization role](/settings/manage-roles/how-to-set-permissions-for-custom-organization-role.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://learn.doubletick.io/meta-business-setup/business-usernames-and-bsuid/understanding-whatsapp-usernames-and-bsuid.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
