WorkOS by Befocusy WorkOS Help center

Linking a WhatsApp conversation to a CRM contact

In a WhatsApp Business conversation, next to the rest of the message actions, there's an icon for linking it to a CRM contact. The same icon also exists in Instagram and LinkedIn if you have them connected, but the rest of this article focuses on WhatsApp — it's the only network whose phone number has its own field on the contact record.

The icon's two states

  • Not linked: two grey silhouettes, with the hint Link to a CRM contact.
  • Already linked: a person with a checkmark, in green, with the hint Linked to {name} — click to view.

Clicking the icon when the conversation is ALREADY linked doesn't ask for another contact again: it takes you straight to their record.

Linking a new conversation

Clicking the icon of an unlinked conversation opens a CRM contact search, with the sender's name already filled in. You can:

  • Search for and pick an existing contact.
  • Click Create new contact, which creates one with that same name.

Once confirmed, WorkOS does two things at once:

  1. Saves this conversation's number in the contact record's WhatsApp phone field.
  2. Links every message in the conversation that didn't already have a contact to this one.

From then on, the next messages from that same number are recognized automatically — no need to link anything again.

"WhatsApp phone" and "Contact phone"

A contact record has two separate phone fields, next to each other:

  • WhatsApp phone: the number WorkOS uses to automatically recognize their WhatsApp messages. It's the one that fills in on its own when you link a conversation from the icon, and you can also type or correct it by hand at any time.
  • Contact phone: a generic phone number, for reference only. It isn't used to recognize any message — change it whenever you like without affecting WhatsApp.

If you manually correct a contact's WhatsApp phone (for example, because they changed number), the next messages from that new number will be recognized by it; already-linked older messages don't move.

If the conversation's number couldn't be determined when linking, the contact still gets linked to the thread, but the WhatsApp phone field is left empty — you can type it in yourself afterwards.