DOM Helper API

DOM Helper is a Javascript API library that serves as an abstraction layer between the apps you build and the Freshdesk page. It ensures that your apps work even if the selectors or page structure is altered. A global variable called domHelper is exposed in the ticket detail page and contact page. It can be used to get information about objects in the page and to manipulate UI elements in the page. For apps that are meant to be shared on the Marketplace, it is required to use DOMhelper to perform the aforementioned operations.


Note: The DOMHelper APIs cannot be used define the placement or display of your app. You’ll need to use the Placeholder APIs for that.


Global Data APIs

The following DOM Helper Data APIs can be used on both the ticket and contact details page:

getAgentEmail() - This API returns the email of the logged in agent.

domHelper.getAgentEmail();

getDomainName() - This API returns the domain name of the current account. Freshdesk v2 APIs do not support custom CNAMEs. Hence to make API calls, it is highly recommended to use this method to obtain the Freshdesk domain name.

domHelper.getDomainName();
Ticket Details Page Data APIs

The DOM Helper Data APIs for the ticket details page are:

getTicketInfo() - This API returns the helpdesk_ticket object with the following attributes:

ATTRIBUTE TYPE DESCRIPTION
cc_email dictionary Key value pairs containing the list of email addresses that are copied on to replies and to forwards
cc_emails array of strings Email address(es) added in the 'cc' field of the incoming ticket email
created_at datetime Ticket creation timestamp
custom_field dictionary Key value pairs containing the names and values of custom fields. Read more here
deleted boolean Set to true if the ticket has been deleted/trashed. Deleted tickets will not be displayed in any views except the "deleted" filter
description string Content of the ticket in plain text
description_html string Content of the ticket in HTML
display_id number Ticket ID
due_by datetime Timestamp that denotes when the ticket is due to be resolved
email_config_id number ID of email config which is used for this ticket.(i.e., support@yourcompany.com/sales@yourcompany.com)
frDueBy datetime Timestamp that denotes when the first response is due
isescalated boolean Set to true if the ticket has been escalated as the result of first response time being breached
fwd_emails array of strings Email address(es) added while forwarding a ticket
group_id number ID of the group to which the ticket has been assigned
id number Unique ID of the ticket
is_escalated boolean Set to true if the ticket has been escalated for any reason
owner_id number ID of the company of the ticket requester
priority number Priority of the ticket
priority_name string Priority of the ticket in text
product_id number ID of the product to which the ticket is associated
requester_id number User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email
requester_name string Name of the Requester
responder_id number ID of the agent to whom the ticket has been assigned
reply_cc array of strings Email address(es) added while replying to a ticket
responder_name string Name of the agent to whom the ticket has been assigned
source number The channel through which the ticket was created
source_name string The channel through which the ticket was created in plain text
spam boolean Set to true if the ticket has been marked as spam
status number Status of the ticket
status_name string Status of the ticket in text
subject string Subject of the ticket
tag_list string Returns list of tags for a ticket
to_email string Email address to which the ticket was originally sent
to_emails Array of strings Email addresses to which the ticket was originally sent
ticket_type string Helps categorize the ticket according to the different kinds of issues your support team deals with.
updated_at datetime Ticket updated timestamp
urgent boolean Is ticket priority “urgent”?

Syntax domHelper.ticket.getTicketInfo();
Sample Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{ "helpdesk_ticket" : { "cc_email" : { "Fwd_emails" : ["saul@freshdesk.com" , "diana@freshdesk.com"], "Reply_cc" : ["saul@freshdesk.com" , "diana@freshdesk.com"], "Tkt_cc" : [ ] }, "created_at" : "2016-02-03T07:00:55-05:00", "deleted" : false, "delta" : true, "description" : "This is a sample ticket", "description_html" : "<div>sample ticket</div>", "display_id" : 1, "due_by" : "2016-02-04T07:00:55-05:00", "email_config_id" : 2345, "frDueBy" : "2016-02-03T15:00:55-05:00", "fr_escalated" : true, "group_id" : 9000131702, "id" : 9002391542, "isescalated" : true, "owner_id" : 45677, "priority" : 2, "requester_id" : 9006811381, "responder_id" : 23422, "source" : 1, "spam" : false, "status" : 3, "subject" : "Support", "ticket_type" : "Feature Request", "to_email" : "sample@freshdesk.com", "trained" : false, "updated_at" : "2016-12-15T02:29:03-05:00", "urgent" : false, "status_name" : "Pending", "requester_status_name" : "Awaiting your Reply", "priority_name" : "Medium", "source_name" : "Email", "requester_name" : "Rachel", "responder_name" : "No Agent", "to_emails" : ["sam@freshdesk.com", "saul@freshdesk.com"], "product_id" : 4, "custom_field" : { "department" : "sales" }, "tag_list" : "support, help" } }
EXPAND ↓

getContactInfo() - This API returns the user object with the following attributes:

ATTRIBUTE TYPE DESCRIPTION
active boolean Set to true if the contact has been verified
address string Address of the contact
created_at datetime Contact creation timestamp
custom_field dictionary Key value pair containing the name and value of the custom fields. Read more here
customer_id number ID of the company to which the contact belongs.
deleted boolean Set to true if the contact has been deleted
description string A short description of the contact
email string Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute
external_id number ID of the contact in an external system
fb_profile_id string Facebook profile of the contact
helpdesk_agent boolean Is the contact an agent or not?
id number ID of the contact
job_title string Job title of the contact
language string Language of the contact
mobile number Mobile number of the contact
name string Name of the contact
phone number Telephone number of the contact
time_zone string Time zone in which the contact resides
twitter_id string Twitter handle of the contact
updated_at datetime Contact updated timestamp

Syntax domHelper.ticket.getContactInfo();
Sample Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{ "user" : { "active" : false, "address" : "Baker street, London.", "created_at" : "2016-09-19T01:40:03-04:00", "customer_id" : 600, "deleted" : false, "description" : "Jerry is a seller", "email" : "jerry@freshdesk.com", "external_id" : 21, "fb_profile_id" : 2343, "helpdesk_agent" : false, "id" : 9011947510, "job_title" : "Seller", "language" : "en", "mobile" : "292903902934", "name" : "Jerry", "phone" : "2039480293", "time_zone" : "Eastern Time (US & Canada)", "twitter_id" : 2342342, "unique_external_id" : null, "updated_at" : "2016-09-19T01:40:03-04:00", "custom_field" : { "cf_skype" : "jerry123" } } }
EXPAND ↓

getCustomField() - Depending on the fields the portal Admin has configured, this command will return custom field JSONs
domHelper.ticket.getCustomField();


Ticket Details Page Interface APIs

The DOM Helper Interface APIs for the ticket details page are:

expandConversations() - If there are more than 3 conversations, they are collapsed in the ticket detail page. This API can be used to expand them and display all the conversations. domHelper.ticket.expandConversations();


hideAttachments() - This API hides the attachments in the conversations in the ticket detail page. If the attachments in the collapsed conversation also needs to be hidden, ensure expandConversations API is called before this API and enough timer is also set before calling hideAttachments. domHelper.ticket.hideAttachments();


showAttachments() - This API is used to display the attachments in the conversations if hidden. domHelper.ticket.showAttachments();


hideTicketDelete() - This API hides the ticket delete option in the More menu of the ticket detail page domHelper.ticket.hideTicketDelete();


showTicketDelete() - This API is used to display the ticket delete option in the More menu of the ticket detail page if hidden. domHelper.ticket.showTicketDelete();


openReply(text) - This API is used to open the Reply box and add the text in the textbox. Using this API will also invoke any callback function if specified using onReplyClick API domHelper.ticket.openReply("Text to be added in the reply textbox after opening");


openNote(text) - This API is used to open the Note box and add the text in the textbox. Using this API will also invoke any callback function if specified using the onAddNoteClick API domHelper.ticket.openNote("Text to be added in the note textbox after opening");


domHelper.showConfirm(event, title, message_to_display, ok_label, cancel_label, ok_callback, cancel_callback) - This API is used to display the Confirm dialog box to the user with the message_to_display, ok_label text and cancel_label text. The ok_callback / cancel_callback is executed based on the user's action on the ok / cancel option.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
(function() { return { initialize: function() { domHelper.ticket.onSubmitClick(this.submitClicked.bind(this), ['reply']); }, submitClicked: function(event) { //In this sample, the showConfirm dialog box is invoked when the submit button is clicked. domHelper.showConfirm(event, "Title of the confirm dialog", "Are you sure you want to proceed", "Yes", "No", this.ok_callback.bind(this), this.cancel_callback.bind(this)); }, ok_callback: function() { // code to execute when user clicks on Yes }, cancel_callback: function() { // code to execute when user clicks on No } } })();
EXPAND ↓

domHelper.showModal(event, title, message_to_display, ok_label, ok_callback) - This API is used to display the Modal dialog box to the user with the message_to_display and ok_label text. The ok_callback is executed based on the user's action on the ok option.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
(function() { return { initialize: function() { domHelper.ticket.onSubmitClick(this.submitClicked.bind(this), ['reply']); }, submitClicked: function(event) { //In this sample, the showModal dialog box is invoked when the submit button is clicked. domHelper.showModal(event, "Title of the modal dialog", "You are submitting the reply", "Ok", this.ok_callback.bind(this)); }, ok_callback: function() { // code to execute when user clicks on Ok } } })();
EXPAND ↓

show_growl_flash("message") - This API enables you to display flash messages in both the ticket and contact details page.

Copied
1
2
3
show_growl_flash("message"); /*"message" refers to the text that will be displayed. */ /*"message" can either be a plain text or html formatted text.*/

Sample with plain text:

Copied Copy
1
show_growl_flash("Hello World");

Sample with HTML text:

Copied Copy
1
show_growl_flash("<b><i>File could not be saved</i></b>");

New Ticket Page Interface APIs

The DOM Helper Interface APIs for the new ticket page are:

setRequester(text) - This API is used to update the ticket requester email with the corresponding parameter text as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_ticket.setRequester("sample@freshdesk.com") }, } })();

setPriority(number) - This API is used to update the ticket priority with the corresponding value number as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_ticket.setPriority(1); }, } })();

setStatus(number) - This API is used to update the ticket status with the corresponding value number as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_ticket.setStatus(5); }, } })();

disableRequesterField() - This API is used to disable the ticket requester field in the new ticket page.

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_ticket.disableRequesterField(); }, } })();
New Email Page Interface APIs

The DOM Helper Interface APIs for the new email page are:

setRequester(text) - This API is used to update the ticket requester email with the corresponding parameter(text) as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_email.setRequester("sample@freshdesk.com") }, } })();

setPriority(number) - This API is used to update the ticket priority with the corresponding value (number) as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_email.setPriority(1); }, } })();

setStatus(number) - This API is used to update the ticket status with the corresponding value (number) as shown in the sample below:

Copied Copy
1
2
3
4
5
6
7
8
(function() { return { initialize: function() { //app code domHelper.new_email.setStatus(5); }, } })();

setFromEmail(text) - This API is used to update the From email with the corresponding parameter (text). You will need to ensure that the From email should be one of the configured support emails. For information on support email configuration, see the Adding multiple email addresses to Freshdesk article.

Copied Copy
1
2
3
4
5
6
7
8
9
(function() { return { initialize: function() { //app code domHelper.new_email.setFromEmail("sample@freshdesk.com"); }, } })();

disableFromEmail() - This API is used to disable the From option.

Copied Copy
1
2
3
4
5
6
7
8
9
(function() { return { initialize: function() { //app code domHelper.new_email.disableFromEmail(); }, } })();

enableFromEmail( ) - This API is used to enable the From option.

Copied Copy
1
2
3
4
5
6
7
8
9
(function() { return { initialize: function() { //app code domHelper.new_email.enableFromEmail(); }, } })();

Contact Details Page Data APIs

The DOMHelper Data APIs for the contact details page are

getContactInfo() - This API returns the user object with the following attributes:

ATTRIBUTE TYPE DESCRIPTION
active boolean Set to true if the contact has been verified
address string Address of the contact
created_at datetime Contact creation timestamp
custom_field dictionary Key value pair containing the name and value of the custom fields. Read more here
customer_id number ID of the company to which the contact belongs.
deleted boolean Set to true if the contact has been deleted
description string A short description of the contact
email string Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute
external_id number ID of the contact in an external system
fb_profile_id string Facebook profile of the contact
helpdesk_agent boolean Is the contact an agent or not?
id number ID of the contact
job_title string Job title of the contact
language string Language of the contact
mobile number Mobile number of the contact
name string Name of the contact
phone number Telephone number of the contact
time_zone string Time zone in which the contact resides
twitter_id string Twitter handle of the contact
updated_at datetime Contact updated timestamp

Syntax domHelper.contact.getContactInfo();
Sample Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{ "user" : { "active" : false, "address" : "Baker street, London.", "created_at" : "2016-09-19T01:40:03-04:00", "customer_id" : 600, "deleted" : false, "description" : "Jerry is a seller", "email" : "jerry@freshdesk.com", "external_id" : 21, "fb_profile_id" : 2343, "helpdesk_agent" : false, "id" : 9011947510, "job_title" : "Seller", "language" : "en", "mobile" : "292903902934", "name" : "Jerry", "phone" : "2039480293", "time_zone" : "Eastern Time (US & Canada)", "twitter_id" : 2342342, "unique_external_id" : null, "updated_at" : "2016-09-19T01:40:03-04:00", "custom_field" : { "cf_skype" : "jerry123" } } }
EXPAND ↓

getCustomField() - Depending on the fields the portal Admin has configured, this command will return custom field JSONs

domHelper.contact.getCustomField();
Error Handling

In case of errors during API calls, the console log will display the list of errors along with links to the documentation of the API to make it easy for you to identify and fix the issue. On expanding the error log, you can click on .initialize in the stack trace to find the line of code where there is an error. Errors shown can be classified into the following types:

  • Missing parameters
  • Invalid callbacks
  • Invalid parameters
  • Invalid arguments passed (for certain APIs)

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.