add docs for BSUID

Author: glorialimicrosoft

articles/communication-services/concepts/advanced-messaging/whatsapp/template-messages.md

@@ -80,6 +80,10 @@ var sampleTemplate = new MessageTemplate(templateName, templateLanguage);
 For detailed examples and template supported scenarios by Advanced Messages SDK, see:
 - [WhatsApp Template Quickstart](../../../quickstarts/advanced-messaging/whatsapp/send-template-messages.md)
 
+## Authentication templates and BSUIDs
+
+Authentication templates that use one-tap, zero-tap, or copy code flows **require a phone number** as the recipient. You can't use a business-scoped user ID (BSUID) to send these authentication template types. All other template types support both phone numbers and BSUIDs. For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](./whatsapp-usernames-bsuid.md).
+
 ## Next steps
 
 -   [Get started with advanced communication messages SDK](../../../quickstarts/advanced-messaging/whatsapp/get-started.md)

articles/communication-services/concepts/advanced-messaging/whatsapp/whatsapp-overview.md

@@ -29,6 +29,13 @@ The key features of Azure Communications Services Advanced Messaging for WhatsAp
 * Reply to user’s inquiries and trigger automation using Azure Event Grid notifications.
 * Receive delivery reports for messages sent, delivered, and read.
 
+## WhatsApp usernames and business-scoped user IDs
+
+WhatsApp is launching usernames in 2026, allowing users to display a username instead of their phone number. To support this change, Meta introduces a new identifier called the **business-scoped user ID (BSUID)**. BSUIDs begin appearing in webhook payloads and can be used as recipient identifiers in send requests.
+
+> [!IMPORTANT]
+> The `from` and `to` fields in Advanced Messaging events may now be empty when a user hides their phone number. Update your event handlers to use the new `fromBSUID` and `toBSUID` fields. For more information, see [WhatsApp usernames and BSUIDs](./whatsapp-usernames-bsuid.md).
+
 ## Next steps
 
 To get started with Advanced Messaging for WhatsApp, see:

articles/communication-services/concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md

@@ -0,0 +1,179 @@
+---
+title: WhatsApp usernames and business-scoped user IDs (BSUID)
+titleSuffix: An Azure Communication Services concept document
+description: Learn about WhatsApp usernames and business-scoped user IDs (BSUIDs) and how they affect messaging in Azure Communication Services.
+author: gelli
+services: azure-communication-services
+ms.author: gelli
+ms.date: 04/01/2026
+ms.topic: conceptual
+ms.service: azure-communication-services
+ms.subservice: advanced-messaging
+---
+
+# WhatsApp usernames and business-scoped user IDs (BSUID)
+
+WhatsApp is launching usernames in 2026. Usernames are an optional feature that allows WhatsApp users to display a username instead of their phone number. To support this change, Meta introduces a new identifier called the **business-scoped user ID (BSUID)** that uniquely identifies a WhatsApp user within a specific business portfolio.
+
+This article explains what BSUIDs are, how they affect Azure Communication Services Advanced Messaging, and how to prepare your integration.
+
+[!INCLUDE [Survey Request](../../../includes/survey-request.md)]
+
+## What is a BSUID?
+
+A business-scoped user ID (BSUID) is a unique, opaque identifier that Meta assigns to a WhatsApp user within a specific business portfolio. BSUIDs are:
+
+- **Automatically generated** by Meta for each user-portfolio pair.
+- **Prefixed with a country code**: The format is `{ISO 3166 alpha-2 country code}.{up to 128 alphanumeric characters}`, for example, `US.13491208655302741918`.
+- **Unique per business portfolio**: A BSUID is scoped to an individual business portfolio. The same WhatsApp user has a different BSUID for each business portfolio they interact with.
+- **Stable across username changes**: If a user changes their username, their BSUID remains the same.
+- **Regenerated on phone number change**: If a user changes their phone number, a new BSUID is generated.
+
+> [!IMPORTANT]
+> When using BSUIDs in API requests, use the entire BSUID value including the country code and period. Omitting or modifying any part of the BSUID causes the request to fail.
+
+## Impact on outbound messages
+
+The existing `to` field in the Send Notification API now accepts either a phone number or a BSUID. The service automatically detects the format and routes accordingly. No new fields are needed.
+
+**Send to a phone number (existing behavior):**
+
+```json
+{
+  "channelRegistrationId": "<channel-registration-id>",
+  "to": ["+14255550199"],
+  "kind": "text",
+  "content": "Hello!"
+}
+```
+
+**Send to a BSUID:**
+
+```json
+{
+  "channelRegistrationId": "<channel-registration-id>",
+  "to": ["US.13491208655302741918"],
+  "kind": "text",
+  "content": "Hello!"
+}
+```
+
+## Impact on inbound messages
+
+When a WhatsApp user sends a message to your business, the [AdvancedMessageReceived](../../../../event-grid/communication-services-advanced-messaging-events.md#microsoftcommunicationadvancedmessagereceived-event) event now includes a new `fromBSUID` field containing the sender's BSUID.
+
+If the user has adopted a username and their phone number isn't available, the existing `from` field may be empty. Both fields coexist when the phone number is available.
+
+**Phone number available:**
+
+```json
+"data": {
+  "from": "14255551234",
+  "fromBSUID": "US.13491208655302741918",
+  "to": "{channel-id}",
+  "content": "Hi there!",
+  "channelType": "whatsapp",
+  "messageType": "text"
+}
+```
+
+**Phone number hidden (username adopted):**
+
+```json
+"data": {
+  "from": "",
+  "fromBSUID": "US.13491208655302741918",
+  "to": "{channel-id}",
+  "content": "Hi there!",
+  "channelType": "whatsapp",
+  "messageType": "text"
+}
+```
+
+> [!CAUTION]
+> The `from` field may now be empty or null. Do not assume this field always contains a phone number.
+
+## Impact on delivery status events
+
+The [AdvancedMessageDeliveryStatusUpdated](../../../../event-grid/communication-services-advanced-messaging-events.md#microsoftcommunicationadvancedmessagedeliverystatusupdated-event) event now includes a new `toBSUID` field containing the recipient's BSUID.
+
+If the message was sent to a BSUID, the existing `to` field may be empty.
+
+**Sent to a phone number:**
+
+```json
+"data": {
+  "from": "{channel-id}",
+  "to": "14255550199",
+  "toBSUID": "US.13491208655302741918",
+  "status": "Delivered",
+  "channelType": "whatsapp",
+  "messageId": "22222222-2222-2222-2222-222222222222"
+}
+```
+
+**Sent to a BSUID:**
+
+```json
+"data": {
+  "from": "{channel-id}",
+  "to": "",
+  "toBSUID": "US.13491208655302741918",
+  "status": "Delivered",
+  "channelType": "whatsapp",
+  "messageId": "22222222-2222-2222-2222-222222222222"
+}
+```
+
+## Phone number availability rules
+
+When a WhatsApp user adopts a username, their phone number may no longer appear in webhook payloads. However, the phone number is still included when any of the following conditions are met:
+
+- You messaged or called the user's phone number **within the last 30 days**.
+- You received a message or call from the user's phone number **within the last 30 days**.
+- The user is in your **Contact Book**.
+
+> [!NOTE]
+> The 30-day lookback is evaluated **per business phone number**, not per portfolio. If you message a user from one business phone number, webhooks from a different business phone number in your portfolio won't include the user's phone number unless that specific number also had recent interaction.
+
+### Contact Book
+
+Meta provides a Contact Book feature that automatically stores WhatsApp user contact information (phone number and BSUID mappings) from interactions. Key details:
+
+- The Contact Book is provided and hosted by Meta. It is by default enabled. No integration work is required.
+- It's scoped to the business portfolio level.
+- Only interactions that occur **after** the Contact Book launches are captured. Prior interactions aren't retroactively stored.
+
+
+## Limitations
+
+- **Authentication templates**: One-tap, zero-tap, and copy code [authentication templates](/azure/communication-services/concepts/advanced-messaging/whatsapp/template-messages) still require phone numbers. BSUIDs can't be used for these template types.
+- **Portfolio scoping**: BSUIDs are scoped to individual business portfolios and can't be used across different portfolios.
+- **Contact Book**: Only captures interactions after launch. No retroactive data.
+
+## How to prepare
+
+To prepare your integration for WhatsApp usernames and BSUIDs:
+
+1. **Stop assuming `from` and `to` always contain phone numbers.** Review any logic that parses, validates, or formats these fields as E.164 numbers. These fields may now be empty or null.
+
+2. **Process `fromBSUID` and `toBSUID` fields.** Update your event handlers to read the new BSUID fields in [AdvancedMessageReceived](../../../../event-grid/communication-services-advanced-messaging-events.md#microsoftcommunicationadvancedmessagereceived-event) and [AdvancedMessageDeliveryStatusUpdated](../../../../event-grid/communication-services-advanced-messaging-events.md#microsoftcommunicationadvancedmessagedeliverystatusupdated-event) events.
+
+3. **Update outbound messaging logic.** When replying to a username-only user, use the BSUID from the `fromBSUID` field as the `to` value in your send request.
+
+## Key timeline
+
+| Date | Milestone |
+|------|-----------|
+| March 31, 2026 | BSUIDs begin appearing in production webhook payloads |
+| Early April 2026 | Contact Book feature launches |
+| May 2026 | APIs support sending messages to BSUIDs |
+| June 2026 | WhatsApp begins rolling out usernames to end users |
+
+## Related content
+
+- [Advanced Messaging for WhatsApp overview](whatsapp-overview.md)
+- [Handle Advanced Messaging events](../../../quickstarts/advanced-messaging/whatsapp/handle-advanced-messaging-events.md)
+- [Advanced Messaging event schemas](../../../../event-grid/communication-services-advanced-messaging-events.md)
+- [Send WhatsApp template messages](template-messages.md)
+- [Meta: Business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)

articles/communication-services/quickstarts/advanced-messaging/whatsapp/handle-advanced-messaging-events.md

@@ -89,8 +89,19 @@ The Event Grid Viewer is a sample site that allows you to view incoming events f
 
 If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../../create-communication-resource.md#clean-up-resources).
 
+## WhatsApp usernames and BSUIDs
+
+With the introduction of WhatsApp usernames, Advanced Messaging events now include new fields for business-scoped user IDs (BSUIDs).
+
+- **`AdvancedMessageReceived`** events include a `fromBSUID` field with the sender's BSUID.
+- **`AdvancedMessageDeliveryStatusUpdated`** events include a `toBSUID` field with the recipient's BSUID.
+
+> [!IMPORTANT]
+> The existing `from` and `to` fields may now be empty or null when a WhatsApp user has adopted a username and hidden their phone number. Update your event handlers accordingly. For more information, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md).
+
 ## Next steps
 
 - [Understand Advanced Communication Messages Events](../../../../event-grid/communication-services-advanced-messaging-events.md)
+- [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md)
 - [Get started With Advanced Communication Messages SDK](./get-started.md)
 

articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/common-setting-java.md

@@ -125,25 +125,34 @@ String channelRegistrationId = "<your channel registration id GUID>";
 
 ### Set recipient list
 
-You need to supply a real phone number that has a WhatsApp account associated with it. This WhatsApp account receives the text and media messages sent in this article.
+You need to supply a real phone number that has a WhatsApp account associated with it, or a business-scoped user ID (BSUID). This WhatsApp account receives the text and media messages sent in this article.
 For this article, this phone number can be your personal phone number.   
 
 The recipient phone number can't be the business phone number (Sender ID) associated with the WhatsApp channel registration. The Sender ID appears as the sender of the text and media messages sent to the recipient.
 
 The phone number should include the country code. For more information on phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats).
 
 > [!NOTE]
-> Only one phone number is currently supported in the recipient list.
+> Only one phone number or BSUID is currently supported in the recipient list.
 
 Create the recipient list like this:
 ```java
 List<String> recipientList = new ArrayList<>();
-recipientList.add("<to WhatsApp phone number>");
+recipientList.add("<to WhatsApp phone number or BSUID>");
 ```
 
-Example:
+Example using a phone number:
 ```java
 // Example only
 List<String> recipientList = new ArrayList<>();
 recipientList.add("+14255550199");
 ```
+
+Example using a BSUID:
+```java
+// Example only
+List<String> recipientList = new ArrayList<>();
+recipientList.add("US.13491208655302741918");
+```
+
+For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md).

articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/common-setting-javascript.md

@@ -139,23 +139,31 @@ const channelRegistrationId = "<your channel registration id GUID>";
 
 ### Set recipient list
 
-You need to supply a real phone number that has a WhatsApp account associated with it. This WhatsApp account receives the template, text, and media messages sent in this article.
+You need to supply a real phone number that has a WhatsApp account associated with it, or a business-scoped user ID (BSUID). This WhatsApp account receives the template, text, and media messages sent in this article.
 For this article, this phone number can be your personal phone number.   
 
 The recipient phone number can't be the business phone number (Sender ID) associated with the WhatsApp channel registration. The Sender ID appears as the sender of the text and media messages sent to the recipient.
 
 The phone number should include the country code. For more information on phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats).
 
 > [!NOTE]
-> Only one phone number is currently supported in the recipient list.
+> Only one phone number or BSUID is currently supported in the recipient list.
 
 Create the recipient list like this:
 ```json
-const recipientList = ["<to WhatsApp phone number>"];
+const recipientList = ["<to WhatsApp phone number or BSUID>"];
 ```
 
-Example:
+Example using a phone number:
 ```javascript
 // Example only
 const recipientList = ["+14255550199"];
-```
+```
+
+Example using a BSUID:
+```javascript
+// Example only
+const recipientList = ["US.13491208655302741918"];
+```
+
+For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md).

articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/common-setting-net.md

@@ -32,7 +32,7 @@ var channelRegistrationId = new Guid("<your channel registration ID GUID>");
 
 ### Set recipient list
 
-You need to supply an active phone number associated with a WhatsApp account. This WhatsApp account receives the template, text, and media messages sent in this quickstart.
+You need to supply an active phone number associated with a WhatsApp account, or a business-scoped user ID (BSUID). This WhatsApp account receives the template, text, and media messages sent in this quickstart.
 
 For this example, you can use your personal phone number.   
 
@@ -41,19 +41,27 @@ The recipient phone number can't be the business phone number (Sender ID) associ
 The phone number must include the country code. For more information about phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats).
 
 > [!NOTE]
-> Only one phone number is currently supported in the recipient list.
+> Only one phone number or BSUID is currently supported in the recipient list.
 
 Create the recipient list like this:
 ```csharp
-var recipientList = new List<string> { "<to WhatsApp phone number>" };
+var recipientList = new List<string> { "<to WhatsApp phone number or BSUID>" };
 ```
 
-Example:
+Example using a phone number:
 ```csharp
 // Example only
 var recipientList = new List<string> { "+14255550199" };
 ```
 
+Example using a BSUID:
+```csharp
+// Example only
+var recipientList = new List<string> { "US.13491208655302741918" };
+```
+
+For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md).
+
 ### Start sending messages between a business and a WhatsApp user
 
 Conversations between a WhatsApp Business Account and a WhatsApp user can be initiated in one of two ways:

articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/common-setting-python.md

@@ -129,7 +129,7 @@ Assign it to a variable called channelRegistrationId.
 
 ### Set recipient list
 
-You need to supply an active phone number associated with a WhatsApp account. This WhatsApp account receives the template, text, and media messages sent in this article.
+You need to supply an active phone number associated with a WhatsApp account, or a business-scoped user ID (BSUID). This WhatsApp account receives the template, text, and media messages sent in this article.
 
 For this example, you can use your personal phone number.   
 
@@ -138,19 +138,27 @@ The recipient phone number can't be the business phone number (Sender ID) associ
 The phone number must include the country code. For more information about phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats).
 
 > [!NOTE]
-> Only one phone number is currently supported in the recipient list.
+> Only one phone number or BSUID is currently supported in the recipient list.
 
 Set the recipient list like this:
 ```python
     phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")
 ```
 
-Usage Example:
+Usage example with a phone number:
 ```python
     # Example only
     to=[self.phone_number],
 ```
 
+Usage example with a BSUID:
+```python
+    # Example only
+    to=["US.13491208655302741918"],
+```
+
+For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-usernames-bsuid.md).
+
 ### Start sending messages between a business and a WhatsApp user
 
 Conversations between a WhatsApp Business Account and a WhatsApp user can be initiated in one of two ways: