Plugins | Widgets
Give Feedback

Widget JS SDK

Updated on October 4, 2021

The Widget JS SDK lets you control your iFrame widget from your JavaScript code, via $crisp ("dollar-crisp"). This lets you access to data of the current conversation, as well as open modals, show toasts, and do other fancy stuff with the widget. This guide helps you use this SDK from your code.

To another extent, the Widget JS SDK can also be used in modals opened from a Generic widget.


To begin, you must include the Widget JS SDK in your iFrame widget.

It is hosted on our CDN at:

Available Methods

Set a value

Set widget height

  • Description: Set widget / modal height.
  • Syntax: $crisp.setHeight(height)
  • Parameters:
    • height: the height in pixels (required)
// Example 1: set height to 800px

Perform an action

Acquire data

Make sure you have registered the onDataAcquired handler first (see Register a callback on event).
  • Description: Acquires data from the Crisp app.
  • Syntax: $crisp.acquireData(namespace)
  • Parameters:
    • namespace (required)
      • Values
        • conversation
        • operator
        • operators
        • plugin_settings
// Example 1: request conversation data

Show modal

  • Description: Display a modal / popup above the Crisp app itself.
  • Syntax: $crisp.showModal(url, size, controls)
  • Parameters:
    • url: the URL of the webpage to display in the modal (required)
    • size: the size of the modal (defaults to normal)
      • Values
        • normal
        • medium
        • large
        • wide
    • controls: whether to show controls ("Open in new tab" and "Close" buttons) bellow the modal or not (defaults to true)
// Example 1: show a large modal without controls
$crisp.showModal("", "large", false);

// Example 2: show a normal modal with controls

Close modal

  • Description: Close the currently opened modal.
  • Syntax: $crisp.closeModal()
// Example 1: close the currently opened modal

Show toast

  • Description: Show a toast at the bottom of the Crisp app.
  • Syntax: $crisp.showToast(type, message)
  • Parameters:
    • type: the type of toast (required)
      • Values
        • success
        • info
        • warning
        • error
    • message: the message to display in the toast (required)
// Example 1: display a success toast
$crisp.showToast("success", "This user was successfully refunded.");

// Example 2: display an error toast
$crisp.showToast("error", "You can't refund this user.");

Forward event

  • Description: Forward an arbitrary event from the widget to the currently opened modal, or vice versa.
  • Syntax: $crisp.forwardEvent(target, event)
  • Parameters:
    • target: the target of the event (required)
      • Values
        • widget
        • modal
    • event: the event payload (required)
// Example 1: forward an event from the currently opened modal to the widget
$crisp.forwardEvent("widget", {
  // Your event payload

Register a callback on event

Note that to unregister a callback that was previously set, simply set it to null. For instance: $crisp.onDataAcquired = null.

Data was acquired

  • Description: Handles the data acquired event, ie. when data was acquired (triggers your callback function, with namespace as first argument).
  • Syntax: $crisp.onDataAcquired = callback
$crisp.onDataAcquired = (namespace) => {
  // Data was acquired

Event was forwarded

  • Description: Handles the event forwarded event, ie. when an event was forwarded from the widget to the modal, or vice versa (triggers your callback function, with payload as first argument).
  • Syntax: $crisp.onEventForwarded = callback
$crisp.onEventForwarded = (payload) => {
  // Event was received
  • Description: Handles the modal close event, ie. when the user closes the modal via the controls (triggers your callback function).
  • Syntax: $crisp.onModalClose = callback
$crisp.onModalClose = () => {
  // Modal is being closed

Use $crisp once it's ready

You can use the window.CRISP_READY_TRIGGER register as such:

// This callback gets executed once $crisp is fully loaded and all methods are available
window.CRISP_READY_TRIGGER = function() {
  // Do something.