Zoho CRM

What your agents can doCopy Anchor Link

Helios agents call the Zoho CRM REST API with the connected user's permissions and granted OAuth scopes. Agents can work with records, COQL queries, notes, attachments, files, emails, bulk jobs, tags, users, and settings.

• Create leads from an email or a form, and convert them to contacts, accounts, and deals
• Find records with search or COQL, and update their fields
• Move deals between stages, and add notes, tasks, and attachments to records that support them
• Send email and mail merge documents from a record, and read the emails linked to it
• Export or import many records at once with the bulk read and bulk write APIs
• With Admin access, change fields, layouts, and workflow rules, and manage users

Agents can send GraphQL queries to /crm/graphql when the connected Zoho account supports them. Helios requests scopes to enable the profile's GraphQL schema and read data. See Zoho's GraphQL guide.

Agents can only call these Zoho hosts:

• Your data center's API domain, such as https://www.zohoapis.eu.
• upload.zoho.com for bulk write files, and the faster upload-accl.zoho.com, upload-accl.zoho.eu, or upload-accl.zoho.in in the US, EU, and IN data centers.
• In the US data center, download.zoho.com and download-accl.zoho.com for audit log exports and backups. Zoho doesn't document these download hosts for other data centers, so agents there can't download those files.

Every call uses your organization's Zoho API credits. See Limits.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Your own Zoho CRM OAuth appCopy Anchor Link

You need a Zoho account to register the client in the Zoho API Console. Zoho records every change as the user who approves access, with that user's permissions. For Admin access, that user needs the Administrator profile in Zoho CRM.

1. Open the Zoho API Console for your data center, such as api-console.zoho.com or api-console.zoho.eu. Click GET STARTED, or add a new client if you already have one.

2. Choose Server-based Applications and click CREATE NOW. Enter a client name and a homepage URL, and add this redirect URI:

   Copy Text

   https://api.heliosapp.com/integrations/zoho_crm/oauth_callback

   Click CREATE.

3. Copy the Client ID and Client Secret from the client's Client Secret tab.

4. In Helios, choose Your own Zoho CRM OAuth app. Enter Client ID and Client Secret.

5. Check Admin access if a Zoho CRM administrator will approve access and agents need to change settings, manage users, or back up data.

6. If your Zoho account isn't in the US data center, set Base URL to your data center's API domain from the table below. Helios sends you to that data center to approve access. US accounts can leave it empty.

7. Save, then approve access in Zoho. If you belong to more than one Zoho CRM organization, pick the one Helios should use.

Zoho lists its accounts servers at accounts.zoho.com/oauth/serverinfo. A sandbox or Developer Edition organization uses sandbox.zohoapis or developer.zohoapis instead of www.zohoapis, such as https://developer.zohoapis.com. Zoho tokens only work for the organization and environment they were issued for, so connect each one separately.

Helios also stores the data center that Zoho reports when you connect. A Base URL you set takes precedence over it.

A client in another data centerCopy Anchor Link

If you registered the client in one data center's console and your Zoho account is in another, enable your data center on the client:

1. In the Zoho API Console, open the client and go to the Settings tab.
2. Turn on the toggle next to your data center.
3. Select Use the same OAuth credentials for all data centers and click OK.

Helios stores one client secret for the connection. By default, Zoho gives each data center its own client secret, and the token request fails with invalid_client when the secret doesn't match. See Zoho's multi data center guide.

Scopes and tokensCopy Anchor Link

Helios asks for these scopes:

With Admin access checked, Helios also asks for these:

Zoho checks each call against the profile of the user who approved access. A call that the profile doesn't allow, such as a mass update without the Mass Update permission, fails with NO_PERMISSION. The other calls still work.

Access tokens last one hour, and Helios renews them with the refresh token. Zoho refresh tokens don't expire until they're revoked. Zoho keeps at most 20 refresh tokens for each user, and creating the 21st invalidates the oldest. Each time you approve access, Zoho issues a new one. A user who connects many times can end an older connection's access. Connect that connection again. See Zoho's token validity.

If you change the client secret in the Zoho API Console, enter the new one in Client Secret through Manage and connect again. Connect again after you change Admin access too, so Zoho issues a token with the new scopes.

TriggersCopy Anchor Link

Zoho CRM can start a Workflow when a record in one of its built-in modules is created, updated, or deleted. Helios creates a Zoho notification channel when you connect, so there is nothing to set up in Zoho. This needs the ZohoCRM.notifications.ALL and ZohoCRM.settings.READ scopes above. Zoho ends a channel after at most a week, so Helios replaces it every five days. When you delete the connection, Helios attempts to remove the channel. If removal fails, the channel stays active in Zoho until it expires.

The channel covers every module in the table below that your organization has. When a module is missing, or Zoho refuses to watch it, its events show as unavailable in the trigger picker with the reason.

If renewing the channel fails, for example because access was revoked, events stop. Save the connection again, or connect again, and Helios creates a new channel.

Meetings are called Events in Zoho's API, so their API name is Events.

• Changed field is on every *.updated event. It matches the API name of a field that the update changed, such as Lead_Status or Owner. It's a pattern, such as Lead_*. Case matters. It's optional.
• Moved to stage is on deal.updated. It matches updates whose new Stage value matches, such as Closed Won. It's a pattern, and case matters. It's optional. It uses the new field values that Zoho sends with each update. An update that arrives without a new Stage value doesn't match.

Each event carries the module, the record ID, the operation, and for updates the changed fields with their new values. It doesn't carry the whole record, so the agent reads the record from Zoho. When one action changes several records, such as a mass update, each record starts its own run. Actions on related records, such as a note added to a deal, don't send an event for the deal.

Zoho doesn't sign notifications. Each one carries a random token that Helios sets on the channel, and Helios rejects notifications without it. Zoho also returns that token when a channel is read or changed through /crm/v8/actions/watch. Helios removes it from those responses before an agent sees them, and from the events it passes to workflows.

Check that it worksCopy Anchor Link

• The connection: after you approve access, the connection's status shows Connected. Error means Zoho rejected the token. See Common errors.
• A trigger:
  1. Add lead.created to a workflow with no filters.
  2. Create a test lead in Zoho CRM.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• API credits: Calls count toward your organization's Zoho API limits. See Zoho's API limits.
• Notification channels: a channel lasts at most one week. Helios replaces it every five days.