Plugins | Widgets
Give Feedback

iFrame Widget

Updated on October 4, 2021

With iFrame widgets, you're free to build a web app with the framework of your choice, and craft any feature you want. Because it is web-based, this is an extremely powerful solution to provide rich features straight in the Crisp app. Sky is the limit!

Use Cases

As an example, our Trello and Shopify widgets are iFrame widgets. Behind the scenes, they are both powered by a lightweight Vue.js app. They make use of the widget JS SDK as well.

Example of an iFrame widget

Widget Schema

An iFrame widget is defined as the following (see the full reference):

{
  "version": "1.0",
  "url": "https://acme.com/widget.html"
}
A complete iFrame Widget example is available in the Examples.

Some parameters are passed along the GET request to the iFrame URL:

  • website_id
  • session_id: only if your plugin has at least one website:conversation:* token scope granted
  • token
  • locale

They are automatically added as query parameters, like so:

"https://acme.com/widget.html?session_id=session_4396ad07-53d9-47a7-81ba-3b6278bf5fae&website_id=a63d1c82-809d-4ff0-be7b-9c82b24cfcf3&token=c99e0df2-db6f-4b0c-9505-83fcbb2da627&locale=en"

Sizing

The height of your web page is automatically propagated by the Widget JS SDK. This ensures that the proper sizing is applied to the iFrame embedding your web page.

The maximum height of the iFrame embedding your web app is 300px. If your plugin is taller than 300px, it will be scrollable, like a regular page. The user will also have the possibility to expand it via a button located at the bottom of your widget. By clicking on it, the conversation sidebar will be cleared of its content (ie. the user profile and all the other widgets), and your widget will be the only one remaining: it will be able to fill the whole height of the Crisp app.

An iFrame widget with expand button

If the height of your widget or modal changes after the DOM initialization, you can propagate the new value, by calling the setHeight method:

$crisp.setHeight(document.body.scrollHeight);

Data Access

You can access to Crisp Data from the iFrame widget. In many cases, this can eliminate the need for you to make additional requests to our REST API.

See Data Access for the full list of supported data namespaces and properties.
window.onload = () => {
  // Register data acquired callback
  $crisp.onDataAcquired = (namespace) => {
    console.log(namespace);
    console.log($crisp.data[namespace]);
  }

  // Acquire conversation data
  $crisp.acquireData("conversation");
};

Modals

In addition to the iFrame widget itself, you can open modals from it. A modal is displayed above the Crisp app itself. Controls ("Open in new tab" and "Close" buttons) are available bellow the modal.

Modals can be used in the following situations:

  • To display a warning, alert or confirmation
  • If a process of your widget requires user-submitted information
  • For a long, multi-steps process

To display a modal, simply use the showModal method and provide the URL to open (see more details here):

window.onload = () => {
  function onButtonClick() {
    $crisp.showModal("https://acme.com/modal.html");
  }
};

The exact same parameters as the iFrame widget URL are passed along in the modal URL:

"https://acme.com/modal.html?session_id=session_4396ad07-53d9-47a7-81ba-3b6278bf5fae&website_id=a63d1c82-809d-4ff0-be7b-9c82b24cfcf3&token=c99e0df2-db6f-4b0c-9505-83fcbb2da627&locale=en"
A normal-sized modal with controls

Widget communication

When a modal is opened, it represents a second instance of your web app (the first one being the iFrame widget itself). It is like having two browser tabs open, each with the same website.

Because these two instances are separated from each other, you may feel the need to communicate between the iFrame widget and the opened modal:

  • To keep the local state of the iFrame widget in-sync
  • To provide context from the widget to the modal, once it's opened
  • To back up data when the modal is about to be closed
  • To send user-submitted information from the modal to the widget

Communication can be established using the forwardEvent method (see more details here):

$crisp.forwardEvent("widget", {
  result: {
    title: "A title",
    description: "A description",
    end_date: "Jan 21, 2021, 4:43 PM"
  }
});

Toasts

Toasts are displayed at the bottom of the Crisp app. They share the very same visual aspect as the regular toasts used in the Crisp app.

You can choose to display a toast in order to indicate a success, an information, a warning or an error (see more details here).

A success toast