---
title: "WhatsApp contact identity changed event"
method: POST
path: "whatsapp.contact.identity_changed"
tags: ["Webhook Events"]
---

# WhatsApp contact identity changed event

`POST whatsapp.contact.identity_changed` (webhook)

Fired when a WhatsApp user changes phone number or Meta regenerates their
business-scoped user id (BSUID). Carries the previous and current identifiers
so you can re-key records stored against the old phone number or BSUID.
Delivery is at-least-once; dedupe on the event `id`.

## Payload

- WebhookPayloadWhatsAppContactIdentityChanged — Webhook payload for the `whatsapp.contact.identity_changed` event. Fired when Meta reports that a WhatsApp user is now known by a different identifier: a `system` message of type `user_changed_number`, `user_changed_user_id` or `user_identity_changed`, or a `user_id_update` webhook (BSUID regenerated). Zernio re-keys the inbox conversation and contact channel before firing.
  - `id` string, required — Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.
  - `event` 'whatsapp.contact.identity_changed', required
  - `account` object, required
    - `accountId` string, required
    - `profileId` string, required
    - `platform` 'whatsapp', required
    - `username` string, required
    - `displayName` string, nullable
  - `reason` 'user_changed_number' | 'user_changed_user_id' | 'user_identity_changed' | 'user_id_update', required — Which Meta signal reported the change. `user_changed_number`: new phone number. `user_changed_user_id` and `user_id_update`: new BSUID.
  - `previous` WhatsAppContactIdentity, required
    - `phoneNumber` string, nullable, required — The user's WhatsApp phone number (wa_id), null when Meta did not send it (a username adopter who hides it).
    - `businessScopedUserId` string, nullable, required — Meta business-scoped user id (BSUID), for example `US.13491208655302741918`.
    - `parentBusinessScopedUserId` string, nullable, required — Parent BSUID, shared across the businesses of one portfolio when Meta sends it.
    - `whatsappUsername` string, nullable, required — The user's WhatsApp username, when Meta sent one with the change. Null on `previous`.
  - `current` WhatsAppContactIdentity, required
    - `phoneNumber` string, nullable, required — The user's WhatsApp phone number (wa_id), null when Meta did not send it (a username adopter who hides it).
    - `businessScopedUserId` string, nullable, required — Meta business-scoped user id (BSUID), for example `US.13491208655302741918`.
    - `parentBusinessScopedUserId` string, nullable, required — Parent BSUID, shared across the businesses of one portfolio when Meta sends it.
    - `whatsappUsername` string, nullable, required — The user's WhatsApp username, when Meta sent one with the change. Null on `previous`.
  - `contactId` string, nullable, required — Zernio contact id matched on the new identity, null when none exists yet.
  - `conversationId` string, nullable, required — Zernio inbox conversation that was re-keyed, null when there was none.
  - `changedAt` string, date-time, required — When Meta reported the change.
  - `timestamp` string, date-time, required — UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.

## Acknowledgement `200`

Webhook received successfully

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/f92af0e169c1?raw)