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.

• QuickstartGet introduced to plugin widgets.Read
• ExamplesSee plugin widget examples.Read

JS SDK URL

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

It is hosted on our CDN at: https://assets.crisp.chat/widget/javascripts/sdk.min.js

Available Methods

Set a value

Set widget height

• Description: Set widget / modal height.
• Syntax: $crisp.setHeight(height)
• Parameters:
  • height: the height in pixels (required)

If the value is less than or equal to 350, the widget's height is adjusted accordingly. However, if the value exceeds 350, the widget's height is capped at 350 pixels, and an 'Expand' button will appear at the widget's base. Users can click this button to enlarge the widget to its full height for better visibility.

// Example 1: set height to 300px
$crisp.setHeight(300);

Perform an action

Acquire data

• 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
$crisp.acquireData("conversation");

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: states which controls ("Open in new tab", "Close", "Minimize" and "Move" buttons) are shown bellow the modal (boolean or array, defaults to true)
    • Boolean value: whether to show all controls or to show none
    • Array value: the list of buttons to show
      • Values
        • open
        • close
        • minimize (the move button will be automatically added when the modal is minimized)

// Example 1: show a large modal without controls
$crisp.showModal("https://acme.com/widget/refund-user", "large", false);

// Example 2: show a normal modal with all controls
$crisp.showModal("https://acme.com/widget/refund-user");

// Example 3: show a normal modal with some controls
$crisp.showModal("https://acme.com/widget/refund-user", "normal", ["close", "minimize"]);

Close modal

• Description: Close the currently opened modal.
• Syntax: $crisp.closeModal()

// Example 1: close the currently opened modal
$crisp.closeModal();

Show toast

• Description: Show a toast at the bottom of the Crisp app.
• Syntax: $crisp.showToast(type, message, action)
• Parameters:
  • type: the type of toast (required)
    • Values
      • success
      • info
      • warning
      • error
  • message: the message to display in the toast (required)
  • action: the action to display in the toast (optional)
    • Properties
      • label: the label of the action (required)
      • callback: the callback to execute when the action is clicked (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.");

// Example 3: display a success toast with an action
$crisp.showToast("success", "This user was successfully refunded.", {
  label: "Undo",
  callback: () => {
    // Do something.
  }
});

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

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
  console.log(namespace);
  console.log($crisp.data[namespace]);
};

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
  console.log(payload);
};

Modal is being closed by the user

• 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.
  $crisp.acquireData("conversation");
};