> For the complete documentation index, see [llms.txt](https://help.1msg.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.1msg.io/docs/api-1msg/bsuid-new-whatsapp-user-identifier-and-changes-in-1msg.md). # ❗️ BSUID: New WhatsApp User Identifier and Changes in 1MSG Previously, WhatsApp identified users by phone number.\ Now Meta is gradually moving to the BSUID identifier — a unique WhatsApp user ID that works even when the phone number is hidden. Throughout 2026, users will be able to hide their phone number by setting a username in their profile. After that, sending by phone may stop working if you have not previously saved the BSUID ↔ phone mapping. BSUID becomes the new identification method, and integrations that rely only on phone will break over time. {% hint style="info" %} BSUID is a unique identifier that WhatsApp assigns to each user within your specific business portfolio. {% endhint %} We already pass BSUID in webhooks, and username rollout will begin in June 2026 at the country level, after which adoption will happen gradually. ### Backward Compatibility We have made sure that your current integrations continue to work without changes. Starting in May 2026, 1MSG stores an internal mapping for your client: ``` BSUID ↔ phone ``` This allows us to perform internal routing. Specifically, you will be able to: * send an outgoing message as usual by phone number, even if your client has hidden their number, because we have already saved the BSUID and will automatically route to BSUID; * send an outgoing message in either way: by phone number or by BSUID, whichever is convenient; * maintain compatibility with legacy integrations. {% hint style="info" %} Please note: if there is no BSUID ↔ phone mapping in the 1MSG database and the client has hidden their phone number in WhatsApp, you will not be able to message them first by phone number — the message will not be delivered. To create a BSUID ↔ phone mapping in 1MSG, the client must either message you first or receive a message from you before hiding their phone number. {% endhint %} You will be able to send outgoing messages **using both phone number and BSUID:** * via `phone` — accepts both {{phone}} and {{bsuid}}; * via `chatID` — accepts both {{}} and {{bsuid\@lid}}; Expected changes in the API documentation:\ In the message sending request body, in addition to `phone` and `chatID`, a new parameter `bsuid` will be introduced. This parameter will become available after enabling Meta message sending via bsuid. We will notify you separately about this.
Options for recipient identification parameters: phone — accepts both {{phone}} and {{bsuid}}; chatID — accepts both {{}} and {{bsuid\@lid}}; bsuid — accepts {{bsuid}}.
*** ### New Fields in Webhooks We store the BSUID ↔ phone mapping on our side, but you can also receive and store it in your integration. As a reminder, BSUID is unique within your specific business portfolio. #### Incoming Messages Additional fields are already available in all incoming webhooks: | Field | Description | | ---------------- | ------------------------------------------------------------ | | `authorBsuid` | BSUID of the incoming message sender (`RU.1504711984690866`) | | `authorUserName` | WhatsApp user username (not yet introduced by Meta) | *** #### Send, Delivery, and Read Webhooks In ack webhooks for: * message sending; * delivery; * read receipts; the following are now also passed: | Field | Description | | ---------- | -------------------------------------------- | | `bsuid` | Client BSUID | | `phone` | Client phone number (if available) | | `username` | Client username (not yet introduced by Meta) | {% embed url="" %} *** ### ChatID Logic Changes Since Meta is gradually moving to a new model where a user can: * hide their phone number using a username; * interact with a business through the internal BSUID identifier; * phone number is no longer the primary identifier The chatId field will support storing two formats. ``` chatId: 796700000001@c.us or chatId: RU.1504711984690866@lid ``` {% hint style="warning" %} Make sure your integration correctly handles the new format and length of the chatId field: RU.1504711984690866\@lid {% endhint %} **BSUID format** Must start with the user’s two-letter country code according to the ISO 3166 alpha-2 standard, followed by a dot and up to 128 alphanumeric characters (for example: US.13491208655302741918). #### Current Logic For existing clients, ChatID will continue to be stored in the previous format: ``` {{phone@c.us}} ``` For example: ``` 796700000001@c.us ``` *** #### New Users Without a Phone Number If a client messages you for the first time after Meta's new model is rolled out (and there is no BSUID ↔ phone mapping) and the client's phone number is hidden, ChatID will be stored in the format: ``` {{bsuid@lid}} ``` For example: ``` RU.1504711984690866@lid ``` If the user later reveals their phone number or shares it manually, ChatID will still remain: ``` {{bsuid@lid}} ``` This is intentional so that the conversation identifier does not change. #### Why ChatID Does Not Change Back to Phone BSUID is a permanent user identifier within WhatsApp's new architecture. Even if the phone number becomes available later, changing ChatID could: * result in two different chats; * break message associations; * cause issues in CRM and integrations. Therefore, after a chat is created via BSUID, its identifier remains unchanged. *** ### Future Transition to BSUID Since Meta is gradually moving toward BSUID as the primary identifier, all chats in the future will use the format: ``` {{bsuid@lid}} ``` Exact timelines for the full transition have not been announced yet. *** ### Important To ensure backward compatibility between phone ↔ BSUID works correctly, it is very important not to disable contact storage and synchronization in WhatsApp Business. If contact collection is disabled in Meta Business Manager: * WhatsApp will stop storing the phone ↔ BSUID mapping; * new users with hidden phone numbers may become unavailable for messaging by phone number; * some previously accumulated phone ↔ BSUID mappings may be lost; * this may affect your ability to continue conversations with existing customers after Meta fully transitions to the new identification model. ### FAQ
If my client registers a username, will I still be able to message them? Yes, if you already have their phone number from a previous conversation, you can continue sending them messages regardless of whether they registered or changed their username. In the "Contact Book", this link is saved automatically thanks to matching the phone number with BSUID based on all previous interactions.
What is BSUID and why does my system need it? BSUID is a unique identifier that WhatsApp assigns to each user within your business portfolio. When a user changes their username and stops sharing their phone number, your system receives BSUID instead. Without this identifier, you will not be able to identify such users and reply to them.
We use ads with a link to WhatsApp. What does this mean for us? To communicate with users who have switched to using a username, your system will need to handle BSUID instead of a phone number. This will become relevant starting in June 2026, when the transition to usernames begins.
What is the realistic timeline? The practical answer: until username usage becomes widespread in your markets. Testing at the country level will begin in June 2026, after which rollout will happen gradually. The period from April to June is specifically allocated for a smooth rollout.
We work with multiple clients across different portfolios. Will the same client have a different identifier in each one? Yes. BSUID identifiers are tied to a business portfolio, so the same client will appear with different BSUID identifiers in each portfolio.
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.1msg.io/docs/api-1msg/bsuid-new-whatsapp-user-identifier-and-changes-in-1msg.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.