Events Methods

You can use the events methods to enable apps to react to events that occur in the user interface of a page. The events includes button clicks or changes and updates to field values. An app can register event listeners that are invoked when an event occurs. Some events can be intercepted and an 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 event.helper.getData() method returns an empty JSON for most of these events, the only exception being timer events.

Take a look at the Simple Events 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 triggered even if the value is not submitted. The event.helper.getData() method 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 runs. The listener can choose to allow the original event to complete or 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 event.helper.getData() method 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.

Global Method
Font Awesome Icons
cti.triggerDialer

The event is triggered when a user clicks , , or a phone number link that is displayed on any of the following pages of the Freshdesk UI.

  • Ticket Details page > CONTACT DETAILS widget
  • Ticket List page > Contact hover card
  • New ticket page > CONTACT DETAILS widget
  • Contact List page > Contact hover card
  • Contact Details page > Contact header and DETAILS widget

To register the event and its corresponding callback use the following code:

Copied Copy
1
2
3
4
5
var eventCallback = function (event) { var data = event.helper.getData(); // processing logic that uses data }; client.events.on("cti.triggerDialer", eventCallback);

The event.helper.getData() method returns a JSON object that contains the contact’s phone number.

Sample Payload
1
2
3
{ "number": "+12345678900" }

You can pass event.helper.getData().number to a dialer that can be opened by using the show CTI Interface method.

Ticket Details Page
Click Events
Event Name Trigger
ticket.replyClick When a user clicks the Reply button to open the editor window.
ticket.sendReply When a user clicks the Send button.
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 Notes 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 Trigger
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 Trigger
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.sendReply When a user clicks the SEND button on the Ticket Details page.

ticket.replyClick

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The event is triggered when a user clicks the Start Timer button to start the timer. It is also triggered when the user adds a time entry 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 event.helper.getData() method 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

The 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 event.helper.getData() method 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

The 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 event.helper.getData() method 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

The 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 event.helper.getData() method 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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

The 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 ↓
ticket.sendReply

The intercepting event is triggered when a user clicks the Send button on 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.sendReply", eventCallback, {intercept: true});

The event.helper.getData() method returns the following JSON.

1
2
3
4
5
6
7
8
9
10
{ "attachment_ids": [18989], "bcc_emails": ["John@freshdesk.com"], "body": "<div>Lorem ipsum dolor</div>", "cc_emails": ["joe@freshdesk.com"], "from_email":["James@freshdesk.com"], "full_text": "Lorem ipsum dolor", "to_email": ["Jane@freshdesk.com"], "user_id": 5 }
EXPAND ↓
New Ticket Page

Change Events

Event Trigger
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

Change Events

Event Trigger
ticket.fromChanged When a user changes the From address of a ticket.
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.

ticket.fromChanged

The event is triggered when a user changes the From address of a ticket.

Copied Copy
1
2
3
4
5
6
7
var propertyChangeCallback = function (event) // code to be executed when the From address 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.fromChanged", propertyChangeCallback);