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.
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.
For each core method in the ZohoDesk integration, the solution contains a corresponding example 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.
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.
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
https://desk.zoho.com
https://desk.zoho.eu
https://desk.zoho.in
https://desk.zoho.cn
https://desk.zoho.au
OAuth API URL
https://accounts.zoho.com/oauth/v2/token
https://accounts.zoho.eu/oauth/v2/token
https://accounts.zoho.in/oauth/v2/token
https://accounts.zoho.cn/oauth/v2/token
https://accounts.zoho.au/oauth/v2/token
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.
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.
Desk.tickets.ALL,Desk.contacts.READ,Desk.basic.READ,Desk.search.READ,Desk.contacts.READ,Desk.settings.READ
.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
}
Each access token is valid for only an hour and used only for the operations defined in the scope. Refresh token does not expire. Use it to refresh access tokens when they expire. You can only generate a maximum of five refresh tokens in a minute.
You can now find the organization Id for your Zoho Desk by following the steps given below,
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 |
Obtain the ticket status configuration by doing the following:
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 |
This step is optional for people that have congifured their ticket status configurations.
To update the global variables, proceed as follows:
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.
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, 106User: 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, 106User: 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!
For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.
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.
Was this page helpful?