Zoho CRM Integration
The Zoho CRM integration lets agents create and update leads, contacts, and deals — directly from a conversation. Use it in sales or support flows to log inbound interest, update deal stages, or look up existing contacts.
Connect Zoho CRM
Zoho CRM connects with OAuth. You sign in to Zoho and approve access; you do not need to create a Zoho API client or copy tokens.
- Open your project and go to Tools → Add tool → From template.
- Find Zoho CRM and click Connect with Zoho CRM.
- Sign in with the Zoho account that has access to your CRM.
- Review the requested permission and click Accept.
- Back in the VoisX console, select the actions you want to enable and click Install integration.
VoisX requests one scope: ZohoCRM.modules.ALL (read and write access to CRM modules such as Leads, Contacts and Deals). What the agent can actually change is limited by the role and profile of the Zoho user who connected.
Zoho data centres
Zoho hosts accounts in several data centres. You do not need to pick one: Zoho tells VoisX which data centre your account belongs to when you sign in, and every later API call and token refresh goes to that data centre.
Supported data centres:
| Data centre | Zoho domain |
|---|---|
| United States | zoho.com |
| Europe | zoho.eu |
| India | zoho.in |
| Australia | zoho.com.au |
| Japan | zoho.jp |
| Saudi Arabia | zoho.sa |
| United Kingdom | zoho.uk |
| Canada | zohocloud.ca |
| China | zoho.com.cn |
Token refresh
Zoho access tokens last one hour. VoisX stores a refresh token and gets a new access token automatically shortly before the old one expires, so you do not need to reconnect.
Connect with a dedicated Zoho user (for example an integration user) rather than a personal account. Records the agent creates show that user as the owner, and access does not break when someone leaves.
Actions
create_lead — Create Lead
Creates a new lead record.
Tool reference: {{tool:zoho_crm_create_lead}}
| Parameter | Required | Description |
|---|---|---|
last_name | Yes | Lead's last name |
first_name | No | Lead's first name |
email | No | Email address |
phone | No | Phone number |
company | No | Company name |
lead_source | No | Source (e.g. Web Form, Cold Call) |
description | No | Notes on the lead |
Returns: lead_id, created_time
get_lead — Get Lead
Retrieves a lead by ID.
Tool reference: {{tool:zoho_crm_get_lead}}
| Parameter | Required | Description |
|---|---|---|
lead_id | Yes | Zoho CRM lead ID |
Returns: Full lead record including name, email, phone, status, lead source
update_lead — Update Lead
Updates an existing lead record.
Tool reference: {{tool:zoho_crm_update_lead}}
| Parameter | Required | Description |
|---|---|---|
lead_id | Yes | Lead to update |
email | No | New email address |
phone | No | New phone number |
status | No | Lead status (e.g. Contacted, Not Contacted, Qualified) |
description | No | Updated notes |
search_contacts — Search Contacts
Searches CRM contacts by a text criteria.
Tool reference: {{tool:zoho_crm_search_contacts}}
| Parameter | Required | Description |
|---|---|---|
criteria | Yes | Search string — matches against name, email, phone |
Returns: Array of matching contacts with id, full_name, email, phone
create_contact — Create Contact
Creates a new contact.
Tool reference: {{tool:zoho_crm_create_contact}}
| Parameter | Required | Description |
|---|---|---|
last_name | Yes | Contact's last name |
first_name | No | Contact's first name |
email | No | Email address |
phone | No | Phone number |
account_name | No | Associated company/account name |
Returns: contact_id, created_time
create_deal — Create Deal
Creates a new deal (opportunity).
Tool reference: {{tool:zoho_crm_create_deal}}
| Parameter | Required | Description |
|---|---|---|
deal_name | Yes | Deal name or title |
stage | Yes | Deal stage (e.g. Qualification, Proposal, Closed Won) |
amount | No | Deal value |
closing_date | No | Expected close date (YYYY-MM-DD) |
account_name | No | Associated company |
description | No | Notes on the deal |
Returns: deal_id, created_time
get_deal — Get Deal
Retrieves a deal by ID.
Tool reference: {{tool:zoho_crm_get_deal}}
| Parameter | Required | Description |
|---|---|---|
deal_id | Yes | Zoho CRM deal ID |
update_deal — Update Deal
Updates a deal's stage or value.
Tool reference: {{tool:zoho_crm_update_deal}}
| Parameter | Required | Description |
|---|---|---|
deal_id | Yes | Deal to update |
stage | No | New deal stage |
amount | No | Updated deal value |
closing_date | No | Updated closing date |
Using Zoho CRM in an agent
Lead capture from inbound calls
When a caller expresses interest in the product or requests a demo:
1. Collect their name, email, company name, and phone number.
2. Use {{tool:zoho_crm_create_lead}} to create a lead with this information.
- Set lead_source to "Inbound Call"
- Add any context from the conversation as the description
3. Confirm with the caller: "I've added you to our system. The sales team will be in touch within 1 business day."
If the caller is already a contact, use {{tool:zoho_crm_search_contacts}}
to find them and skip the lead creation step.
Troubleshooting
INVALID_TOKEN or Authentication failure
The connection was revoked in Zoho, or the Zoho user lost access. Reconnect Zoho CRM.
The connection fails after signing in
Make sure you sign in with a Zoho account that has Zoho CRM enabled. If you have more than one Zoho account, sign out of Zoho in your browser first, then connect again.
MANDATORY_NOT_FOUND
A required field is missing. last_name is required for leads and contacts.
DUPLICATE_DATA
A record with that email already exists. Use search_contacts first to check before creating.
Contact or deal not appearing in Zoho
Zoho CRM may have module-level record limits depending on your plan. Check that your plan supports the number of records you're creating.