Interface API

You can use Interface APIs to trigger user interface actions on a page. With these APIs, an app can control the visibility of ticket properties, hide or disable buttons, and show dialog boxes and notifications.

Take a look at the Ticket Background app for a demonstration of this feature.

Global Interface APIs

The following APIs can be used in all locations:

Show Modal - Opens a Modal dialog box in an IFrame to display HTML content to users.

Note: Events API and Interface API are not allowed within the Modal IFrame.

template.html

Copied Copy
1
client.interface.trigger("showModal", {title: "Sample Modal", template: "modal.html"})

To send data from template.html to the modal, add an additional parameter data as shown in the following code.

template.html

Copied Copy
1
client.interface.trigger("showModal", { title: "Sample Modal", template: "modal.html", data: {name: "James", email: "James@freshdesk.com"} })

The data can be retrieved inside the modal by using the context API.

modal.html

Copied Copy
1
2
3
4
5
client.instance.context().then (function(context){ console.log(context); /* Output: { instanceId: "modalinstanceID", location: "location", parentId: "parentinstanceID", modalData: {name: "James", email: "James@freshdesk.com"} } */ });

You can transfer data from the modal back to the parent window (or any other location of the same app) by using the Instance API.

If the app includes features, such as Data API, Request API, Installation Parameters, and Data Storage, you need to include the following Freshclient link within the Modal IFrame.

modal.html

Copied Copy
1
<script src="http://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script>

Show Dialog - Shows a dialog box to a user with title and template.

template.html

Copied Copy
1
2
3
client.interface.trigger("showDialog", {title: "Sample Dialog", template: "dialog.html"}) /*"title" should be plain text.*/ /*"dialog.html" is the "template" within "<yourproject>/app" directory.*/

Show Confirm - Shows a confirmation dialog with title, message, saveLabel, and cancelLabel to users. By default, the dialog shows Save and Cancel buttons, you can use saveLabel and cancelLabel to modify the button labels.

Note: Timeout for confirmation dialog is 15 seconds.

Sample confirmation dialog with default buttons

Copied Copy
1
2
client.interface.trigger("showConfirm", {title: "Sample Confirm", message: "Are you sure you want to close this ticket?"}) /*"title" and "message" should be plain text.*/

Sample confirmation dialog with saveLabel and cancelLabel

Copied Copy
1
2
client.interface.trigger("showConfirm", {title: "Sample Confirm", message: "Do you want to save the changes?", saveLabel: "save", cancelLabel: "ignore"}) /*"title" and "message" should be plain text.*/
EXPAND ↓

Show Notifications - Shows various types of notifications.

  • Success

    Sample notification with message

    Copied Copy
    1
    2
    client.interface.trigger("showNotify", {type: "success", message: "sample notification"}) /* The "message" should be plain text */

    Sample notification with an optional title

    You can add a title to the notification by including the optional title parameter.
    Copied Copy
    1
    2
    client.interface.trigger("showNotify", {type: "success", title: "Success", message: "This is a sample success notification."}}) /* "title" and "message" should be plain text */
  • Info
  • Warning
  • Danger
  • Alert

Navigate to Ticket Details page - Allows users to navigate to the Ticket Details page.

template.html

Copied Copy
1
client.interface.trigger("click", {id: "ticket",value: 1 });

Navigate to Contact Details page - Allows users to navigate to the Contact Details page.

template.html

Copied Copy
1
client.interface.trigger("click", {id: "contact",value: 1 });

Global CTI

The following APIs are available:

Show IFrame - Opens an IFrame to show content to users.

template.html

Copied Copy
1
client.interface.trigger("show", {id: "softphone"});

Hide IFrame - Hides the IFrame.

template.html

Copied Copy
1
client.interface.trigger("hide", {id: "softphone"});

Ticket Details Page APIs

Time Entry Modal
Note: For the following APIs, the app location has to be time_entry_background.

Editor Window APIs

Hide Attachments - Hides attachments in conversations on the Ticket Details page.

Copied Copy
1
client.interface.trigger("hide", {id: "attachments"})

Show Attachments - Shows attachments in conversations.

Copied Copy
1
client.interface.trigger("show", {id: "attachments"})

Hide Attachment Delete Buttons - Hides the Attachment Delete button.

Copied Copy
1
client.interface.trigger("hide", {id: "attachmentsDelete"})

Show Attachment Delete Buttons - Shows the Attachment Delete button.

Copied Copy
1
client.interface.trigger("show", {id: "attachmentsDelete"})

Hide Edit Ticket Option - Allows an app to hide the Edit ticket option on the Ticket Details page.

Copied Copy
1
client.interface.trigger("hide", {id: "ticketEdit"})

Show Edit Ticket Option - Allows an app to show the Edit ticket option on the Ticket Details page.

Copied Copy
1
client.interface.trigger("show", {id: "ticketEdit"})

Enable Edit Ticket Option - Allows an app to enable the Edit ticket option on the Ticket Details page.

Copied Copy
1
client.interface.trigger("enable", {id: "ticketEdit"})

Disable Edit Ticket Option - Allows an app to disable the Edit ticket option on the Ticket Details page.

Copied Copy
1
client.interface.trigger("disable", {id: "ticketEdit"})

Hide Ticket Delete Button - Hides the Ticket delete option on the page.

Copied Copy
1
client.interface.trigger("hide", {id: "ticketDelete"})

Show Ticket Delete Button - Shows the Ticket delete icon on the Ticket Details page.

Copied Copy
1
client.interface.trigger("show", {id: "ticketDelete"})

Disable Ticket Delete Button - Is used to disable the Ticket delete icon on the Ticket Details page.

Copied Copy
1
client.interface.trigger("disable", {id: "ticketDelete"})

Enable Ticket Delete Button - Is used to enable the Ticket delete icon on the Ticket Details page.

Copied Copy
1
client.interface.trigger("enable", {id: "ticketDelete"})

Hide Ticket Property Fields - Hides the selected ticket properties field on the Ticket Details page.

Copied Copy
1
client.interface.trigger ("hide", {id: "element"})

The following table lists all the property fields that can be hidden.

Element Syntax
Status

client.interface.trigger ("hide", {id: "status"})

Priority

client.interface.trigger ("hide", {id: "priority"})

Type

client.interface.trigger ("hide", {id: "ticket_type"})

Group

client.interface.trigger ("hide", {id: "group"})

Product

client.interface.trigger ("hide", {id: "product"})

Custom field

client.interface.trigger ("hide", {id: "customfield"})

Show Ticket Property Fields - Shows the selected ticket property field if hidden.

Copied Copy
1
client.interface.trigger ("show", {id: "element"})

The following table lists all the supported property fields.

Element Syntax
Status

client.interface.trigger ("show", {id: "status"})

Priority

client.interface.trigger ("show", {id: "priority"})

Type

client.interface.trigger ("show", {id: "ticket_type"})

Group

client.interface.trigger ("show", {id: "group"})

Product

client.interface.trigger ("show", {id: "product"})

Custom field

client.interface.trigger ("show", {id: "customfield"})

Set Options - Allows users to display specific values in a drop-down list; all other values will be hidden.

Copied Copy
1
client.interface.trigger ("setOptions", {id: "property", value: [value1, value2]})

Here, property can be a default or custom drop-down field and value should be an array of comma separated values.

The following table lists the fields for which values can be set.

Property Syntax
Status

client.interface.trigger("setOptions", {id: "status", value: [2, 3, 4]})

Priority

client.interface.trigger("setOptions", {id: "priority", value: [3, 4, 5]})

Ticket type

client.interface.trigger("setOptions", {id: "ticket_type", value: ["incident", "problem", "question"]})

Group

client.interface.trigger("setOptions", {id: "group", value: [10, 11, 12]})

Agent

client.interface.trigger("setOptions", {id: "agent", value: [30, 40, 50]})

Product

client.interface.trigger("setOptions", {id: "product", value: [1, 2, 3]})

Custom field

client.interface.trigger("setOptions", {id: "customfield name", value: [3, 4, 5]})

Set Value of Ticket Property Field - Sets the ticket property field with a specified value.

Copied Copy
1
client.interface.trigger("setValue", {id: "property", value: "value"});

The following table lists all the property fields for which values can be set.

Element Syntax
Status

client.interface.trigger("setValue", {id: "status", value: 3})

Priority

client.interface.trigger("setValue", {id: "priority", value: 3})

Ticket

client.interface.trigger("setValue", {id: "ticket_type", value: "Incident"})

Group

client.interface.trigger("setValue", {id: "group", value: 10})

Agent

client.interface.trigger("setValue", {id: "agent", value: 30})

Product

client.interface.trigger("setValue", {id: "product", value: 1})

Custom field

client.interface.trigger("setValue", {id: "customfield name", value: 3})

Disable Ticket Property Fields - Disables the selected ticket property field.

Copied Copy
1
client.interface.trigger("disable", {id: "element"})

The following table lists all the property fields that can be disabled.

Element Syntax
Status

client.interface.trigger ("disable", {id: "status"})

Priority

client.interface.trigger ("disable", {id: "priority"})

Type

client.interface.trigger ("disable", {id: "ticket_type"})

Group

client.interface.trigger ("disable", {id: "group"})

Product

client.interface.trigger ("disable", {id: "product"})

Custom field

client.interface.trigger ("disable", {id: "customfield"})

When you disable the status property, users will not be able to edit the field.

Enable Ticket Property Fields - Enables the selected ticket property field so you can edit its value.

The following table lists all the supported property fields.

Element Syntax
Status

client.interface.trigger ("enable", {id: "status"})

Priority

client.interface.trigger ("enable", {id: "priority"})

Type

client.interface.trigger ("enable", {id: "ticket_type"})

Group

client.interface.trigger ("enable", {id: "group"})

Product

client.interface.trigger ("enable", {id: "product"})

Custom field

client.interface.trigger ("enable", {id: "customfield name"})

Hide Ticket Due By Link - Is used to hide the Edit link to prevent any updates to the existing value.

Copied Copy
1
client.interface.trigger("hide", {id: "ticketDueBy"})

Show Ticket Due By Link - Shows the Edit link to allow updates to the existing value.

Copied Copy
1
client.interface.trigger("show", {id: "ticketDueBy"})

Start Timer - Is used to start a timer.

Copied Copy
1
client.interface.trigger("start", {id: "timer", value: {agent: user_id, billable: true, note: "text"}});

Stop Timer - Is used to stop a running timer.

Copied Copy
1
client.interface.trigger("stop", {id: "timer"})

Expand Conversation - When the number of notes and replies in a ticket exceeds a certain limit, the older ones are collapsed and only the most recent ones are shown. This API enables you to expand and view all of them.

Copied Copy
1
client.interface.trigger("click", {id: "expandConversation"})

Open Reply and Insert Text - Opens the Reply editor and replaces the existing text with the specified text. Using this API also invokes any callback function if specified by using the ticket.replyClick API.

Copied Copy
1
client.interface.trigger("click", {id: "reply", text: "Text to be inserted"})

Open Note and Insert Text - Opens the Note editor and replaces the existing text with the specified text. Using this API also invokes any callback function if specified using the ticket.notesClick API.

Copied Copy
1
client.interface.trigger("click", {id: "note", text: "Text to be inserted", isPublic: true})

Insert into Editor Window - Is used to insert text and attachments in an already open conversation editor window. It works for notes, replies, and forwards. It does require that the window is already open and is therefore recommended only for apps in the "ticket_conversation_editor" location.

Copied Copy
1
2
3
client.interface.trigger( "setValue", {id: "editor", text: "Text to be inserted", attachments: [attachment ID1, attachment ID2...]})

By default, the text is appended at the current cursor position. The optional parameter replace that accepts a value of true or false can be used to either replace the existing content or to add to it. The optional parameter position that accepts a value of start or end can be used to decide if the text is to be added to the start or end of the existing content. By default, this value is set to start.

Copied Copy
1
client.interface.trigger("setValue", {id: "editor", text: "Text to be inserted", replace: false, position: "end"})

Show To - Shows the To field in the reply editor.

Copied Copy
1
client.interface.trigger("show", {id: "to"})

Hide To - Is used to hide the To field in the reply editor.

Copied Copy
1
client.interface.trigger("hide", {id: "to"})

Show From - Is used to show the From field in the reply editor.

Copied Copy
1
client.interface.trigger("show", {id: "from"})

Hide From - Is used to hide the From field in the reply editor.

Copied Copy
1
client.interface.trigger("hide", {id: "from"})

Show CC - Is used to show the cc field in the reply editor.

Copied Copy
1
client.interface.trigger("show", {id: "cc"})

Hide CC - Is used to hide the cc field in the reply editor.

Copied Copy
1
client.interface.trigger("hide", {id: "cc"})

Show BCC - Is used to show the bcc field in the reply editor.

Copied Copy
1
client.interface.trigger("show", {id: "bcc"})

Hide BCC - Is used to hide the bcc field in the reply editor.

Copied Copy
1
client.interface.trigger("hide", {id: "bcc"})

Show Note Button - Shows the note option in all locations such as Ticket top navigation and bottom conversation bars.

Copied Copy
1
client.interface.trigger("show", {id: "note"})

Hide Note Button - Hides the note option in all the locations such as Ticket top navigation and bottom coversation bars.

Copied Copy
1
client.interface.trigger("hide", {id: "note"})

Show Reply Button - Shows the reply option in all locations such as Ticket top navigation and bottom conversation bars.

Copied Copy
1
client.interface.trigger("show", {id: "reply"})

Hide Reply Button - Hides the reply option in all the locations such as Ticket top navigation and bottom coversation bars.

Copied Copy
1
client.interface.trigger("hide", {id: "reply"})

Show Forward Button - Shows the forward option in all locations such as Ticket top navigation and bottom conversation bars.

Copied Copy
1
client.interface.trigger("show", {id: "forward"})

Hide Forward Button - Hides the forward option in all the locations such as Ticket top navigation and bottom coversation bars.

Copied Copy
1
client.interface.trigger("hide", {id: "forward"})

Disable To - Is used to disable the To field in the reply editor to prevent any updates to the existing value.

Copied Copy
1
client.interface.trigger("disable", {id: "to"})

Enable To - Is used to enable the To field in the reply editor.

Copied Copy
1
client.interface.trigger("enable", {id: "to"})

Disable From - Disables the From field in the reply editor to prevent any updates to the existing value.

Copied Copy
1
client.interface.trigger("disable", {id: "from"})

Enable From - Enables the From field in the reply editor.

Copied Copy
1
client.interface.trigger("enable", {id: "from"})

Disable CC - Disables the cc field in the reply editor to prevent any updates to the existing value.

Copied Copy
1
client.interface.trigger("disable", {id: "cc"})

Enable CC - Enables the cc field in the reply editor.

Copied Copy
1
client.interface.trigger("enable", {id: "cc"})

Disable BCC -Disables the bcc field in the reply editor to prevent any updates to the existing value.

Copied Copy
1
client.interface.trigger("disable", {id: "bcc"})

Enable BCC - Enable the bcc field in the reply editor.

Copied Copy
1
client.interface.trigger("enable", {id: "bcc"})

Disable Note Button - Disables the note option in the top navigation bar and hides the note option in the bottom conversation bar.

Copied Copy
1
client.interface.trigger("disable", {id: "note"})

Enable Note Button - Enables the note option in the top navigation and bottom conversation bars.

Copied Copy
1
client.interface.trigger("enable", {id: "note"})

Set Value of Editor Window Fields - Sets the editor window field (To, From, CC, BCC) with the specified value.

Copied Copy
1
2
3
client.interface.trigger("setValue", {id: "property", value: ["value"]}); // For multiple values client.interface.trigger("setValue", {id: "property", value: ["value_1", "value_2"..]});

The following table lists all the fields for which values can be set.

Element Syntax
To

client.interface.trigger("setValue", {id: "to", value: ["tom@customer.com"]})

From

client.interface.trigger("setValue", {id: "from", value: "rachel@freshdesk.com"})

CC

client.interface.trigger("setValue", {id: "cc", value: ["rachel@freshdesk.com"]})

BCC

client.interface.trigger("setValue", {id: "bcc", value: ["rachel@freshdesk.com"]})

Set Note type - Enables you to set the note type to either private or public.

Copied Copy
1
client.interface.trigger("setValue", {id: "noteType", value: "value"})
Sample Copied Copy
1
client.interface.trigger("setValue", {id: "noteType", value: "private"})

Remove Quoted Text in Ticket Reply Editor - Allows an app to remove quoted text when you click the Reply button on the Ticket Details page.

Copied Copy
1
client.interface.trigger("click", {id: "deleteQuotedText"})

Hide - Is used to hide the following fields.

  • timerBillable
  • timerAgentId
  • timerNote
  • timerSetTime
  • timerExecuteAt

Copied Copy
1
client.interface.trigger("hide", {id: "element"})

In the given code, "element" can be replaced with the above listed fields.

Show - Shows the following fields.

  • timerBillable
  • timerAgentId
  • timerNote
  • timerSetTime
  • timerExecuteAt

Copied Copy
1
client.interface.trigger("show", {id: "element"})

In the given code, "element" can be replaced with the above listed fields.

Enable - Is used to enable the following fields.

  • timerBillable
  • timerAgentId
  • timerNote
  • timerSetTime
  • timerExecuteAt

Copied Copy
1
client.interface.trigger("enable", {id: "element"})

In the given code, "element" can be replaced with the above listed fields.

Disable - Is used to disable the following fields.

  • timerBillable
  • timerAgentId
  • timerNote
  • timerSetTime
  • timerExecuteAt

Copied Copy
1
client.interface.trigger("disable", {id: "element"})

In the given code, "element" can be replaced with the above listed fields.

Set Value - Sets the fields (timerBillable, timerAgentId, timerNote, timerSetTime) with a specified value.

Copied Copy
1
client.interface.trigger("setValue", {id: "property", value: "value"});

In the given code, "property" can be replaced with the above fields.

  • timerBillable - value can be either true or false.
  • client.interface.trigger("setValue", {id: "timerBillable", value: false})
  • timerAgentId - value is an integer and should be the agent's user_id.
  • client.interface.trigger("setValue", {id: "timerAgentId", value: 147})
  • timerNote - value is a string.
  • client.interface.trigger("setValue", {id: "timerNote", value: "time sheet value"})
  • timerSetTime - value is a string (ie.) "1" or "1:30" or "1.5".
  • client.interface.trigger("setValue", {id: "timerSetTime", value: "1:15"})
  • timerExecuteAt - value is in date format "DD/MMM/YYYY" or "DD-MMM-YYYY".
  • client.interface.trigger("setValue", {id: "timerExecuteAt", value: "24/june/2018"})

    Note:
    If the timerSetTime field is blank, the timerExecutedAt field is set to the current date even if an app tries to set a value for the same.

Contact Details Page

Hide Contact Edit Button/Fields - Hides the Contact Edit button or any particular field on the Contact Details page.

Copied Copy
1
client.interface.trigger("hide", {id: "element"})

The following table lists the supported button/fields.

Button/Field Name Syntax
Edit Button

client.interface.trigger ("hide", {id: "contactEdit"})

Tags

client.interface.trigger ("hide", {id: "tag"})

Mobile Phone

client.interface.trigger ("hide", {id: "mobile"})

Address

client.interface.trigger ("hide", {id: "address"})

Work Phone

client.interface.trigger ("hide", {id: "phone"})

Twitter ID

client.interface.trigger ("hide", {id: "twitter_id"})

Language

client.interface.trigger ("hide", {id: "language"})

About

client.interface.trigger ("hide", {id: "description"})

Any Custom Fields

client.interface.trigger ("hide", {id: "zip_code"})

Note: If the field name has multiple words (zip code), replace the space in the field name with an underscore in the ID label (zip_code).

Show Contact Edit Button/Fields - Shows the Contact Edit button or any particular field on the Contact Details page. See the above table for the list of buttons/fields that can be displayed.

Copied Copy
1
client.interface.trigger("show", {id: "element"})
Contact List Page

Hide Contact Edit Button - Hides the Contact Edit button on the Contact List page.

Copied Copy
1
client.interface.trigger("hide", {id: "contactEdit"})

Show Contact Edit Button - Shows the Contact Edit button on the Contact List page.

Copied Copy
1
client.interface.trigger("show", {id: "contactEdit"})

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.