Octopods links each incoming message to a contact in Intercom. This article explains how matching works for each channel, including WhatsApp contacts who arrive with a username and no phone number. Matching is designed to prevent duplicates when channels share an identifier, such as a phone number. For an overview, visit Contact matching for Intercom.
Users and Leads
Intercom stores two kinds of contacts:
User — a contact you have explicitly identified, usually because they signed in or were synced from your own system. Users typically carry full profile data.
Lead — an unidentified or anonymous visitor. Leads can be promoted to Users later, usually through a merge.
Whenever Octopods creates a brand-new contact for an incoming message, it is created as a Lead. You or your team can later merge that Lead into an existing User when you recognise the person. See Merging Contacts in Intercom for how that works.
How Octopods finds the right contact
When a customer messages one of your connected channels, Octopods follows a two-step lookup:
Channel identifier lookup. If Octopods has already seen this customer on this channel before, it jumps straight to the Intercom contact that message was linked to last time. No further searching happens.
Phone number or handle lookup. If this is a first-time message from this customer on this channel, Octopods searches your Intercom workspace for a contact that matches the sender’s identifier (phone number for phone-based channels, or a channel-specific user ID for social channels).
If neither step finds a match, Octopods creates a new Lead in Intercom using the information the channel provided — typically the customer’s name and phone number or handle — and links the incoming message to that Lead.
Channels that match by Custom Data Attribute (CDA)
For social and chat-app channels, the customer’s phone number is not available on their first message. Instead, Octopods stores a Custom Data Attribute (CDA) on the Intercom contact that records the channel and the customer’s ID on that channel. On the next message from the same person, Octopods finds them by that CDA.
The channels that use CDA matching are:
Telegram
Instagram
Facebook Messenger
LINE
WeChat
TikTok (matched by the TikTok user ID)
Viber bots (older Intercom accounts only; Viber bots are no longer offered)
When a customer sends their first message on any of these channels, Octopods either finds an existing contact that already has the matching CDA stored or creates a new Lead and writes the CDA on it.
Telegram Personal matches by phone number if the person shares it. Otherwise it matches by their Telegram user ID.
Channels that match by phone number
Phone-based channels use the customer’s phone number to find or create the Intercom contact. WhatsApp Cloud API, SMS, Viber Business Messages and other phone-based channels fall into this group. In particular, WhatsApp Cloud API matches by phone number. A WhatsApp contact with only a username is matched by the WhatsApp user ID, and the phone is added to the same contact if they share it later. For more on these contacts, see the next section.
Octopods normalises phone numbers to international (E.164) format before searching, so a contact saved as +14155550100, 14155550100, or (415) 555-0100 can all be matched to the same Intercom record. The search looks across Intercom’s standard phone field.
If more than one Intercom contact shares the same phone number, Octopods uses your contact prioritization setting to pick one. See Contact Prioritization Settings for how to configure that.
WhatsApp contacts with a username and no phone number
WhatsApp lets people use a username instead of sharing their phone number. When someone like this messages you, for example from a click-to-WhatsApp ad, Meta sends a Business-Scoped User ID (BSUID) instead of a phone number.
Where to find the BSUID. Octopods saves the BSUID in the Intercom contact attribute octopods_whatsapp_user_id, and the WhatsApp username in octopods_whatsapp_user_name.
Replying. You reply as usual from the Intercom conversation. Replies go back to the customer on WhatsApp. The normal 24-hour customer service window applies: after 24 hours with no message from the customer, you need an approved template to write again.
Sending templates later. You can send a template to a username-only contact from the Intercom Inbox App, as long as Octopods has a WhatsApp user ID (BSUID) linked to the contact. If it doesn’t, the Inbox App shows “User phone number or WhatsApp user id must exist.” The WhatsApp template and interactive API endpoints accept destination_user_id (the BSUID) instead of destination_phone. See Send WhatsApp Template Message.
How matching works. Octopods matches later messages from the same person by the BSUID, never by the username.
Keeping one contact per person. A username-only contact arrives as a new Lead, because there’s no phone number to match. If the customer shares their phone number later, Octopods adds it to the same contact. You can also merge the Lead into an existing contact when you recognize the person. After a merge, later messages can create a new Lead again unless matching by contact attributes is switched on for your account (see “Keeping contact data in sync” below). See Merging Contacts in Intercom.
Keeping contact data in sync
Octopods updates the CDA fields whenever it creates or finds a contact, so the mapping stays accurate even if the same customer reaches out on multiple channels. If an Intercom admin merges a Telegram Lead into a User, later messages can create a new Lead again. This doesn’t happen when matching by contact attributes is switched on for your account (available on request) and the merged User keeps the Telegram ID attribute. WhatsApp Leads with only a username work the same way.
What’s next
