Zoho Desk

The ZohoDesk example solution showcases how to connect a Teneo solution with the ZohoDesk REST API. The example flows in the solution demonstrate how user can be authenticated as well as how to retrieve, filter, create, update and delete tickets on ZohoDesk.

Solution contents

ZohoDesk integration

The solution contains a ZohoDesk backend integration containing methods for authentication, retrieval of tickets, filtering tickets, create, update and delete tickets. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.

Example flows

For each core method in the ZohoDesk integration, the solution contains a corresponding example flow:

• User asks to retrieve tickets assigned to authenticated user
• User asks to create a ticket
• User asks to update a ticket
• User asks to delete a ticket
• User asks to filter tickets

Authentication flow

ZohoDesk provides a support for OAuth authentication method that allow a Teneo bot to interact with ZohoDesk on the user's behalf. This example solution contains flow to demonstrate OAuth 2.0 based authentication approach.

Getting started

Prerequisites

These instructions assume you have a ZohoDesk admin account. Alternatively, you can signup for a free user account on Zoho Desk. These instructions assume you have downloaded and imported the ZohoDesk solution. See instructions below.

ZohoDesk Base URL references

Data privacy and protection laws today require that collected data must be stored in data centers that are physically located in the respective country or region. To facilitate compliance, Zoho has set up multiple data centers across different regions. Each data center only holds the data of those users that signed-up to it. Find base url's for each region and it's important to refer the most suitable base URL according to your region for references:

ZohoDesk API URL

• United States (US) - https://desk.zoho.com
• Europe (EU) - https://desk.zoho.eu
• India (IN) - https://desk.zoho.in
• China (CN) - https://desk.zoho.cn
• Australia (AU) - https://desk.zoho.au

OAuth API URL

• United States (US) - https://accounts.zoho.com/oauth/v2/token
• Europe (EU) - https://accounts.zoho.eu/oauth/v2/token
• India (IN) - https://accounts.zoho.in/oauth/v2/token
• China (CN) - https://accounts.zoho.cn/oauth/v2/token
• Australia (AU) - https://accounts.zoho.au/oauth/v2/token

ZohoDesk API authentication steps (OAuth2.0)

Zoho Desk's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization.This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. Each API request must include an OAuthToken to retrieve any resource from your Zoho Desk portal. In order to follow the steps below.

Generating OAuth Tokens Using 'Self Client'

Use this method to generate the grant token if your application does not have a domain and a redirect URL. You can also use this option when your application is a standalone server-side application performing a back-end job.

1. Go to Zoho Developer Console.
2. Choose Self Client from the list of client types followed up with Create Now.
3. Click 'OK' in the pop up to enable a self client for your account.
4. Now, your client ID and client secret are displayed under the Client Secret tab. Copy the newly generated grant token code along with client id & secret and store them securely.
5. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details. For an example, Desk.tickets.ALL,Desk.contacts.READ,Desk.basic.READ,Desk.search.READ,Desk.contacts.READ,Desk.settings.READ.
6. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
7. Enter a description as you wish and click on 'Generate' and copy the generated json response from body and store it securely.

Generating Tokens

Invoke a URL in the following format by using cURL (Command line tool) as this is an one time activity to exchange the authorization code (obtained at the end of the previous step) with an OAuthToken. For this you will need the following which should be collected in the previous step.

Parameter	Description
code	Authorization code obtained after generating the grant token.
client_id	Client ID obtained after registering the client.
client_secret	Client secret obtained after registering the client.
grant_type	"authorization_code"

Access Token API URL: Paste the following line to your command line interpreter application after replacing the values. curl "https://accounts.zoho.eu/oauth/v2/token?code=INSERT_TOKEN_CODE_HERE&grant_type=authorization_code&client_id=INSERT_CLIENT_ID_HERE&client_secret=INSERT_CLIENT_SECRET_HERE" -X POST

The line should look something like this: curl "https://accounts.zoho.eu/oauth/v2/token?code=1000.eb3b70bXXXXXXXXXXX40b3e15.dcd8744bXXXXXXXXXX&grant_type=authorization_code&client_id=1000.HDFDFPETM9CD3D0XXXXXXX&client_secret=e23d7fe02XXXXXXXXXXdf6e7256XXXXXXXXX" -X POST

After invoking the URL, you will be presented with an access token, which you must include in all API calls. So copy the generated access token and refresh token from json response and store it securely.
Response example:
{
"access_token": xxxxxxxxxxx,
"refresh_token": xxxxxxxxxxxx,
"token_type": "Bearer",
"expires_in": xxxx
}

Getting Department Id

1. Sign into a ZohoDesk portal
2. Click on the Setup icon on top most right side corner or press the 'S'.
3. Under the 'GENERAL' section, click on the 'Departments' menu.
4. Click on Default department name link under 'ACTIVE' tab
5. Go to browser URL area, copy the last part (Long number format) of an URL.

Getting Organization Id

You can now find the organization Id for your Zoho Desk by following the steps given below,

1. Click on the Setup icon on top most right side corner or press the 'S'.
2. Click on API menu available under 'Developer Space'.
3. Scroll down to the bottom most section of the web page in ZohoDesk portal and copy an organization Id from OrgId section.

Add credentials to your solution

The solution contains a global variables ZohoDesk_sOrgId, ZohoDesk_sDeptId, ZohoDesk_sClientId, ZohoDesk_sOauthAccessToken, ZohoDesk_sClientSecret and ZohoDesk_sOauthRefreshToken in which various keys we have collected should be stored. We’re interested in our instance based Oauth keys. People may try to use their ZohoDesk OAuth keys accordingly. The values of the global variables should be a type of String like this:

Variable Name	Example value	Description
ZohoDesk_sClientId	'1000.HDFDFPETM9CD3D0XXXXXXX'	Client id for Oauth2.0
ZohoDesk_sClientSecret	'e23d7fe02XXXXXXXXXXdf6e7256XXXXXXXXX'	Client secret for Oauth2.0
ZohoDesk_sOauthRefreshToken	'1000.XXXXXXXX79f8dd2d6e5dc0.69b8XXXXXXXXX30ac34'	Oauth 2.0 refresh token
ZohoDesk_sDeptId	'6XX2XXXXXXX070XX'	Department id of a ZohoDesk user
ZohoDesk_sOrgId	'XXX7631XXX9'	Organization id of an ZohoDesk user
ZohoDesk_sOauthAccessToken	'1000.eb3b70bXXXXXXX'	Oauth2.0 access token

Add Ticket Status configuration to your solution (Optional)

Obtain the ticket status configuration by doing the following:

1. Sign into the ZohoDesk portal.
2. Click on the Setup icon on top most right side corner or press the 'S'.
3. Under 'CUSTOMIZATION' section, click on Ticket Status menu.
4. Copy all items listed under STATUS column

The solution contains a global variable ZohoDesk_lTicketStatusList in which various ticket statuses we have configured in ZohoDesk instance should be stored. We’re interested in our instance based ticket status configurations. People may try to use their ZohoDesk ticket status configurations accordingly. The value of the global variable should be a type of String like this:

Variable Name	Example value	Description
ZohoDesk_lTicketStatusList	['Open','On Hold','Escalated','Closed']	Ticket status list configuration as per Org level customization

Update the Global Variables

To update the global variables, proceed as follows:

1. In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
2. In you ZohoDesk solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
3. Select the 'Variables' tab at the top, select the variables called ZohoDesk_sOrgId, ZohoDesk_sDeptId, ZohoDesk_sClientId, ZohoDesk_sOauthAccessToken, ZohoDesk_sClientSecret, ZohoDesk_sOauthRefreshToken and ZohoDesk_lTicketStatusList.
4. In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
5. When done, click 'Save All' in the top left corner.

Test in Try Out

Your solution is now ready. You can test this in Try Out by asking I want to retrieve tickets assigned to user. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the tickets, which are assigned to an user on ZohoDesk portal.

Example conversations

User: I want to retrieve tickets assigned to user
Bot: Please enter an assignee full name. Note: Assignee full name is case sensitive.
User: test user
Bot: Below are list of tickets assigned to test user. 101, 102, 103, 106

User: Can I filter my tickets
Bot: Please choose one of the following filters, FilterView1, FilterView2
User: FilterView2
Bot: Below are list of tickets available from a filter FilterView2. 102, 106

User: I want to create a ticket
Bot: Please enter a subject.
User: My First ZohoDesk ticket
Bot: Please choose one of the following contacts, test user, test user1, test user2
User: test user1
Bot: New ticket 107 has been created successfully!

User: Can I update my ticket
Bot: Please enter a ticket number
User: 107
Bot: Please choose one of the following fields, 1) Status 2) Priority
User: Status
Bot: Please choose one of the following statuses. Open, On Hold, Escalated, Closed
User: On Hold
Bot: Status field has been updated on a ticket number 107 successfully!

User: I want to delete a ticket
Bot: Please enter a ticket number.
User: 107
Bot: Ticket number 107 has been deleted successfully!

More on authentication

ZohoDesk offers OAuth authentication that developers can use to allow their users to authenticate with ZohoDesk.

All the use case flows in ZohoDesk solution uses OAuth2.0 protocol based access token to authenticate the requests to ZohoDesk API. Every 60 minutes once, access token will get expired for security reasons by ZohoDesk OAuth server. The ZohoDesk solution flows has the capability to refresh the access tokens automatically upon expiry and hence API requests are deemed as valid and gets passed.

This authentication uses stored credentials from a global variable ZohoDesk_sClientId, ZohoDesk_sClientSecret, ZohoDesk_sOauthRefreshToken, ZohoDesk_sOrgId to prepare an authentication with ZohoDesk. ZohoDesk_sOauthAccessToken authorization header value checks an access against ZohoDesk instance URL stored on ZohoDesk_sApiEndPointUrl and return a successful authentication.

The value will be auto assigned at run time in the global variable ZohoDesk_sOauthAccessToken and this global variable can be used for subsequent requests that require authentication across flows in the ZohoDesk solution. The global variable is used by the ZohoDesk integration for the various REST requests.

This authentication flow can be used in production grade as it uses OAuth 2.0 protocol in Teneo in a more secured way by using any industrial standard techniques.

The authentication mechanism for the OAuth2.0 authentication roughly looks like this:

For more details on ZohoDesk and OAuth2.0 based authentication, see: Digging Deeper into OAuth2.0 in ZohoDesk.

Download

• Download the solution from the following link: ZohoDesk.solution.
• Import the solution into Teneo. For more details see: How to import solutions.