Migrating from `contactPhone` to Contact Identity

WhatsApp is moving toward usernames and business-scoped user IDs. A customer may no longer be represented by a phone number in every webhook. Existing integrations should keep reading contactPhone, but should stop using it as the primary key.

What Changes

Legacy fields remain in v1:

{
  "contactPhone": "5491155551234",
  "contactName": "John Doe"
}

New fields are added next to them:

{
  "contactId": "550e8400-e29b-41d4-a716-446655440020",
  "contactIdentifier": "AR.ABC123",
  "contactIdentifierType": "bsuid",
  "contactReplyTo": "AR.ABC123",
  "contactPhone": null,
  "businessScopedUserId": "AR.ABC123",
  "parentBusinessScopedUserId": null,
  "username": "customer.name"
}

Use contactIdentifier as the stable key in your system. Use contactReplyTo as the to value when replying through POST /v1/phones/{phoneId}/messages.

Migration Steps

Add a nullable contactIdentifier column to your local customer/session table.
Backfill it from the old phone field for existing rows.
Start reading contactIdentifier and contactReplyTo from message.received webhooks.
Change replies to send to contactReplyTo instead of contactPhone.
Treat contactPhone as optional display data.
Monitor events where contactIdentifierType is not phone.

Checklist

Do not key sessions only by phone number.
Do not validate outbound to as digits-only.
Accept contactPhone: null.
Store the full BSUID string without truncation.
Keep contactPhone in UI when present, but fall back to username or contactIdentifier.
Update integration tests with at least one BSUID-only webhook fixture.

Deprecation Timeline

Release 1 adds the new fields without breaking existing payloads. After clients have migrated, the legacy contactPhone/phoneNumber fields can be marked deprecated. Removal requires v2 or an explicit deprecation window.

Recommended minimum window: 90 days from publication of this guide.

References

Meta Business-Scoped User IDs: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
Twilio WhatsApp key concepts: https://www.twilio.com/docs/whatsapp/key-concepts
Microsoft ACS WhatsApp username overview: https://learn.microsoft.com/en-us/azure/communication-services/concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview

# Migrating from `contactPhone` to Contact Identity

WhatsApp is moving toward usernames and business-scoped user IDs. A customer may no longer be
represented by a phone number in every webhook. Existing integrations should keep reading
`contactPhone`, but should stop using it as the primary key.

## What Changes

Legacy fields remain in v1:

```json
{
  "contactPhone": "5491155551234",
  "contactName": "John Doe"
}
```

New fields are added next to them:

```json
{
  "contactId": "550e8400-e29b-41d4-a716-446655440020",
  "contactIdentifier": "AR.ABC123",
  "contactIdentifierType": "bsuid",
  "contactReplyTo": "AR.ABC123",
  "contactPhone": null,
  "businessScopedUserId": "AR.ABC123",
  "parentBusinessScopedUserId": null,
  "username": "customer.name"
}
```

Use `contactIdentifier` as the stable key in your system. Use `contactReplyTo` as the `to` value
when replying through `POST /v1/phones/{phoneId}/messages`.

## Migration Steps

1. Add a nullable `contactIdentifier` column to your local customer/session table.
2. Backfill it from the old phone field for existing rows.
3. Start reading `contactIdentifier` and `contactReplyTo` from `message.received` webhooks.
4. Change replies to send to `contactReplyTo` instead of `contactPhone`.
5. Treat `contactPhone` as optional display data.
6. Monitor events where `contactIdentifierType` is not `phone`.

## Checklist

- Do not key sessions only by phone number.
- Do not validate outbound `to` as digits-only.
- Accept `contactPhone: null`.
- Store the full BSUID string without truncation.
- Keep `contactPhone` in UI when present, but fall back to username or `contactIdentifier`.
- Update integration tests with at least one BSUID-only webhook fixture.

## Deprecation Timeline

Release 1 adds the new fields without breaking existing payloads. After clients have migrated, the
legacy `contactPhone`/`phoneNumber` fields can be marked deprecated. Removal requires v2 or an
explicit deprecation window.

Recommended minimum window: 90 days from publication of this guide.

## References

- Meta Business-Scoped User IDs: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
- Twilio WhatsApp key concepts: https://www.twilio.com/docs/whatsapp/key-concepts
- Microsoft ACS WhatsApp username overview: https://learn.microsoft.com/en-us/azure/communication-services/concepts/advanced-messaging/whatsapp/whatsapp-username-support-overview