Zoho

The Zoho connector supports the following Zoho products:

• Zoho CRM (default)
• Zoho Desk
• Zoho Mail

Zoho CRM

Supported Actions

This connector supports:

• Read Actions, including full historic backfill and incremental read.
• Write Actions.
• Proxy Actions, using the base URL https://www.zohoapis.com.
• Subscribe Actions.

Supported Objects

Object	Read	Write	Subscribe
Leads
Accounts
Contacts
Deals
Campaigns
Tasks
Cases
Events
Meetings
Calls
Solutions
Products
Vendors
Price Books
Quotes
Sales Orders
Purchase Orders
Invoices
Appointments
Appointments Rescheduled History
Services
Custom
Users

Example Integration

For an example manifest file of a Zoho CRM integration, visit our samples repo on GitHub.

Zoho Desk

Supported Actions

This connector supports:

• Read Actions, including full historic backfill and incremental read for most objects.
• Write Actions.

Supported Objects

The Zoho connector allows you to read from and write to these objects:

• organizations
• agents
• profiles
• roles
• departments
• channels
• tickets
• contacts
• accounts
• tasks
• products
• helpCenters
• users
• labels
• groups
• articles
• articleFeedbacks
• kbRootCategories
• contracts
• ticketTemplates
• calls
• events
• organizationModules
• languages
• countries
• timeZones
• businessHours
• domains
• holidayList
• im/channels
• im/sessions

Example Integration

For an example manifest file of a Zoho Desk integration, visit our samples repo on GitHub.

Zoho Mail

To use Zoho Mail, add module: mail to your integration definition in amp.yaml:

specVersion: 1.0.0
integrations:
  - name: myZohoMailIntegration
    provider: zoho
    module: mail

Supported Actions

This connector supports:

• Read Actions, including full historic backfill. Please note that incremental read is not supported, a full read of the Zoho Mail instance will be done for each scheduled read.
• Write Actions.
• Subscribe Actions. Please note that special set up is needed for Zoho Mail: Zoho Mail has no API to create or manage webhook subscriptions, so your customer configures an outgoing webhook by hand in the Zoho Mail console, and Ampersand verifies and processes the delivered events.

Supported Objects

Object	Read	Write	Subscribe
accounts
accounts/folders
accounts/labels
collections
customStatus
groups/collections
links
links/favorites
links/groups
links/me
links/trash
messages
notes
notes/books
notes/favorites
notes/groups
notes/sharedtome
signature
tasks
tasks/groups

Subscribe events

Ampersand supports two of Zoho Mail’s outgoing-webhook entities, delivered to the same endpoint:

• messages: fires when a new email is received. When configuring the webhook, your customer can optionally narrow it with conditions (e.g. sender or subject filters) or tags; a webhook also fires when a matching tag is manually applied to an email. All mail deliveries surface as createEvent — Zoho Mail does not send webhooks for message updates or deletions.
• tasks: fires on task activity in groups your customer owns or moderates. Supports createEvent, updateEvent, and deleteEvent, mapped from the task action that triggered the webhook.

Zoho Mail’s third outgoing-webhook entity, Streams Posts, is not supported.

Set up Subscribe Actions for Zoho Mail

Zoho Mail has no API for creating webhook subscriptions, so unlike Zoho CRM, Ampersand cannot register the webhook on your customer’s behalf. Instead:

1. Define the subscribe action in your amp.yaml and deploy it with the amp CLI:

   specVersion: 1.0.0
   integrations:
     - name: subscribeToZohoMail
       provider: zoho
       module: mail
       read: # Read action is required for subscribe actions
         objects:
           - objectName: messages
             destination: mailWebhook
             requiredFields:
               - fieldName: messageId
               - fieldName: subject
               - fieldName: fromAddress
               - fieldName: receivedTime
             optionalFields:
               - fieldName: toAddress
               - fieldName: summary
           - objectName: tasks
             destination: mailWebhook
             requiredFields:
               - fieldName: id
               - fieldName: title
             optionalFieldsAuto: all
       subscribe:
         objects:
           # Zoho Mail only sends webhooks for newly received emails, so
           # messages support createEvent only.
           - objectName: messages
             destination: mailWebhook
             inheritFieldsAndMapping: true
             createEvent:
               enabled: always
           # Task webhooks fire on group task activity; the task action is
           # mapped to create/update/delete events.
           - objectName: tasks
             destination: mailWebhook
             inheritFieldsAndMapping: true
             createEvent:
               enabled: always
             updateEvent:
               enabled: always
               watchFieldsAuto: all
             deleteEvent:
               enabled: always
   

2. Construct a webhook URL for your customer in this format:

   https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
   

3. Share the Zoho customer guide with your customer along with the webhook URL from Step 2. Your customer will create an outgoing webhook in the Zoho Mail console (Settings > Developer Space > Webhooks > Outgoing Webhooks > Create new configuration) that delivers events to this URL. See the Zoho Mail webhook documentation for details.

Example Integration

For an example manifest file of a Zoho Mail integration, visit our samples repo on GitHub.

Before You Get Started

To connect Zoho with Ampersand, you will need an account in an appropriate Zoho product:

• Zoho CRM Account
• Zoho Desk Account
• Zoho Mail Account

Once your account is created, you’ll need to configure an app in Zoho and obtain the following credentials from your app:

• Client ID
• Client Secret
• Scopes

You will use these credentials to connect your application to Ampersand.

Create a Zoho Account

Go to the particular Zoho product sign-up page and create an account:

• Zoho CRM Sign Up page
• Zoho Desk Sign Up page
• Zoho Mail Sign Up page

Creating a Zoho App

Follow the steps below to create a Zoho app and add the Ampersand redirect URL:

1. Log in to the Zoho API Console Account using your Zoho account.
2. Click Get Started to create your first app. If you have already created an application, click Add Client to create a new app.
3. Select Server-based Applications.
4. Enter the following details:
   • Client Name: Name of the client app
   • Homepage URL: The home page URL of your app
   • Authorized Redirect URIs: The Ampersand redirect URL: https://api.withampersand.com/callbacks/v1/oauth
5. Click Create.

You’ll see the details of your newly created application. Note the Client ID and Client Secret keys as they are necessary for connecting your app to Ampersand.

6. Select the checkbox “Use the same OAuth credentials for all data centers” in the settings tab. Also toggle all regions where you expect to have customers.

Add Your Zoho App Info to Ampersand

1. Log in to your Ampersand Dashboard.
2. Select the project where you want to create a Zoho integration.
3. Select Provider apps.
4. Select Zoho from the Provider list.
5. Enter the previously obtained Client ID in the Client ID field and the Client Secret in the Client Secret field.
6. In the Scopes field, enter the list of desired scopes for your integration. We recommend the following scopes. If you want more granular scopes, please refer to the Zoho documentation for syntax.

Zoho CRM:

ZohoCRM.modules.ALL
ZohoCRM.settings.ALL

In case you are using Subscribe action with Zoho CRM, additional scope is required

ZohoCRM.notifications.ALL

Zoho Desk:

Desk.basic.READ 
Desk.settings.ALL 

Zoho Mail:

ZohoMail.accounts.ALL
ZohoMail.folders.ALL
ZohoMail.tags.ALL
ZohoMail.messages.ALL
ZohoMail.tasks.ALL
ZohoMail.notes.ALL
ZohoMail.links.ALL

The accounts scope is always required (ZohoMail.accounts.READ is sufficient): Ampersand uses it after authentication to resolve your customer’s Zoho Mail account ID, which account-scoped objects (messages, accounts/folders, accounts/labels) depend on. You can drop the scopes for object families you don’t use.

7. Click Save changes.

Customer Guide

The Zoho Customer Guide can be shared with your customers to help them successfully use your integration.

List on Zoho Marketplace

The final step, which is optional, is to list your application on the Zoho Marketplace. Follow the steps below to list your application:

1. Sign up and create a company profile on the Zoho Marketplace.
2. Click on the profile icon on the home page and select Partner Console.
3. Select Company Profile on the left panel.
4. Provide your company details. Note that these are your own company’s details, not Ampersand’s.
5. After successful registration, go to Apps on the left sidebar and click Submit App.
6. Complete the process by adding your app’s details and submitting it.