Events API

Event APIs enable you to react to events that occur in the user interface of the page. This includes button clicks, changes and updates to field values. You can register event listeners which get invoked when the event occurs. Some events can be intercepted and the app can decide to allow or prevent the action from completing.


Event Payload
When the callback method is invoked, an event payload is passed to it. The payload is a JavaScript object that contains a type field and a data object.

1
2
3
4
5
// event_type contains the name of the event var event_type = event.type; // event_data is a JSON whose value depends on the type of event var event_data = event.helper.getData();

Click Events
Occurs when the user clicks a button or link in the page. The helper method event.helper.getData() will return an empty JSON for most of these events. The only exception are the timer events.

Take a look at the Simple Events API app for a demonstration of this feature.


Change Events
Occurs when the user changes the value of a ticket property. The event will get trigerred even if the value is not submitted. The helper method event.helper.getData() will return a JSON that contains the old and new value of the changed field.

1
2
3
4
{ "old": <old_value>, "new": <new_value> }

Intercepting Events
Intercepting events are click events that are paused while the event listener executes. The listener can choose to either allow the original event to complete or it can block the event.

1
2
3
4
5
// To allow the original event to continue event.helper.done() // To prevent the original event from completing event.helper.fail(errorMessage)

The errorMessage is a string that will be displayed to the user as an error notification. The helper method event.helper.getData() will return an empty JSON for intercepting click events while other intercepting events will return a payload.

Take a look at the Intercepting Events app for a demonstration of this feature.

Ticket Details Page APIs

Click Events

Event Name Description
ticket.replyClick When the user clicks on the Reply button to open the editor window.
ticket.sendReply When the user clicks on the Send button to send out a reply.
ticket.forwardClick When the user clicks on the Forward button to open the editor window.
ticket.conversationForward When the user clicks on the Forward icon within the conversation.
ticket.forward When the user clicks on the Forward button inside the editor window. This results in the ticket or conversation actually being forwarded.
ticket.notesClick When the user clicks on the Add Note button to open the editor window.
ticket.addNote When the user clicks on the Add Note option from the editor window. This results in the private or public note actually being added.
ticket.closeTicketClick When the user clicks the CLOSE button that is located in the top navigation bar of the Ticket details page.
ticket.deleteTicketClick When the user clicks the DELETE button that is located in the top navigation bar of the Ticket details page.
ticket.previousTicketClick When the user clicks on the previous ticket icon at the top right of the ticket details page.
ticket.nextTicketClick When the user clicks on the next ticket icon at the top right of the ticket details page.
ticket.startTimer When the user clicks on the start or add timer button.
ticket.stopTimer When the user clicks on the stop timer button.
ticket.updateTimer When the user clicks on the update timer button.
ticket.deleteTimer When the user clicks on the delete time entry button.


Change Events

Event Name Description
ticket.priorityChanged When the user changes the priority of the ticket.
ticket.statusChanged When the user changes the status of the ticket.
ticket.groupChanged When the user changes the group to which the ticket is assigned.
ticket.agentChanged When the user changes the agent to whom the ticket is assigned.
ticket.typeChanged When the user changes the type of the ticket.


Intercept Events

Event Name Description
ticket.closeTicketClick When the user clicks the CLOSE button that is located in the top navigation bar of the Ticket details page.
ticket.deleteTicketClick When the user clicks the DELETE button that is located in the top navigation bar of the Ticket details page.
ticket.propertiesUpdated When the user updates any ticket properties and clicks the UPDATE button in the Ticket details page.


ticket.replyClick - This event is triggered when the user clicks on the Reply button to open the editor window.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.replyClick", eventCallback);

ticket.sendReply - This event is triggered when the user clicks on the Send button to send out a reply.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.sendReply", eventCallback);

ticket.forwardClick - This event is triggered when the user clicks on the Forward button to open the editor window.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.forwardClick", eventCallback);

ticket.conversationForward - This event is triggered when the user clicks on the Forward icon within the conversation.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.conversationForward", eventCallback);

ticket.forward - This event is triggered when the user clicks on the Forward button inside the editor window. This results in the ticket or conversation actually being forwarded.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.forward", eventCallback);

ticket.notesClick - This event is triggered when the user clicks on the Add Note option from the conversations.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.notesClick", eventCallback);

ticket.addNote - This event is triggered when the user clicks on the Add Note option from the conversations.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.addNote", eventCallback);

ticket.closeTicketClick - This event is triggered when the user clicks the CLOSE button that is located in the top navigation bar of the Ticket details page.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.closeTicketClick", eventCallback);

ticket.deleteTicketClick - This event is triggered when the user clicks the DELETE button that is located in the top navigation bar of the Ticket details page.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.deleteticketClick", eventCallback);

ticket.previousTicketClick - This event is triggered when the user clicks on the back icon at the top right of the ticket details page.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.previousTicketClick", eventCallback);

ticket.nextTicketClick - This event is triggered when the user clicks on the forward icon at the top right of the Ticket details page.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.nextTicketClick", eventCallback);

ticket.startTimer - This event is triggered when the user clicks on the start timer button to start the timer. It is also triggered when the user adds time and clicks the save button.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.startTimer", eventCallback);

The helper method event.helper.getData() will return the following JSON. The timer_running attribute specifies if the timer is currently running or not.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "billable":true, "note":"", "id":4, "timer_running":true, "agent_id":1, "ticket_id":2, "company_id":null, "time_spent":0, "executed_at":"2017-12-25T18:30:00Z", "start_time":"2017-12-26T09:41:34Z", "created_at":"2017-12-26T09:41:34Z", "updated_at":"2017-12-26T09:41:34Z" }
EXPAND ↓

ticket.stopTimer - This event is triggered when the user stops a running timer.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.stopTimer", eventCallback);

The helper method event.helper.getData() will return the following JSON.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "billable":true, "note":"", "id":4, "timer_running":false, "agent_id":1, "ticket_id":2, "company_id":null, "time_spent":70, "executed_at":"2017-12-25T18:30:00Z", "start_time":"2017-12-26T09:41:34Z", "created_at":"2017-12-26T09:41:34Z", "updated_at":"2017-12-26T09:41:34Z" }
EXPAND ↓

ticket.updateTimer - This event is triggered when the user updates an existing time entry by clicking the update button.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.updateTimer", eventCallback);

The helper method event.helper.getData() will return the following JSON.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "billable":true, "note":"", "id":4, "timer_running":false, "agent_id":1, "ticket_id":2, "company_id":null, "time_spent":70, "executed_at":"2017-12-25T18:30:00Z", "start_time":"2017-12-26T09:41:34Z", "created_at":"2017-12-26T09:41:34Z", "updated_at":"2017-12-26T09:41:34Z" }
EXPAND ↓

ticket.deleteTimer - This event is triggered when the user deletes an existing time entry.

Copied Copy
1
2
3
4
var eventCallback = function (event) { console.log(event.type + " event occurred"); }; client.events.on("ticket.deleteTimer", eventCallback);

The helper method event.helper.getData() will return the following JSON.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "billable":true, "note":"", "id":4, "timer_running":false, "agent_id":1, "ticket_id":2, "company_id":null, "time_spent":70, "executed_at":"2017-12-25T18:30:00Z", "start_time":"2017-12-26T09:41:34Z", "created_at":"2017-12-26T09:41:34Z", "updated_at":"2017-12-26T09:41:34Z" }
EXPAND ↓

ticket.priorityChanged - This event will be triggered when the user changes the priority of the ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the priority of the ticket is changed. { var event_data = event.helper.getData(); console.log(event.type + " changed from " + event_data.old + " to " + event_data.new); }; client.events.on("ticket.priorityChanged", propertyChangeCallback);

ticket.statusChanged - This event will be triggered when the user changes the status of the ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the status of the ticket is changed. { var event_data = event.helper.getData(); console.log(event.type + " changed from " + event_data.old + " to " + event_data.new); }; client.events.on("ticket.statusChanged", propertyChangeCallback);

ticket.groupChanged - This event will be triggered when the user changes the group assigned to the ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the group of the ticket is changed. { var event_data = event.helper.getData(); console.log(event.type + " changed from " + event_data.old + " to " + event_data.new); }; client.events.on("ticket.groupChanged", propertyChangeCallback);

ticket.agentChanged - This event will be triggered when the user changes the agent assigned to the ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the agent of the ticket is changed. { var event_data = event.helper.getData(); console.log(event.type + " changed from " + event_data.old + " to " + event_data.new); }; client.events.on("ticket.agentChanged", propertyChangeCallback);

ticket.typeChanged - This event will be triggered when the user changes the type of the ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the type of the ticket is changed. { var event_data = event.helper.getData(); console.log(event.type + " changed from " + event_data.old + " to " + event_data.new); }; client.events.on("ticket.typeChanged", propertyChangeCallback);

ticket.closeTicketClick - This intercepting event is triggered when the user clicks the Close button that is located in the top navigation bar of the ticket details page.

Copied Copy
1
2
3
4
5
6
7
8
9
var eventCallback = function (event) { console.log(event.type + " event occurred"); // To allow the original event to continue event.helper.done() // To prevent the original event from completing event.helper.fail(errorMessage) }; client.events.on("ticket.closeTicketClick", eventCallback, {intercept: true});

ticket.deleteTicketClick - This intercepting event is triggered when the user clicks the Delete button that is located in the top navigation bar of the ticket details page.

Copied Copy
1
2
3
4
5
6
7
8
9
var eventCallback = function (event) { console.log(event.type + " event occurred"); // To allow the original event to continue event.helper.done() // To prevent the original event from completing event.helper.fail(errorMessage) }; client.events.on("ticket.deleteTicketClick", eventCallback, {intercept: true});

ticket.propertiesUpdated - This intercepting event is triggered when the user updates any ticket property and clicks the Update button that is located in the ticket details page.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
var eventCallback = function (event) { console.log(event.type + " event occurred"); var event_data = event.helper.getData(); // Sample event_data: { changedAttributes: { status: {old:1, new:2} } } // To allow the original event to continue event.helper.done() // To prevent the original event from completing event.helper.fail(errorMessage) }; client.events.on("ticket.propertiesUpdated", eventCallback, {intercept: true});
EXPAND ↓

New Ticket Page APIs

Change Events

Event Name Description
ticket.priorityChanged When the user changes the priority of the ticket.
ticket.statusChanged When the user changes the status of the ticket.
ticket.groupChanged When the user changes the group to which the ticket is assigned.
ticket.agentChanged When the user changes the agent to whom the ticket is assigned.
ticket.typeChanged When the user changes the type of the ticket.

New Email Page APIs

Change Events

Event Name Description
ticket.priorityChanged When the user changes the priority of the ticket.
ticket.statusChanged When the user changes the status of the ticket.
ticket.groupChanged When the user changes the group to which the ticket is assigned.
ticket.agentChanged When the user changes the agent to whom the ticket is assigned.
ticket.typeChanged When the user changes the type of the ticket.

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.