Skip to content

Commit be5cfe9

Browse files
JillGrant615JillGrant615
authored
Merge pull request #314137 from glorialimicrosoft/gelli/addDocsForBSUID
Add Docs for WhatsApp Username and BSUID
2 parents 2805c5c + e20395d commit be5cfe9

10 files changed

Lines changed: 308 additions & 26 deletions

File tree

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@ The key features of Azure Communications Services Advanced Messaging for WhatsAp
2929
* Reply to user’s inquiries and trigger automation using Azure Event Grid notifications.
3030
* Receive delivery reports for messages sent, delivered, and read.
3131

32+
## WhatsApp usernames and business-scoped user IDs
33+
34+
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 will be supported as recipient identifiers in send requests starting in June 2026.
35+
36+
> [!WARNING]
37+
> **Breaking change:** 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-username-support-overview.md).
38+
3239
## Next steps
3340

3441
To get started with Advanced Messaging for WhatsApp, see:

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

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
title: WhatsApp usernames and business-scoped user IDs (BSUID)
3+
titleSuffix: An Azure Communication Services concept document
4+
description: Learn about WhatsApp usernames and business-scoped user IDs (BSUIDs) and how they affect messaging in Azure Communication Services.
5+
author: gelli
6+
services: azure-communication-services
7+
ms.author: gelli
8+
ms.date: 04/01/2026
9+
ms.topic: conceptual
10+
ms.service: azure-communication-services
11+
ms.subservice: advanced-messaging
12+
---
13+
14+
# WhatsApp usernames and business-scoped user IDs (BSUID)
15+
16+
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.
17+
18+
This article explains what BSUIDs are, how they affect Azure Communication Services Advanced Messaging, and how to prepare your integration.
19+
20+
## What is a BSUID?
21+
22+
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:
23+
24+
- **Automatically generated** by Meta for each user-portfolio pair.
25+
- **Prefixed with a country code**: The format is `{ISO 3166 alpha-2 country code}.{up to 128 alphanumeric characters}`, for example, `US.13491208655302741918`.
26+
- **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.
27+
- **Stable across username changes**: If a user changes their username, their BSUID remains the same.
28+
- **Regenerated on phone number change**: If a user changes their phone number, a new BSUID is generated.
29+
30+
> [!IMPORTANT]
31+
> 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.
32+
33+
## Impact on outbound messages
34+
35+
> [!NOTE]
36+
> Sending messages to BSUIDs will be available starting in June 2026, when Meta rolls out the WhatsApp username feature to end users. Until then, the `to` field only supports phone numbers.
37+
38+
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.
39+
40+
**Send to a phone number (existing behavior):**
41+
42+
```json
43+
{
44+
"channelRegistrationId": "<channel-registration-id>",
45+
"to": ["+14255550199"],
46+
"kind": "text",
47+
"content": "Hello!"
48+
}
49+
```
50+
51+
**Send to a BSUID:**
52+
53+
```json
54+
{
55+
"channelRegistrationId": "<channel-registration-id>",
56+
"to": ["US.13491208655302741918"],
57+
"kind": "text",
58+
"content": "Hello!"
59+
}
60+
```
61+
62+
## Impact on inbound messages
63+
64+
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.
65+
66+
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.
67+
68+
**Phone number available:**
69+
70+
```json
71+
"data": {
72+
"from": "14255551234",
73+
"fromBSUID": "US.13491208655302741918",
74+
"to": "{channel-id}",
75+
"content": "Hi there!",
76+
"channelType": "whatsapp",
77+
"messageType": "text"
78+
}
79+
```
80+
81+
**Phone number hidden (username adopted):**
82+
83+
```json
84+
"data": {
85+
"from": "",
86+
"fromBSUID": "US.13491208655302741918",
87+
"to": "{channel-id}",
88+
"content": "Hi there!",
89+
"channelType": "whatsapp",
90+
"messageType": "text"
91+
}
92+
```
93+
94+
> [!CAUTION]
95+
> The `from` field may now be empty or null. Do not assume this field always contains a phone number.
96+
97+
## Impact on event subjects
98+
99+
The `subject` field in Event Grid events for `AdvancedMessageReceived` uses the format `advancedMessage/sender/{sender@id}/recipient/{channel-id}`. When a WhatsApp user hides their phone number, the `{sender@id}` portion of the subject now contains the sender's BSUID instead of their phone number.
100+
101+
> [!WARNING]
102+
> **Breaking change:** If you have Event Grid subscriptions with subject filters based on the sender's phone number, those filters won't match events from users who have adopted a WhatsApp username and hidden their phone number. Update your subject filters and any webhook automation code that parses the event subject to account for BSUID values.
103+
104+
**Subject with phone number:**
105+
106+
```
107+
advancedMessage/sender/14255551234/recipient/11111111-1111-1111-1111-111111111111
108+
```
109+
110+
**Subject with BSUID (phone number hidden):**
111+
112+
```
113+
advancedMessage/sender/US.13491208655302741918/recipient/11111111-1111-1111-1111-111111111111
114+
```
115+
116+
## Impact on delivery status events
117+
118+
The [AdvancedMessageDeliveryStatusUpdated](../../../../event-grid/communication-services-advanced-messaging-events.md#microsoftcommunicationadvancedmessagedeliverystatusupdated-event) event now includes a new `toBSUID` field containing the recipient's BSUID.
119+
120+
If the message was sent to a BSUID, the existing `to` field may be empty.
121+
122+
**Sent to a phone number:**
123+
124+
```json
125+
"data": {
126+
"from": "{channel-id}",
127+
"to": "14255550199",
128+
"toBSUID": "US.13491208655302741918",
129+
"status": "Delivered",
130+
"channelType": "whatsapp",
131+
"messageId": "22222222-2222-2222-2222-222222222222"
132+
}
133+
```
134+
135+
**Sent to a BSUID:**
136+
137+
```json
138+
"data": {
139+
"from": "{channel-id}",
140+
"to": "",
141+
"toBSUID": "US.13491208655302741918",
142+
"status": "Delivered",
143+
"channelType": "whatsapp",
144+
"messageId": "22222222-2222-2222-2222-222222222222"
145+
}
146+
```
147+
148+
## Phone number availability rules
149+
150+
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:
151+
152+
- You messaged or called the user's phone number **within the last 30 days**.
153+
- You received a message or call from the user's phone number **within the last 30 days**.
154+
- The user is in your **Contact Book**.
155+
156+
> [!NOTE]
157+
> 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.
158+
159+
### Contact Book
160+
161+
Meta provides a Contact Book feature that automatically stores WhatsApp user contact information (phone number and BSUID mappings) from interactions. Key details:
162+
163+
- The Contact Book is provided and hosted by Meta. It is by default enabled. No integration work is required.
164+
- It's scoped to the business portfolio level.
165+
- Only interactions that occur **after** the Contact Book launches are captured. Prior interactions aren't retroactively stored.
166+
167+
168+
## Limitations
169+
170+
- **Authentication templates**: One-tap, zero-tap, and copy code authentication templates still require phone numbers. BSUIDs can't be used for these template types.
171+
- **Portfolio scoping**: BSUIDs are scoped to individual business portfolios and can't be used across different portfolios.
172+
- **Contact Book**: Only captures interactions after launch. No retroactive data.
173+
174+
## How to prepare
175+
176+
> [!WARNING]
177+
> **Breaking change:** The `from` and `to` fields in Advanced Messaging events may now be empty or null. Any code that assumes these fields always contain a phone number will break. You must update your event handlers to use the new `fromBSUID` and `toBSUID` fields.
178+
179+
To prepare your integration for WhatsApp usernames and BSUIDs:
180+
181+
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.
182+
183+
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.
184+
185+
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. Sending to BSUIDs will be available starting in June 2026.
186+
187+
4. **Review Event Grid subject filters.** If you have webhook subscriptions that filter on the event `subject` (for example, filtering by a specific sender phone number), update those filters to also handle BSUID values. The sender portion of the subject may now contain a BSUID instead of a phone number.
188+
189+
## Key timeline
190+
191+
| Date | Milestone |
192+
|------|-----------|
193+
| March 31, 2026 | BSUIDs begin appearing in production webhook payloads |
194+
| Early April 2026 | Contact Book feature launches |
195+
| June 2026 | Sending messages to BSUIDs available in production; WhatsApp begins rolling out usernames to end users |
196+
197+
## Related content
198+
199+
- [Advanced Messaging for WhatsApp overview](whatsapp-overview.md)
200+
- [Handle Advanced Messaging events](../../../quickstarts/advanced-messaging/whatsapp/handle-advanced-messaging-events.md)
201+
- [Advanced Messaging event schemas](../../../../event-grid/communication-services-advanced-messaging-events.md)
202+
- [Send WhatsApp template messages](template-messages.md)
203+
- [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‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,11 @@ The Event Grid Viewer is a sample site that allows you to view incoming events f
4747

4848
3. Then select **Review + Create**.
4949

50-
4. After the deployment completes, select on the App Service resource to open it.
50+
4. After the deployment completes, select the App Service resource to open it.
5151

5252
:::image type="content" source="./media/handle-advanced-messaging-events/event-viewer-web-app.png" lightbox="./media/handle-advanced-messaging-events/event-viewer-web-app.png" alt-text="Screenshot that shows Events Viewer web app.":::
5353

54-
5. On the resource overview page, select on the copy button next to the **Default Domain** property.
54+
5. On the resource overview page, select the copy button next to the **Default Domain** property.
5555

5656
:::image type="content" source="./media/handle-advanced-messaging-events/default-domain.png" lightbox="./media/handle-advanced-messaging-events/default-domain.png" alt-text="Screenshot that shows URL of Events Viewer web app.":::
5757

@@ -89,8 +89,19 @@ The Event Grid Viewer is a sample site that allows you to view incoming events f
8989

9090
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).
9191

92+
## WhatsApp usernames and BSUIDs
93+
94+
With the introduction of WhatsApp usernames, Advanced Messaging events now include new fields for business-scoped user IDs (BSUIDs).
95+
96+
- **`AdvancedMessageReceived`** events include a `fromBSUID` field with the sender's BSUID.
97+
- **`AdvancedMessageDeliveryStatusUpdated`** events include a `toBSUID` field with the recipient's BSUID.
98+
99+
> [!WARNING]
100+
> **Breaking change:** 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. Additionally, the event `subject` field may now contain a BSUID instead of a phone number, which can break existing webhook subject filters and automation code that parses the subject. For more information, see [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview.md).
101+
92102
## Next steps
93103

94104
- [Understand Advanced Communication Messages Events](../../../../event-grid/communication-services-advanced-messaging-events.md)
105+
- [WhatsApp usernames and BSUIDs](../../../concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview.md)
95106
- [Get started With Advanced Communication Messages SDK](./get-started.md)
96107

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

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -125,25 +125,37 @@ String channelRegistrationId = "<your channel registration id GUID>";
125125

126126
### Set recipient list
127127

128-
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.
128+
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.
129129
For this article, this phone number can be your personal phone number.
130130

131131
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.
132132

133133
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).
134134

135135
> [!NOTE]
136-
> Only one phone number is currently supported in the recipient list.
136+
> Only one phone number or BSUID is currently supported in the recipient list.
137137
138138
Create the recipient list like this:
139139
```java
140140
List<String> recipientList = new ArrayList<>();
141-
recipientList.add("<to WhatsApp phone number>");
141+
recipientList.add("<to WhatsApp phone number or BSUID>");
142142
```
143143

144-
Example:
144+
Example using a phone number:
145145
```java
146146
// Example only
147147
List<String> recipientList = new ArrayList<>();
148148
recipientList.add("+14255550199");
149149
```
150+
151+
Example using a BSUID:
152+
```java
153+
// Example only
154+
List<String> recipientList = new ArrayList<>();
155+
recipientList.add("US.13491208655302741918");
156+
```
157+
158+
> [!NOTE]
159+
> Sending messages to BSUIDs will be available starting in June 2026. Until then, use phone numbers as recipients.
160+
161+
For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../../concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview.md).

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

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -139,23 +139,34 @@ const channelRegistrationId = "<your channel registration id GUID>";
139139

140140
### Set recipient list
141141

142-
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.
142+
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.
143143
For this article, this phone number can be your personal phone number.
144144

145145
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.
146146

147147
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).
148148

149149
> [!NOTE]
150-
> Only one phone number is currently supported in the recipient list.
150+
> Only one phone number or BSUID is currently supported in the recipient list.
151151
152152
Create the recipient list like this:
153153
```json
154-
const recipientList = ["<to WhatsApp phone number>"];
154+
const recipientList = ["<to WhatsApp phone number or BSUID>"];
155155
```
156156

157-
Example:
157+
Example using a phone number:
158158
```javascript
159159
// Example only
160160
const recipientList = ["+14255550199"];
161-
```
161+
```
162+
163+
Example using a BSUID:
164+
```javascript
165+
// Example only
166+
const recipientList = ["US.13491208655302741918"];
167+
```
168+
169+
> [!NOTE]
170+
> Sending messages to BSUIDs will be available starting in June 2026. Until then, use phone numbers as recipients.
171+
172+
For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../../concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview.md).

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

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ var channelRegistrationId = new Guid("<your channel registration ID GUID>");
3232

3333
### Set recipient list
3434

35-
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.
35+
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.
3636

3737
For this example, you can use your personal phone number.
3838

@@ -41,19 +41,30 @@ The recipient phone number can't be the business phone number (Sender ID) associ
4141
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).
4242

4343
> [!NOTE]
44-
> Only one phone number is currently supported in the recipient list.
44+
> Only one phone number or BSUID is currently supported in the recipient list.
4545

4646
Create the recipient list like this:
4747
```csharp
48-
var recipientList = new List<string> { "<to WhatsApp phone number>" };
48+
var recipientList = new List<string> { "<to WhatsApp phone number or BSUID>" };
4949
```
5050

51-
Example:
51+
Example using a phone number:
5252
```csharp
5353
// Example only
5454
var recipientList = new List<string> { "+14255550199" };
5555
```
5656

57+
Example using a BSUID:
58+
```csharp
59+
// Example only
60+
var recipientList = new List<string> { "US.13491208655302741918" };
61+
```
62+
63+
> [!NOTE]
64+
> Sending messages to BSUIDs will be available starting in June 2026. Until then, use phone numbers as recipients.
65+
66+
For more information about BSUIDs, see [WhatsApp usernames and BSUIDs](../../../../concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview.md).
67+
5768
### Start sending messages between a business and a WhatsApp user
5869

5970
Conversations between a WhatsApp Business Account and a WhatsApp user can be initiated in one of two ways:

0 commit comments

Comments
 (0)