How Octopods finds the right contact
Every inbound message carries an identifier from the channel it came from. Octopods uses that identifier to look up an existing HubSpot contact before creating or updating a conversation.
The identifier depends on the channel:
Phone-based channels (SMS, WhatsApp): the sender’s phone number, normalized to international E.164 format.
Social and chat channels (Instagram, Messenger, Telegram, Slack): a channel-specific identifier — either the sender’s username on that channel or an opaque user ID issued by the platform.
Matching a sender to a HubSpot contact
For phone-based channels, Octopods searches your HubSpot contacts for a match against the standard HubSpot Phone number (phone) and Mobile phone number (mobilephone) fields. If either field matches the incoming phone number, Octopods uses that contact.
For social and chat channels, you control the match behavior from the channel’s Create HubSpot Contact for Channel Users settings:
Pick a Channel identifier — Username or User ID from the sending platform.
Pick a HubSpot contact property that stores the identifier on your contacts.
Octopods then searches HubSpot using the selected property. If a contact already has that property populated with the incoming identifier, that contact is used.
What happens when no contact matches
If the search finds no matching contact, behavior depends on whether automatic contact creation is turned on for the channel:
Enabled: Octopods creates a new HubSpot contact, stores the channel identifier on the property you chose, and starts the conversation against the new record.
Disabled: The message still lands in the selected HubSpot inbox, but no new contact is created. The conversation is not tied to a CRM record.
Note: Automatic contact creation is available for Telegram, Instagram, and Messenger channels. WhatsApp and Twilio SMS contacts are always resolved by phone number.
Contact properties Octopods reads and writes
Octopods uses a small, predictable set of standard HubSpot properties:
First name (
firstname)Last name (
lastname)Phone number (
phone)Mobile phone number (
mobilephone)Email (
email)
For social and chat channels, it also writes the channel identifier to the HubSpot contact property you selected in the channel’s settings.
Tip: Picking a property that is unique and indexed in HubSpot (for example, a custom “Telegram User ID” field) keeps matches reliable and avoids collisions with contacts who share a common name.
What’s next