> For the complete documentation index, see [llms.txt](https://docs.channel360.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.channel360.co.za/api-usage/using-the-channel360-v1.1-api/conversations/whatsapp-usernames-and-bsuid.md).

# WhatsApp usernames and BSUID

{% hint style="warning" %}
**Draft**

This guidance is not a final contract yet.

Our code change is not shipped yet. The exact `additionalIdentifiers` shape and rollout timing are still being confirmed with the provider.

Publish this only after validating against a real post-migration payload.
{% endhint %}

### Overview

WhatsApp is decoupling a user's identity from their phone number through usernames.

As this rolls out, identity fields in the `message:appUser` webhook change shape.

If your integration reads a phone number from the webhook, update it.

### What changes

The `client` object in the webhook payload is affected.

Fields that previously carried a phone number now carry an opaque **Business-Scoped User ID (BSUID)**.

A BSUID is a string prefixed with a two-letter country code, such as `ZA.2c7a9f3e8b...`.

A BSUID is not a phone number.

When the user still shares their number, it moves to `additionalIdentifiers.phoneNumber`.

**Before**

```json
"client": {
  "externalId": "27824420729",
  "displayName": "+27 82 442 0729",
  "raw": {
    "profile": { "name": "Jane Doe" },
    "from": "27824420729"
  }
}
```

**After**

```json
"client": {
  "externalId": "ZA.2c7a9f3e8b...",
  "displayName": "Jane Doe",
  "additionalIdentifiers": {
    "phoneNumber": "+27824420729"
  },
  "raw": {
    "profile": { "name": "Jane Doe" },
    "from": "ZA.2c7a9f3e8b..."
  }
}
```

`additionalIdentifiers.phoneNumber` may be absent.

Users who adopt a WhatsApp username can message you without sharing a number at all.

The rest of the payload stays the same, including `trigger`, `appUser`, `conversation`, and `messages`.

### What you must do

1. **Stop reading `externalId` and `raw.from` as a phone number.** These values are forwarded from the provider and now become BSUIDs. We do not rewrite them.
2. **Read the phone number from `additionalIdentifiers.phoneNumber`.** Handle it being missing. Never store a BSUID in a phone-number field.
3. **Do not assume a cutover date.** Existing contacts are not back-filled, so both formats coexist for some time. Detect the value format instead.
4. **Correlate on Channel360 IDs, not the phone number.** Match inbound replies on `conversation._id` and `appUser._id`. Keep your own phone-number record keyed to those IDs.

### How to detect the format

Use simple format checks during the transition.

* **BSUID:** country code, then `.`, then opaque characters.
* **Phone number:** digits, optionally prefixed with `+`.

### Recommended approach

This follows the same principle as [Recommended source of truth](/api-usage/using-the-channel360-v1.1-api/conversations.md).

Treat your own system as authoritative for the phone number.

Use Channel360 and WhatsApp identifiers for correlation.