Building Extensions #14: Creating widgets with the JS SDK bundle in Zoho Desk - Hooks 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.

Hello developers!

In our previous post, we explained the use of the resources API and provided an example of how to use them in a Zoho Desk extension. In this post, we'll continue with the Hooks API.

What is the hooks API?

The hooks API allows developers to control the flow of UI actions through their extensions on a conditional basis. You'll need to subscribe to the hooks and, based on your requirements, you can allow the event to happen or reject it by passing either boolean values or promises in the event handler.

If the boolean value TRUE is passed/if the extension resolves the promise, the event will be executed.
If the boolean value FALSE is passed/if the extension rejects the promise, the event will be terminated and the reason for terminating the event will be displayed as an error message to end users.

Extensions with subscriptions to hooks must respond within 30 seconds of the event being triggered. If not, the control provided by the extension will be lost and the event will be executed.

What events are supported by the hooks API ?

Zoho Desk currently supports hooks for the following events:

Reopening a ticket
Closing a ticket
Changing the status of a ticket
Changing the assignee of a ticket
Adding a ticket comment
Editing a ticket comment
Sending a ticket reply
Closing a ticket on sending ticket reply
Updating the agent status in a channel

Click this link to find out more about the events and locations that are supported for every event within Zoho Desk.

Now that we have an understanding of the hooks API, including when and where it can be used, let's look at an example of how it can be used in an extension.

Defining the hooks API

Below is the structure of the hooks API to be defined in your extension code.

      App.instance.on('name of the hook to be subscribed', function(){
          //return promise or boolean
      })

You can subscribe to the required hooks and include your required custom logic. The custom logic should either return TRUE or the promise needs to be resolved to allow the subscribed event to occur; otherwise the event occurrence will be blocked with a relevant message popping up that you provide.

Hooks related to ticket status, ticket comments, and other parameters will return data that can be used within your custom logic.

Possible scenarios

Let's create an extension that tracks the activities associated with a ticket in Zoho Desk. The extension monitors the activities (e.g., a call, task, or event) of Zoho Desk tickets and controls the trigger of actions based on the hooks defined.

In this example, we're configuring an extension to subscribe to the Zoho Desk hook defined for the close ticket event. With this extension, when the agent tries to close the ticket, the extension checks whether the activities mapped to the ticket are completed.

If they are completed, the extension will allow the ticket to close in Zoho Desk; otherwise, the close ticket event will not be executed and a relevant error message will be displayed. In addition, we're configuring the hook to consider the activity as completed for both cancelled and no activities as well in the ticket.

Use case implementation

To implement our use case, we'll perform the following steps. The code snippet is added for reference.

Obtain the activities associated with the current ticket
Obtain the status of the activities
Subscribe to the ticket status hook and handle the event handler according to the requirements
Subscribe a hook to close the ticket

Sample code

window.onload = function () {

ZOHODESK.extension.onload().then(App=>{

var activityStatus;

ZOHODESK.get(['ticket.id']).then(function (res) {

var result = res.data;

ticketID=result["ticket.id"];

//Get the activities associated to the ticket

var reqObj= {

url: 'https://desk.zoho.com/api/v1/tickets/'+ ticketID+'/activities',

headers: {

'Content-Type': 'application/json'},

type: 'GET',

postBody: {},

connectionLinkName: "deskproject"

}

ZOHODESK.request( reqObj ).then(function(response){

var resultparse = JSON.parse(response);

var resultparse2=JSON.parse(resultparse.response).statusMessage;

//From the response obtain the status of the activities

if(resultparse2!=null){

var resultparse3=resultparse2.data;

for (let i = 0; i < resultparse3.length; i++) {

activityStatus=resultparse3[i].status; }

}

})

//Register a Hook for changing the status of a ticket

            App.instance.on('ticket.status', function (data) {
            return new Promise((resolve, reject) => {
            if ((data["ticket.newStatus"] == "Closed")){
            if((activityStatus=="Completed")||(activityStatus=="Canceled")||(activityStatus==null))
            {
                  return true;
            } else {
                  reject({ msg: "Incomplete Activity" });
                  }
            }
                  })
})

//Register a Hook for ticket close event

App.instance.on('ticket.close', function () {

if((activityStatus=="Completed")||(activityStatus=="Canceled")||(activityStatus==null))

{

return true;

} else {

reject({ msg: "Incomplete Activity" });

}

})

}

Result:

Here, you can see that the extension doesn't allow you to close the ticket because there is an open activity tagged. This is how the hooks API helps us to configure whether an event should happen or not, based on the hook configured.

We hope you found this post to be useful. Stay tuned for more posts in this space!