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 event from completing.

Event Payload
When the callback method is invoked, an event payload is passed to it. The payload is a JavaScript object which contains a type field and 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
These events occur when a user clicks a button or link on the page. The helper method event.helper.getData() returns an empty JSON for most of these events, the only exception being timer events.

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

Change Events
These events occur when a user changes the value of a ticket property. The event is trigerred even if the value is not submitted. The helper method event.helper.getData() returns 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
These 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 is displayed as an error notification to the user. The helper method event.helper.getData() returns an empty JSON for intercepting click events while other intercepting events 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 a user clicks the Reply button to open the editor window.
ticket.sendReply When a user clicks the Send button to send a reply.
ticket.forwardClick When a user clicks the Forward button to open the editor window.
ticket.conversationForward When a user clicks the Forward icon in the conversation.
ticket.forward When a user clicks the Forward button inside the editor window, the ticket or conversation is forwarded.
ticket.notesClick When a user clicks the Add note button to open the editor window.
ticket.addNote When a user clicks the Add Note option from the editor window, a private or public note is added.
ticket.closeTicketClick When a user clicks the CLOSE button located on the top navigation bar of the Ticket Details page.
ticket.deleteTicketClick When a user clicks the DELETE button located on the top navigation bar of the Ticket Details page.
ticket.previousTicketClick When a user clicks the previous ticket icon at the top right of the Ticket Details page.
ticket.nextTicketClick When a user clicks the next ticket icon at the top right of the Ticket Details page.
ticket.startTimer When a user clicks the Start or Add Timer button.
ticket.stopTimer When a user clicks the Stop Timer button.
ticket.updateTimer When a user clicks the Update Timer button.
ticket.deleteTimer When a user clicks the Delete Time Entry button.

Change Events

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

Intercept Events

Event Name Description
ticket.closeTicketClick When a user clicks the CLOSE button located on the top navigation bar of the Ticket Details page.
ticket.deleteTicketClick When a user clicks the DELETE button located on the top navigation bar of the Ticket Details page.
ticket.propertiesUpdated When a user updates any ticket property and clicks the UPDATE button on the Ticket Details page.

ticket.replyClick - This event is triggered when a user clicks 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 a user clicks the Send button.

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 a user clicks 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 a user clicks the Forward icon in a 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 a user clicks the Forward button in the editor window, the ticket or conversation is 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 a user clicks 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 a user clicks 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 a user clicks the CLOSE button located on 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 a user clicks the DELETE button located on 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 a user clicks 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 a user clicks 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 a user clicks 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() returns 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 a 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() returns 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 a 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() returns 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 a 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() returns 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 is triggered when a user changes the priority of a 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 is triggered when a user changes the status of a 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 is triggered when a user changes the group assigned to a 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 is triggered when a user changes the agent assigned to a 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 is triggered when a user changes the type of a 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 a user clicks the Close button located on 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 a user clicks the Delete button located on 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 a user updates any ticket property and clicks the Update button located on 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 a user changes the priority of a ticket.
ticket.statusChanged When a user changes the status of a ticket.
ticket.groupChanged When a user changes the group to which a ticket is assigned.
ticket.agentChanged When a user changes the agent to whom a ticket is assigned.
ticket.typeChanged When a user changes the type of a ticket.

New Email Page APIs

Change Events

Event Name Description
ticket.priorityChanged When a user changes the priority of a ticket.
ticket.statusChanged When a user changes the status of a ticket.
ticket.groupChanged When a user changes the group to which a ticket is assigned.
ticket.agentChanged When a user changes the agent to whom a ticket is assigned.
ticket.typeChanged When a user changes the type of a 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.