This document explains how the Zoho CRM integration matches phone numbers to Zoho CRM contacts and accounts when logging calls and SMS messages.
When a call or SMS event is received, the system automatically normalizes the phone number before searching Zoho CRM:
1. Removes country code prefix: If the number starts with `+`, the system removes the `+` and the country code (e.g., `+1`)
2. Removes leading "1": If the number starts with `1` (North American country code), it removes it
3. Uses 10-digit format: The final search uses a standard 10-digit phone number
Examples
Incoming Number | Formatted for Search |
`+12345678901` | `2345678901` |
`12345678901` | `2345678901` |
`2345678901` | `2345678901` |
`+15551234567` | `5551234567`
|
When logging calls or SMS messages, the integration follows this process:
The system searches for a Contact in Zoho CRM that has a phone number matching the formatted number (10-digit format).
Zoho CRM searches across all phone fields on the Contact record:
- Phone
- Mobile
- Other Phone
- Assistant Phone
- Home Phone
If a matching contact is found, the system automatically retrieves the related Account through the contact's `Account_Name` relationship field.
3. Log the Activity
The call or SMS is then logged with:
- Contact: Linked to the matching contact record
- Account: Linked to the related account (if the contact has one)
- Owner: Assigned to the appropriate Zoho CRM user
Important Notes
No Direct Account Phone Search
The integration does not search Accounts directly by phone number. Account matching only occurs when:
1. A contact is found first
2. That contact has a related account in the `Account_Name` field
Minimum Phone Number Length
Phone numbers must be at least 10 digits to trigger a contact search. Shorter numbers (like internal extensions) will not be matched to contacts.
No Match Scenario
If no contact is found with a matching phone number:
- The call or SMS is still logged in Zoho CRM
- It will be created without a linked Contact or Account
- The phone number will appear in the activity description
Troubleshooting
Check these common issues:
1. Phone format in Zoho CRM: Ensure the phone number in Zoho CRM is stored in a format compatible with the 10-digit search
- ✅ Good: `(234) 567-8901`, `234-567-8901`, `2345678901`
- ⚠️ May cause issues: Numbers with extensions, international formats not matching the normalization rules
2. Which phone field: Verify the phone number is stored in one of the standard Zoho CRM phone fields on the Contact record
3. Multiple contacts: If multiple contacts have the same phone number, Zoho CRM will return the first match