WhatsApp usernames and BSUID

How WhatsApp usernames change identity fields in message:appUser events.

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.

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

"client": {
  "externalId": "27824420729",
  "displayName": "[phone]",
  "raw": {
    "profile": { "name": "Jane Doe" },
    "from": "27824420729"
  }
}

After

"client": {
  "externalId": "ZA.2c7a9f3e8b...",
  "displayName": "Jane Doe",
  "additionalIdentifiers": {
    "phoneNumber": "[phone]"
  },
  "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.

Treat your own system as authoritative for the phone number.

Use Channel360 and WhatsApp identifiers for correlation.