Instance API

A single app can be present in multiple locations on the same page. In addition, a location may open up one or more modals. The locations and modals can be thought of as separate instances of the app and can be resized, closed, and communicate with each other. The app framework provides instance APIs to enable these use cases.

Take a look at the Instance API sample app for a demonstration of this feature.

Resizing an Instance
You can manually set the height of an app instance with client.instance.resize(), the maximum height being 700px. This works for modals and dialogs as well.

Copied Copy
1
client.instance.resize({ height: "500px" });

If the instance occupies more space than this, scroll bars appear.

Closing an Instance
You can close modals and dialogs with this API.

Copied Copy
1
client.instance.close();

Communication between Instances

The above use cases can be achieved with the following APIs.

Context

This API is used to fetch information about the current instance. For example, modals contain information about the parent location which triggered them and any data that was passed to them.

parent_location_template.html

Copied Copy
1
2
3
4
5
client.instance.context().then( function(context) { console.log(context); } );

Output

Copied Copy
1
2
3
4
{ instanceId: "1", location: "ticket_requester_info" }

Attribute Description
instanceId Each instance is auto-assigned with an ID.
location The location of the current instance.

modal.html

Copied Copy
1
2
3
4
5
client.instance.context().then( function(context) { console.log(context); } );

Output

Copied Copy
1
2
3
4
5
6
{ instanceId: "4", location: "modal", parentId: "1", modalData: "This ticket is created by Rachel" }

Attribute Description
instanceId Each instance is auto-assigned with an ID.
location The location of the current instance.
parentId ID of the parent instance that triggered the modal.
modalData (optional) This parameter contains data sent from the parent instance. For more information, see showModal.

To know the usage of context API with an example, see Send data from a parent location to a modal.

Get

This API is used to fetch context information of all instances that are active at the time of the get() call. It can be used in conjunction with the send() API to send data to a specific instance.

ticket_sidebar_template.html or modal.html

Copied Copy
1
2
3
4
5
client.instance.get().then( function(data) { console.log(data); } );

Output

Copied Copy
1
2
3
4
5
[ {instanceId: "1", location: "ticket_requester_info"}, {instanceId: "2", location: "ticket_sidebar"}, {instanceId: "4", location: "modal", parentId: "1"} ]

Attribute Description
instanceId Each instance is auto-assigned with an ID.
location The location of the current instance.
parentId ID of the parent instance that triggered the modal.

Send

This API can be used to send data to one or many instances. The receive() API should be used in the destination instance(s) to receive data. The syntax varies according to the scenario as shown below.

  • From one location/modal to one or more locations.

    ticket_sidebar_template.html Copied Copy
    1
    2
    3
    4
    5
    client.instance.send({ message: {name: "James", email: "James@freshdesk.com"}, receiver: ["instanceID1", "instanceID2"] });

    Attribute Description
    message Data that is sent from location/modal. message can be a string, object, or array.
    receiver InstanceId(s) of the receiver locations.

  • From a modal to its parent location.

    modal.html Copied Copy
    1
    2
    3
    4
    client.instance.send({ message: {name: "James", email: "James@freshdesk.com"} });

    Attribute Description
    message Data that is sent from location/modal. message can be a string, object, or array.

The destination instances must be active when data is sent. You can retrieve all active instances using the get() method.

Receive

This API is used to receive data that is sent by another instance of the same app using the send() API. Anytime data is sent to the instance, the callback method will be executed.

ticket_sidebar_template.html or modal.html

Copied Copy
1
2
3
4
5
6
7
client.instance.receive( function(event) { var data = event.helper.getData(); console.log(data); /* data contains {senderId: "1", message: { message: {name: "James", email: "James@freshdesk.com"}} */ } );
data returns the following attributes.
Attribute Description
senderId InstanceId(s) of the sender location/modal.
message Data that is sent from a location/modal. message can be a string, object, or array.
Use Cases

Send data from a parent location to a modal
In this example, when a user enters information (Name and Email) and clicks the Show Modal button, the values are sent to the modal.

First, add an additional parameter data in showModal() so that information is available in the modal.

ticket_sidebar_template.html

Copied Copy
1
2
3
4
5
client.interface.trigger("showModal", { title: "Information Form", template: "modal.html", data: {name: "James", email: "James@freshdesk.com"} });

The data can then be retrieved using the context() API.

modal.html

Copied Copy
1
2
3
4
5
6
7
8
client.instance.context().then( function(context) { console.log("Modal instance API context", context); /* Output: Modal instance API context { instanceId: "4", location: "modal", parentId: "1", modalData: {name: "James", email: "James@freshdesk.com"} }" */ jQuery("#name").val(context.modalData.name); jQuery("#email").val(context.modalData.email); } );

Here, modalData contains data that was passed using showModal.

Send data from a modal to a parent location
Data can be transferred from a modal to its parent location ticket_requester_info using the send() and receive() APIs. In the following example, when a user enters the information (Name and Email) and clicks the Send button in the modal, the user input is populated in ticket_requester_info(parent location).

modal.html

Copied Copy
1
2
3
4
client.instance.send({ message: {name: "James", email: "james.dean@freshdesk.com"} }); /* message can be a string, object, or array */

ticket_requester_template.html

Copied Copy
1
2
3
4
5
6
7
client.instance.receive( function(event) { var data = event.helper.getData(); console.log(data); /* Output: {senderId: "4", message: {name: "James", email: "james.dean@freshdesk.com"}} */ } );

Send data from one location to another location
Data can be transferred from location to another location by using send() and receive() instance APIs. In the following example, when a user enters information (Name and Email) and clicks the Send button in the ticket_requester_info location, the data is passed to the ticket_sidebar location as shown below.

ticket_requester_template.html

Copied Copy
1
2
3
4
5
6
7
8
9
10
client.instance.get( function(data) { console.log(data); /* output: [{ instanceId: "1", location: "ticket_requester_info"},{ instanceId: "2", location: "ticket_sidebar"} ]; */ var sidebarApp = data.find(x => x.location === "ticket_sidebar"); client.instance.send({ message: {name: "James", email: "james.dean@freshdesk.com"}, receiver: sidebarApp.instanceId}); /* 2 - instance ID of the receiver */ } );

ticket_sidebar_template.html

Copied Copy
1
2
3
4
5
6
7
client.instance.receive( function(event) { var data = event.helper.getData(); console.log(data); /* Output: {senderId: "1", message: {name: "James", email: "james.dean@freshdesk.com"}} */ } );

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.