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)

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

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: 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("https://acme.com/widget/refund-user", "large", false);

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

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)
• 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

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");
};