Contact Matching
How Conduits matches Telegram users to HubSpot contacts.
How Matching Works
When Conduits encounters a Telegram contact for the first time, it searches your HubSpot portal using multiple identity signals, in priority order:
1. Phone Number Match (95% confidence)
If the Telegram user has a phone number visible to you, Conduits normalizes it to E.164 format and searches HubSpot's phone and mobilephone fields. This is the most reliable match.
2. Telegram Username Match (90% confidence)
If you've previously set the telegram_username custom property on a HubSpot contact, Conduits matches by username. Useful for contacts whose phone numbers aren't in HubSpot.
3. Telegram User ID Match (100% confidence)
If a contact was previously linked (either auto-matched or manually confirmed), their telegram_user_id property provides a definitive match.
4. Name Match (50-70% confidence)
As a fallback, Conduits fuzzy-matches first and last names. Because names aren't unique, these matches always require manual confirmation before Conduits will sync notes.
5. No Match
If no match is found, the conversation appears in the Contacts page as "Unmatched."
The Contacts Page
Go to Contacts in the sidebar to see all Telegram contacts organized by match status:
- Confirmed — You verified the match. Syncing is active.
- Phone / Username — High-confidence auto-match. Syncing is active.
- Name — Name-based match. Needs your confirmation before syncing.
- Unmatched — No match found. Use the search or create a new contact.
- Ignored — You chose not to sync this contact.
Searching for Matches
Click Match on any unmatched contact to open a search dropdown. Conduits searches HubSpot by the contact's name, splitting on separators and searching first/last names independently. You can also type a completely different name to search for.
Creating New Contacts
If a Telegram contact doesn't exist in HubSpot at all, click + Create new contact in the match dropdown. Conduits pre-fills the first name, last name, phone, and Telegram username. The new contact is created in HubSpot and linked automatically.
Match Caching
Match results are cached to avoid excessive HubSpot API calls. Successful matches are cached for 24 hours. Failed matches (no result found) are cached for 1 hour, so new contacts added to HubSpot are detected relatively quickly.