Zoho Integration

Owned by Valerio Ciotta
Last updated: May 10, 2022 by XCALLY Knowledge (Unlicensed)
8 min read

How it works

   Zoho CRM integration is used to open a task automatically for every call according to the conditions (Queue, Call status or Outbound Route) set in a trigger.

The task will be populated with information about the call and displayed to the agent in the Zoho CRM environment.

The following are list of things you have to do to make the integration work:

  1. Create the Zoho Administrator Account (on zoho.com or zoho.eu), if you don't have one already
  2. Create the ClientID and get the Client Secret key
  3. Create a temporary Developer Console Code (you will use it when you create the Zoho Account on XCALLY Motion to generate the Token for establishing a certified interaction with Zoho)
  4. Create the Zoho Account on XCALLY Motion and test it
  5. Create Zoho Configuration in XCALLY Motion for the account created 
  6. Create the Zoho Users with the same e-mail address as the Agent in XCALLY Motion
  7. Create a Trigger (Tools → Triggers), set the triggering conditions for this integration and add integrations action
  8. Download the XCALLY Motion Phonebar Windows App* and login the Agent on Zoho and on XCALLY Motion (both on the Phonebar and on Omnidesktop interface) and start!


*alternatively, the Agents can use WebRTC or external Phones (of course, they must be logged on XCALLY Motion Omnidesktop)


On this page:



Any interaction occurred through this integration can be searched by the Agent from the list by:

  • contact's phone number
  • lead's phone number
  • user's email

For additional information please refer to official Zoho Documentation:

https://www.zoho.com/crm/developer/docs/api/auth-request.html

After the configuration steps listed above, every time there is an outgoing/incoming call, the trigger conditions are checked and a Zoho Call Activity is created and assigned to the agent managing the call (if the conditions set are met).


What to know

When an Agent manages a call, his/her account email address will be searched in Zoho.com/Zoho.eu: if the system finds it the Call Activity will be assigned, otherwise the Call Activity will be assigned to the Zoho Administrator Account specified in the Zoho integration



If all the configuration is properly set, the Call Activity will be opened as shown below:



The Call Activity Subject, Description and Fields can be managed and customized in the Zoho Configuration section.





What to do on Zoho

The following are the configuration steps to do on Zoho to make the integration work:





Create the Administrator account, by signing in on zoho.com or zoho.eu.

You can skip the registration if you already have one.





About API V2

The Zoho API V2 use the OAuth2.0 protocol for authentication and the Authorization Code Grant Type to obtain an access token. This grant type allows you to share specific data with any application while keeping your username and password private



 





Go to Zoho Developer Console: here you can create a Self Client for XCALLY Motion. 


Take care you choose the right URL where to register your location. Refer to https://www.zoho.com/crm/developer/docs/api/register-client.html for the specific url of your Zoho Developer Console (for instance for EU, it is https://api-console.zoho.eu)








Create New Client choosing Self Client as type








Click on Create and take note of Client ID and Client Secret.








To create the Oauth2 token needed by XCALLY Motion API, we need also a temporary code, called Developer Console Code. To obtain it, click on Self Client → Generate Code section





In the field Scope insert the following value:

ZohoCRM.users.all,ZohoCRM.modules.all,ZohoCRM.settings.all,ZohoSearch.securesearch.read

to obtain a valid Developer Console Code.


Warning: use this specific string to create the code. If you enter a different string, a code will be created anyway, but it will be invalid and the XCALLY Motion API will not be authenticated on Zoho CRM


Choose the validity of the Console Code (from 3 to 10 minutes). 



Take note of the generated Developer Console Code, which will be used, together with ClientId and ClientSecret obtained before, on XCALLY Motion.


Warning

We strongly suggest to indicate the maximum time window allowed (i.e. 10 minutes) and to proceed promptly to create the XCALLY Motion Account, because if you fail to generate the Oauth2 token within the time window you set, the Developer Console Code expires and to make the integration work you must create a new one. If you follow all the procedure and the token is not working we suggest to repeat the generation of the Developer Console Code step and to try again.




What to do on XCALLY: the Zoho Accounts


The Zoho Accounts Section is under the Integrations Menu

Add the Integration clicking the Button  and insert the requested values:






  • Name: chose the name you want to assign to the Account
  • Host: the choice is between zoho.com and zoho.eu
  • Zone: insert here your specific region (refer to the table here: https://www.zoho.com/crm/developer/docs/api/refresh.html )
  • Client ID (see above)
  • Client Secret (see above)
  • Developer Console Code (see above. Warning: it will expire if not used within the previously set time window!)
  • proxy IP address (the URL of your XCALLY Motion application)


At the end click ADD ZOHO ACCOUNT. 


Reminder

As mentioned above, you must register your application at the Zoho Developer Console to receive your Client ID (a unique identifier you receive when you register your application) and Client Secret (a unique key generated when you register your application with Zoho that must be kept confidential). 






During the Account creation a Refresh Token will be automatically generated (it will be the Oauth2 token used by XCALLY Motion to authenticate API requests). 



You can see this value editing the Zoho Account (Tab General).





Remember to Test Zoho Account configuration to check if the credentials are accepted by the system:

or if you made some mistakes:


If an API error is returned, check all values inserted and eventually try to generate a new Developer Console Code (this may happen when the time window set is exceeded)




Click on Add Configuration


Now insert the Configuration parameters:

  • Name: any name you prefer
  • Channel: the channel you want the integration to be active (e.g. Voice)
  • Type: select one of the proposed values (e.g. Inbound in Queue or Outbound Calls)

At the end click on Add Zoho Configuration





The Configuration added is immediately active and the default values (Subjects, Descriptions, Fields and Advanced) are configured by the system.








You can add more than one Field.

In the drop-down list you can find the complete list of fields available in your Zoho account: Standard and Custom Ticket fields.

Choose the field from the list (Standard or Custom):

and define the Type:

  • String: static string (you must insert it)
  • Variable: a System Variable (choose it from the list: e.g. Queue, uniqueid, calleridnum, etc.)
  • Custom Variable: one of the dynamic variables (created under Tools > Variables)
  • Picklist: choose among the list of the integrated Application Fields. You can only select one of the predefined values available for that field (if any).






In the Configurations ADVANCED tab (available in XCALLY Motion starting from version 2.4.19**) you can set:

  • how to Search the Module: as Contact, as Lead or as both of them

  • what to do if the Module is not found in the system: nothing or Create the Module as Contact or as Lead

How it works up to version 2.4.18

**The caller phone number will be searched in the Contacts and, if not there, also in the Leads. If the contact number is not found in both of them, a new Lead will be created.

Now you have to add agents (the so called Users) in Zoho, having the same e-mail address as on XCALLY Motion: 

  1. Click  (the Settings icon) > Setup > Users > + Add New User
  2. Select a Standard profile
  3. Be sure to use the same email as the agent that use the Zoho integration on XCALLY Motion 
  4. confirm the registration

All the leads/contacts are property of the Administrator, so the Agent will be able to see only the calls he manages

To allow the agent to see all the contacts and the leads, you have to modify the data sharing rules (operation allowed only to a Zoho Enterprise account)


To manage default permissions: 

  1. Click Settings > Setup > Users & Control > Security Control > Data Sharing Settings.
  2. In the Data Sharing Settings page, click Edit All Default Permissions.
  3. In the Edit Default Organization Permissions page, update the Access Privilege for Contacts and Leads modules from Private to Public Read/Write/Delete

Create a Trigger 

It is mandatory to create a trigger to make the Zoho integration work.

Go to Tools -> Triggers Section and click on New Trigger




Enter the trigger Name, select Voice Channel and click on Add Trigger. 

Edit the trigger to define the trigger's Conditions and Actions


Do not forget to set the trigger's status ON.

Add Trigger Conditions

In the Conditions section of the Conditions & Actions you can set properties like Queue, Call status or Outbound Route to define the conditions you want to trigger the Zoho integration:

Add Trigger Action

To execute the Zoho integration when the conditions are met, add them in the Action section of the Conditions & Actions: insert Integrations and Zoho


You can now select one of the the Zoho account you have created and the configuration you want to use.


For more information on trigger conditions, take a look at Voice Trigger Conditions.




How to update an existing Zoho Account (created using Zoho API V1 and XCALLY Motion up to version 2.4.3)

If you created a Zoho Account on XCALLY Motion version 2.4.3 (or earlier), it will not be operational after the end of January 2020, because Zoho API V1 endpoints have been dismissed. 

In order to adopt the new API V2 for protocol authentication, you have to:

  • download XCALLY Motion version 2.4.4
  • edit the Zoho API credentials and retrieve the values that are missing on the XCALLY Motion Zoho Account 
  • edit the XCALLY Motion Zoho Account and insert the missing values (those retrieved on Zoho) in the empty fields of the Tab General and save the changes

in order to create a new and valid token.

The steps to follow are the same as previously described, except for creating the account.