Instance Method

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 methods to enable these use cases.

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 method.

Copied Copy
1
client.instance.close();

Communication Between Instances

  • Send data from a parent location to a modal - When a modal is opened, the location can send data to pre-populate form fields.
  • Send data from a modal to a parent location - When a user fills a form in a modal window, some of this data may need to be returned to the parent.
  • Send data from one location to another location - In the case of an app that is present in two locations on the same page, a button click in one location can be used to trigger an action in the second location.

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

Context

This method 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: "conversation_card" }

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 conversation is initiated 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 Show Modal.
Get

This method 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() method to send data to a specific instance.

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: "conversation_card"}, {instanceId: "2", location: "notification_card"}, {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 method can be used to send data to one or many instances. The receive() method should be used in the destination instance(s) to receive data. The syntax varies according to the following scenario.

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

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

    Attribute Description
    message Data that is sent from a 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@freshworks.com"} });

    Attribute Description
    message Data that is sent from a 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 method is used to receive data that is sent by another instance of the same app using the send() method. Anytime data is sent to the instance, the callback method is executed.

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@freshworks.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.