What happens when a contact changes their WhatsApp number

When a customer moves their WhatsApp account to a new number, Omnifox updates the contact and keeps the whole conversation automatically.

Jun 25, 2026

What it is

When one of your customers moves their WhatsApp account to a different phone number, Meta notifies Omnifox with a system event. Omnifox automatically migrates the contact's identity to the new number and keeps the entire conversation: no duplicate contact is created and no history is lost.

This article explains what you'll see in the Inbox and what to do (usually nothing).

When it applies

  • The customer keeps their WhatsApp account but ties it to another number (new SIM, portability, etc.).
  • Your workspace's WhatsApp channel is connected through Meta's API (Cloud API or Coexistence).

What Omnifox does automatically

  1. Detects the event. Meta sends a user_changed_number event carrying the old and new numbers.
  2. Reassigns the identity. The contact's WhatsApp identifier (wa_id) is updated to the new number.
  3. Merges duplicates. If a separate contact already existed for the new number, Omnifox merges them: it re-links conversations, identities, and custom fields, and writes a merge record.
  4. Keeps the conversation. The open conversation stays the same, with every previous message intact.
  5. Drops a system message inside the chat, e.g. "📱 Customer changed their WhatsApp number from +1… to +1…", so the agent has a clear audit trail.

How to verify it

  1. Open the customer's conversation in Inbox.
  2. Look for the system message with the 📱 icon showing the old and new numbers.
  3. Open the contact panel (on the right) and confirm the phone number is already the new one.
  4. Check that the earlier history is still visible in the same thread.

If it doesn't work

  • I don't see the system message: Meta only sends the event when the customer migrated the same account to a new number. If they created a brand-new account, it arrives as a new contact (no history), because to Meta it's a different person.
  • Two separate contacts appear: this happens when the old number wasn't resolvable at the moment of the event. You can join them manually from the contact using merge contacts.
  • Old history not migrated (Coexistence channels): an admin can reconcile past changes with the whatsapp:fix-changed-numbers command, which applies the same migration logic to historical events.

Tips

  • Don't hand-edit the contact's number when the notice arrives: Omnifox already updated it. Editing in parallel can create inconsistencies.
  • A merge is permanent. Before manually merging two contacts, make sure they really are the same person.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp