Zoho Integration
- Valerio Ciotta
- XCALLY Knowledge (Unlicensed)
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:
- Create the Zoho Administrator Account (on zoho.com or zoho.eu), if you don't have one already
- Create the ClientID and get the Client Secret key
- 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)
- Create the Zoho Account on XCALLY Motion and test it
- Create Zoho Configuration in XCALLY Motion for the account created
- Create the Zoho Users with the same e-mail address as the Agent in XCALLY Motion
- Create a Trigger (Tools → Triggers), set the triggering conditions for this integration and add integrations action
- 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)
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).
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.
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:
- Click
(the Settings icon) > Setup > Users > + Add New User - Select a Standard profile
- Be sure to use the same email as the agent that use the Zoho integration on XCALLY Motion
- 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:
- Click Settings > Setup > Users & Control > Security Control > Data Sharing Settings.
- In the Data Sharing Settings page, click Edit All Default Permissions.
- 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.