Building Extensions #8: Create widgets with the JS SDK bundle in Zoho Desk - Data API

This series aims to equip developers with all they need to build extensions for Zoho Desk in Zoho Sigma and publish them in Zoho Marketplace.

We hope that you've been able to use the information in previous posts to understand building extensions for Zoho Desk and the configuration of various components required while building them. In this post, we'll introduce the various API methods available in the Zoho Desk JS SDK bundles, which will help you experiment with the capabilities of the Zoho Desk Platform. We'll begin with creating widgets using the APIs in this post, and proceed with additional advanced features provided on the platform in the upcoming posts.

The JS SDK provided by Zoho Desk is a package of multiple APIs that helps in interacting with the Zoho Desk data while building extensions. Depending on the purpose met by these APIs, they are grouped and are provided with unique names. These APIs can be used in your extensions to fetch data from various objects of the Desk portal. Based on your business requirements, you can work on these data and use them in your extensions' widgets.

Before we start with the API categories, there are two important points to note. To utilize the APIs in your extension, the min.js file of the JS SDK needs to be added to your code snippet and the widget initialization should be completed.

The JS SDK is provided with onload() API method by default, which will initialize your widget within the Desk portal. When an extension is accessed, this API is invoked and opens the widget. All other APIs in the JS SDK package can be used once the extension is initialized. The following code initializes your widget.

ZOHODESK.extension.onload()

To ease development, the onload() API method is included in the widget.html file of every project that you create. The sample code snippet of all the platform-supported APIs will also be available in the widget.html file. With such an easy-to-use platform, all a developer needs to do is pick and include the APIs they need for their extension.

<script src="https://js.zohostatic.com/support/developer_sdk/v1/js/ZohoDeskClientSDK.min.js"> </script>

<script>

window.onload = function () {

ZOHODESK.extension.onload().then(function (App) {

//Get ticket related data

ZOHODESK.get('ticket.email').then(function (res) {

//response Handling

}).catch(function (err) {

//error Handling

});

...

});

};

</script>

The following list of APIs are available in the JS SDK package, each serving a unique function. Based on your business requirements, you can include the APIs in your extensions.

Data APIs
Data Storage APIs
Extensions API
Resources API
Request API
Invoke API
Events API
Hooks API

Data APIs

Zoho Desk provides a set of data APIs to communicate with the various objects within your Zoho Desk portal. The objects that are supported for APIs are listed below:

Ticket Object
Contact Object
Account Object
User Object
Portal Object
Department Object
Extension Object

Ticket Object

The different properties of a Desk ticket can be accessed and it is currently limited to the widget locations desk.ticket.detail.rightpanel, desk.ticket.detail.subtab, desk.ticket.detail.lefttab, desk.ticket.detail.moreaction, and desk.ticket.thread.moreaction.

To fetch a ticket along with all associated properties from the desk portal, use the below API.

ZOHODESK.get("ticket").then(function(response)

{

//response returns all the properties of the ticket

})

An individual property of a ticket can be obtained by using the following API.

ZOHODESK.get("ticket.<property>").then(function(response)

{

//response returns the property data of the ticket

})

where <property> refers to a particular property or data you need to fetch from the current ticket. For example, department ID, email, etc.

Contact Object

The various properties of a contact within the Desk portal can be accessed. It is accessible only from the contact detail page locations, and global widget locations.

ZOHODESK.get("contact.<property>").then(function(response)

{

//Response - requested detail

}).catch(function(err){

//Error Handling

})

Account Object

This object provides you with access to the various properties of an account. It is accessible only from the account detail page locations, and global widget locations.

ZOHODESK.get("account.<property>").then(function(response)

{

//Response - requested detail

}).catch(function(err){

//Error Handling

})

User Object

The details of a user can be obtained from the Desk portal using the following API.

ZOHODESK.get("user").then(function(response)

{

// response returns information about a particular user

}).catch(function(err){

//Error handling

})

To obtain individual properties of the users, use the following API.

ZOHODESK.get("user.<property>").then(function(response)

{

//response returns information about a particular user

}).catch(function(err){

//Error handling

})

where <property> can take up one of the following values:

isLightAgent - Returns a boolean value stating whether the user is a LightAgent or not.
tzoffset - Fetch the time offset of a particular user. Time offset refers to the difference in time between the Coordinated Universal Time (UTC) and the current standard time in the user's time zone. The time difference is expressed in minutes.
fullName
email
portals - Returns the name of the users' portal.

Portal Object

To obtain the various details of a portal, the following API can be used.

ZOHODESK.get("portal.<property>").then(function(response)

{

//response returns the current Zoho Desk plan of the portal

}).catch(function(err){

//Error Handling

})

where <property> can take up the following values.

plan
id
name
customDomainName

Department Object

To obtain the department details of the portal, the following API can be used. This API can be used only by the users with Admin role.

ZOHODESK.get("department.<property>").then(function(response)

{

//response returns the list of departments

}).catch(function(err){

//Error Handling

})

where <property> can take up the following values

list - The list of departments in the portal
id - The department of the agent currently working
info - Fetch details about a particular department. The department id should be passed as a parameter

Extension Object

When you build an extension, you will be adding your configuration details in the plugin-manifest file. You can obtain these configuration details from the file using this API. You can also set configuration values.

You can fetch the installation parameters of the extension. In production mode, only those parameters that have the value of the secure key set to false can be retrieved. In development mode, all parameters can be obtained irrespective of the value of the secure key.

ZOHODESK.get("extension.config").then(function(response)

{

//response returns the installation parameters of the extension

}).catch(function(err){

//error handling

})

As we already know, the extensions you build for Zoho Desk will be hosted in Zoho Marketplace from where users can install the extension. For your reference, here are some extensions from the Zoho Marketplace that are built for Zoho Desk using the Data APIs explained above. These could give you an idea of how the functionality of Zoho Desk can be enhanced using widgets.

In this post, we've stuck to explaining Data APIs. We'll be covering the features of other APIs available in the JS SDK package in the upcoming posts.

Stay tuned!