Freshworks Developer Docs | Use interface methods

Interface-methods is a mechanism that the developer platform provides, to enable your app to trigger certain actions on the Freshchat UI.

Using interface methods an app can, on the Freshchat UI,

Display certain UI elements such as Modals, Dialog boxes, Confirmation boxes, and Notifications.
Show/Hide certain fields, field values, and elements (such as icons or other relevant information).
Enable/Disable certain buttons.
Set or clear the values of certain fields.

Global interfaces

An app can display these interfaces/UI elements on any of the Freshchat pages where the app is deployed.

Display modals or dialog boxes

From your project’s root, navigate to the app directory and create a <modal or dialog or any-reasonable-name>.html file. In this file, enter the code to render the (front-end of the) Modal or Dialog box.
Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
After app initialization, to display a Modal or Dialog box, use the following method:
Sample app.js
```
client.interface.trigger("<method-name>", {
  title: "<Modal name>",
  template: "<path to the modal.html file>"
})
```
<method-name> is showModal or showDialog

The method displays a Modal in an IFrame. Events methods and Interface methods are not supported in a Modal - your app cannot react to click, change, or update events that occur inside a Modal and your app cannot trigger actions on the product UI from the Modal.

Installation parameters, Request method, Data method, and Data storage are supported in modals. If your app uses these methods from modals, in the modal.html file (or in any other equivalent file that you have added), ensure to include the following appclient resource.

<script src="{{{appclient}}}"></script>

Modal with backdrop

Modal without backdrop

Use the sample code shown on the right pane, to enable your app to display a Modal, as part of the app logic.

You can retrieve the contextual information pertaining to the parent location from where a modal is triggered by using Instance method - Context. You can use the Instance methods - Send and Receive to enable communication between modals and any other app instance.

Sample app.js

Modal with backdrop

Modal without backdrop

try {
  let data = client.interface.trigger('showModal', {
  title: 'Sample App Form',
  backdrop: true,
  template: './views/modal.html' });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Notes:

title is optional. Max characters: 30; value is truncated beyond 30. Default value: Modal dialog.

template is mandatory. Specify the path to the HTML file where the code to render the modal’s front-end is present. If no value is specified, an error message is displayed at run time.

backdrop is optional. To display a modal without a backdrop, specify the backdrop attribute value as false. A modal with a backdrop is displayed if no value is specified for the backdrop attribute or if the value is specified as true.
collapseConversationList is optional and only applies to a modal without backdrop. To display a modal without a backdrop in an expanded layout and with a collapsed conversation list pane, set the backdrop attribute to false and collapseConversationList to true. A modal without a backdrop in default size is displayed, if the collapseConversationList is set as false or left unspecified.

showDialog method

The method displays a Dialog box in an IFrame. Events methods and Interface methods are not supported in a Dialog box - your app cannot react to click, change, or update front-end events that occur inside a Dialog box and your app cannot trigger actions on the product UI from the Dialog box.

Installation parameters, Request method, Data method, and Data storage are supported in modals. If your app uses these methods from modals, in the dialog.html file (or in any other equivalent file that you have added), ensure to include the following appclient resource.

<script src="{{{appclient}}}"></script>

Dialog box

Use the sample code shown on the right pane, to enable your app to display a Dialog box, as part of the app logic.

You can retrieve the contextual information pertaining to the parent location from where a Dialog box is triggered by using Instance method - Context. You can use the Instance methods - Send and Receive to enable communication between modals and any other app instance.

Sample app.js

try {
  let data = client.interface.trigger('showDialog', {
  title: 'Sample Dialog',
  template: 'dialog.html' });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Notes:

title is optional. Max characters: 30; value is truncated beyond 30.
template is mandatory. Specify the path to the HTML file where the code to render the Dialog box is present. If no value is specified, an error message is displayed at run time.

Display confirmation messages

To enable your app to display standard confirmation-message boxes,

Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
After app initialization, to display a confirmation message with default buttons, use the following method:

Sample app.js

 client.interface.trigger("showConfirm", {
   title: "<Confirmation box name>",
   message: "<text message to be displayed seeking confirmation>"
 })

showConfirm method

The method displays a confirmation message box with a title, a message, and the save and cancel buttons. By default, the message box displays the SAVE and CANCEL buttons. You can customize the button names.

Time-out information:Timeout for Confirmation message box is 10 seconds.

Use the sample code shown on the right pane > Default buttons tab, to enable your app to display a Confirmation message box (with SAVE and CANCEL buttons), as part of the app logic.

Confirmation message box - Default

Confirmation message box - Custom

Confirmation message box - Default buttons

Sample app.js

Default buttons

Custom buttons

try {
  let result = await client.interface.trigger("showConfirm", {
    message: "Are you sure you want to save the details?" // plain text
  });
  console.log(result);
    /* "result" will be either "Save" or "Cancel" */
} catch (error) {
    // failure operation
  console.error(error);
}

Notes:

message is mandatory. Max characters: 100; value is truncated beyond 100. If no value is specified, an error message is displayed at run time.
saveLabel and cancelLabel are optional. Max characters: 11

Display notifications

To enable your app to display notifications,

Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.

After app initialization, to display a notification, use the following method:

Sample app.js

client.interface.trigger("showNotify", {
  type: “<Possible values: info, success, warning, alert, danger>”,
  message: "<text message to be displayed in the notification box>"
 }
)

showNotify method

The method displays a notification box with a title and notification message (can be which, if ignored, can fail the system).

Use the sample code shown on the right pane, to enable your app to display various notification messages, as part of the app logic.

info

success

warning

danger

alert

Notification box with an info message

Sample app.js

info

success

warning

danger

alert

try {
  let data = await client.interface.trigger("showNotify", {
    type: "info",
    message: "The details have been edited."
    /* The "message" should be plain text */
  });
    console.log(data); // success message
} catch (error) {
    // failure operation
    console.error(error);
}

Notes:

type is mandatory. Possible values: . If an incorrect value is entered or if no value is specified, an error message is displayed at run time.
title is optional. Max characters: 30; value is truncated beyond 30.
message is mandatory. Max characters: 100; value is truncated beyond 100. If no value is specified, an error message is displayed at run time.

Team Inbox page - possible app actions

Hide/display or enable/disable UI elements

TTo enable your app to hide an UI element, display a hidden element, disable an element, or enable an element,

Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
After app initialization, to a hide/display or enable/disable UI element, use the following method:
app.js
```
client.interface.trigger("<method-name>", {
  id: "<element-name>"
})
```
<method-name> is the action to be performed. Possible values: hide, show, enable, disable
<element-name> is the element to be hidden or displayed; disabled or enabled.

Set the value of a field

To enable your app to set the value of a UI field,

Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
After app initialization, use the following method:
app.js
```
client.interface.trigger("setValue", {
  id: "<element-name>",
  value: "<value to be set>"
})
```
<element-name> is the element whose value is to be set.

Clear the value of a field

To enable your app to clear the value of a UI field,

Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
After app initialization, use the following method:
app.js
```
client.interface.trigger("clearValue", {
  id: "<element-name>"
})
```
<element-name> is the element whose value is to be cleared.

UI elements that the app can act on

addAttachment

Use the sample code on the right pane, to hide or display the Attach File icon.

This image highlights the element the app can act on

Sample app.js

Show Attach File icon

Hide Attach File icon

try {
  let data = await client.interface.trigger("show", {
    id: "addAttachment"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

addImage

Use the sample code on the right pane, to hide or display the Add Image icon.

This image highlights the element the app can act on

Sample app.js

Show Add Image icon

Hide Add Image icon

try {
  let data = await client.interface.trigger("show", {
    id: "addImage"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

coBrowse

Use the sample code on the right pane, to show or hide the Co-browse icon.

This image highlights the element the app can act on

Sample app.js

Show Co-browse icon

Hide Co-browse icon

try {
  let data = await client.interface.trigger("show", {
    id: "coBrowse"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

resolveConversation

Use the sample code on the right pane, to disable or enable the Resolve button.

This image highlights the element the app can act on

If the app is deployed on a Freshchat account with the <sub-domain>.myfreshworks.com account URL, on the conversation window, there is an Open drop-down button with Resolve as a menu option. When the enable or disable method acts on the resolveConversation element, the Open button is disabled or enabled.

This image highlights the element the app can act on. App deployed at: <sub-domain>.myfreshworks.com

Sample app.js

Enable Resolve button

Disable Resolve button

try {
  let data = await client.interface.trigger("enable", {
    id: "resolveConversation"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

assignGroup

Use the sample code shown on the right pane, to enable or disable the Add group element from the conversation window. If a group is assigned, the window contains the group’s name in place of the Add group element. In that case, the group’s name is disabled or enabled when the disable or enable method is used on the assignGroup element.

When no group is assigned

When a group is assigned

This image highlights the element the app can act on

Sample app.js

Enable Add group element

Disable Add group element

try {
  let data = await client.interface.trigger("enable", {
    id: "assignGroup"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

assignAgent

Use the sample code shown on the right pane, to enable or disable the Add agent element from the conversation window. If an agent is assigned, the window contains the agent’s name in place of the Add agent element. In that case, the agent’s name is disabled or enabled when the disable or enable method is used on the assignAgent element.

When no agent is assigned

When an agent is assigned

This image highlights the element the app can act on

Sample app.js

Enable Add agent element

Disable Add agent element

try {
  let data = await client.interface.trigger("enable", {
    id: "assignAgent"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

The product UI displays all information pertaining to the contact (user) associated with a conversation in the Contact info widget of the Team Inbox page. The widget is highlighted in the image.

Contact info widget of the Team Inbox page

An app can act on the following elements (fields) of the Contact info widget.

Field (default display) name	Element name to be used in app.js	Method name to be used in app.js
Email	userEmail	show or hide
Phone	userPhoneNumber	show or hide
IP	userIPAddress	show or hide
The location information	userLocation	show or hide
The edit icon (If the app is deployed on a Freshchat account with the <sub-domain>.freshchat.com account URL.)	userEmail, userPhoneNumber, or userIPAddress	enable or disable

This image highlights the location UI element that the app can act on. This image highlights the element the app can act on

This image highlights the edit icon that the app can act on. App deployed at: <sub-domain>.freshchat.com

Use the sample code on the right pane, with the appropriate element name, to hide, display, disable, or enable these fields.

Sample app.js

Show field

Hide field

try {
  let data = await client.interface.trigger("show", {
    id: "<element-name>"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Note:Possible values of <element-name>: userEmail, userPhoneNumber, userIPAddress, userLocation

Enable field

Disable field

try {
  let data = await client.interface.trigger("enable", {
    id: "<element-name>"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Note:Possible values of <element-name>: userEmail, userPhoneNumber, userIPAddress

Note:Valid only for apps deployed on the <sub-domain>.freshchat.com account URLs.

The product UI displays all custom information pertaining to the contact (user) associated with a conversation in the Custom contact properties widget of the Team Inbox page. The widget is highlighted in the image.

Custom contact properties widget of the Team Inbox page

An app can,

Hide or display the Custom contact properties widget.
Enable or disable the provision to add more Custom contact properties.

Widget or button (default display) name	Element name to be used in app.js	Method name to be used in app.js
Custom contact properties	userCustomProperties	show or hide
Add button (If the app is deployed on a Freshchat account with the <sub-domain>.freshchat.com account URL.)e	userCustomProperties	enable or disable

This image highlights the Add button that the app can act on. App deployed at: <sub-domain>.freshchat.com

Use the sample code on the right pane, with the appropriate element name and method name, to hide, display, disable, or enable the Custom contact properties widget and the provision to add more Custom contact properties.

Sample app.js

Show field

Hide field

try {
  let data = await client.interface.trigger("show", {
    id: "userCustomProperties"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Enable field

Disable field

try {
  let data = await client.interface.trigger("enable", {
    id: "userCustomProperties"
  });
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Editor window field

When an agent replies or adds a note to a conversation, the editor is displayed.

This image highlights the Editor window where the app can insert a text or clear an existing text

An app can set a text to be displayed on the editor window, on opening. Use the sample code on the right pane to specify a text insert on the Editor window or clear all text inserts.

Sample app.js

Insert text in Editor

Clear text in Editor

try {
  let data = await client.interface.trigger("setValue", {
    id: "editor",
    value: "Text to be inserted"});
  console.log(data); // success message
} catch (error) {
    // failure operation
  console.error(error);
}

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Use interface methods

Global interfaces

Display modals or dialog boxes

showModal method

showDialog method

Display confirmation messages

showConfirm method

Display notifications

showNotify method

Team Inbox page - possible app actions

Hide/display or enable/disable UI elements

Set the value of a field

Clear the value of a field

UI elements that the app can act on

addAttachment

addImage

coBrowse

resolveConversation

assignGroup

assignAgent

Contact info widget fields

Custom contact properties widget

Editor window field

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Use interface methodsOn this page

Global interfaces

Display modals or dialog boxes

showModal method

showDialog method

Display confirmation messages

showConfirm method

Display notifications

showNotify method

Team Inbox page - possible app actions

Hide/display or enable/disable UI elements

Set the value of a field

Clear the value of a field

UI elements that the app can act on

addAttachment

addImage

coBrowse

resolveConversation

assignGroup

assignAgent

Contact info widget fields

Custom contact properties widget

Editor window field

Use interface methods