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.
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
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
- Values
// 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 tonormal
)- Values
normal
medium
large
wide
- Values
controls
: whether to show controls ("Open in new tab" and "Close" buttons) bellow the modal or not (defaults totrue
)
// 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
- Values
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
- Values
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, withnamespace
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, withpayload
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");
};