$crisp lets you control Crisp from your JavaScript code. This lets you listen to Crisp events, as well as open, close the chatbox or do fancy stuff with the chatbox.

This section helps you use $crisp from your code.

Available Namespaces

Here's the list of supported action:

Check a boolean value

Warning: the $crisp.is() method is not async-safe. Do not use it before Crisp is fully loaded (see 'Use $crisp Before It Is Ready').

chat:opened - $crisp.is("chat:opened") - Returns true if the chatbox is opened, else false
chat:closed - $crisp.is("chat:closed") - Returns true if the chatbox is closed, else false
chat:visible - $crisp.is("chat:visible") - Returns true if the chatbox is visible, else false
chat:hidden - $crisp.is("chat:hidden") - Returns true if the chatbox is hidden, else false
chat:small - $crisp.is("chat:small") - Returns true if the chatbox is small, else false
chat:large - $crisp.is("chat:large") - Returns true if the chatbox is large, else false
session:ongoing - $crisp.is("session:ongoing") - Returns true if a session is ongoing (ie. messages have been received or sent), else false
website:available - $crisp.is("website:available") - Returns true if the website support is online, else false if away

Get a string or number value

Warning: the $crisp.is() method is not async-safe. Do not use it before Crisp is fully loaded (see 'Use $crisp Before It Is Ready').

chat:unread:count - $crisp.get("chat:unread:count") - Returns the number of unread messages in chat
message:text - $crisp.get("message:text") - Returns the current message text entered in the chatbox but not yet sent
session:identifier - $crisp.get("session:identifier") - Returns the current session identifier (or null if not yet loaded)
session:data - $crisp.get("session:data", key) - Returns the current session data (all data if key is null, or data for given key)
Example 1: Get a saved session data key with $crisp.get("session:data", "user-bill-amount")
user:email - $crisp.get("user:email") - Returns the user email (or null if not set)
user:phone - $crisp.get("user:phone") - Returns the user phone (or null if not set)
user:nickname - $crisp.get("user:nickname") - Returns the user nickname (or null if not set)
user:avatar - $crisp.get("user:avatar") - Returns the user avatar (or null if not set)

Set a value

message:text - $crisp.push(["set", "message:text", [message_text]]) - Pre-fill the current message text in the chatbox
Example 1: Set a prefilled chatbox input message with $crisp.push(["set", "message:text", ["Hi! I'd like to get help."]])
session:segments - $crisp.push(["set", "session:segments", [[segment_1, segment_2, ...]]]) - Sets the session segments (each segment must be a string)
Example 1: Set a single segment with $crisp.push(["set", "session:segments", [["customer"]]])
Example 2: Set multiple segments with $crisp.push(["set", "session:segments", [["help", "customer"]]])
session:data - $crisp.push(["set", "session:data", [[[key_1, value_1], [key_2, value_2], ...]]]) - Sets the session data for given key, with a value (value must be either a string, boolean or number)
Example 1: Set session data with $crisp.push(["set", "session:data", [[["user-bill-amount", "$200"]]]])
session:event - $crisp.push(["set", "session:event", [[[text_1, data_1, color_1], [text_2, data_2, color_2], ...]]]) - Sets one or multiple session events, with a text and an optional data object and optional color (in red, orange, yellow, green, blue, purple, pink, brown, grey, black)`
Example 1: Set session data with $crisp.push(["set", "session:event", [[["product_bought", { price: "$200", name: "iPhone 6S" }, "red"]]]])
user:email - $crisp.push(["set", "user:email", [email]]) - Sets the user email (must be a valid email)
Example 1: Set user email with $crisp.push(["set", "user:email", ["valerian@crisp.chat"]])
user:phone - $crisp.push(["set", "user:phone", [phone]]) - Sets the user phone (must be a valid phone number)
Example 1: Set user phone with $crisp.push(["set", "user:phone", ["+14152370800"]])
user:nickname - $crisp.push(["set", "user:nickname", [nickname]]) - Sets the user nickname
Example 1: Set user nickname with $crisp.push(["set", "user:nickname", ["Valerian Saliou"]])
user:avatar - $crisp.push(["set", "user:avatar", [avatar]]) - Sets the user avatar
Example 1: Set user avatar with $crisp.push(["set", "user:avatar", ["https://avatars3.githubusercontent.com/u/1451907"]])

Do an action

chat:open - $crisp.push(["do", "chat:open"]) - Opens the chatbox
chat:close - $crisp.push(["do", "chat:close"]) - Closes the chatbox
chat:toggle - $crisp.push(["do", "chat:toggle"]) - Toggles the chatbox (close if opened, open if closed)
chat:show - $crisp.push(["do", "chat:show"]) - Shows the chatbox (restore visibility to visible)
chat:hide - $crisp.push(["do", "chat:hide"]) - Hides the chatbox (don't close it if open, sets it invisible)
message:send - $crisp.push(["do", "message:send", [type, content]]) - Sends a message as visitor to conversation (type either text or file, if text then content is message string, if file then content is file object {url, name, type})
Example 1: Send a text message with $crisp.push(["do", "message:send", ["text", "Hello there!"]])
Example 2: Send a file message with $crisp.push(["do", "message:send", ["file", { name: "Europa.jpg", url: "https://upload.wikimedia.org/wikipedia/commons/thumb/5/54/Europa-moon.jpg/600px-Europa-moon.jpg", type: "image/jpg" }]])
Example 3: Send an animation message with $crisp.push(["do", "message:send", ["animation", { url: "https://media.giphy.com/media/3oz8xPjPPvOwrGjip2/giphy.gif", type: "image/gif" }]])
Example 4: Send an audio message with $crisp.push(["do", "message:send", ["audio", { duration: 40, url: "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/d70935e1-c79e-4199-9568-944541657b78.webm", type: "audio/webm" }]])
message:show - $crisp.push(["do", "message:show", [type, content]]) - Shows a message as operator in local chatbox (type either text or file, if text then content is message string, if file then content is file object {url, name, type})
Example 1: Show a text message with $crisp.push(["do", "message:show", ["text", "Can I help?"]])
Example 2: Show an animation message with $crisp.push(["do", "message:show", ["animation", { url: "https://media.giphy.com/media/IThjAlJnD9WNO/giphy.gif", type: "image/gif" }]])
Example 3: Show a picker message with $crisp.push(["do", "message:show", ["picker", { "id": "call-date", "text": "Pick your date!", "choices": [{ "value": "1", "label": "Today, 1:00PM.", "selected": false }, { "value": "2", "label": "Tomorrow, 3:45PM.", "selected": false }]}]])
Example 4: Show a field message with $crisp.push(["do", "message:show", ["field", { "id": "name-field", "text": "What is your name?", "explain": "Enter your name..." }]])
message:read - $crisp.push(["do", "message:read"]) - Marks all unread messages as read, clearing the pending messages notification and the unread counter
session:reset - $crisp.push(["do", "session:reset", [reload]]) - Resets the chatbox session to a new session (reload controls whether to reload page upon reset or not, defaults to true)
Example 1: Reset session with page reload with $crisp.push(["do", "session:reset", [true]])
Example 2: Reset session without page reload with $crisp.push(["do", "session:reset", [false]])
trigger:run - $crisp.push(["do", "trigger:run", [identifier]]) - Runs a trigger with given identifier (from configured triggers, if the Triggers plugin is enabled on your website)
Example 1: Run a saved trigger identifier with $crisp.push(["do", "trigger:run", ["growth-hack-1"]])

Register a callback on event

session:loaded - $crisp.push(["on", "session:loaded", callback]) - Handles the session loaded event (triggers your callback function, with session_id as first argument)
chat:initiated - $crisp.push(["on", "chat:initiated", callback]) - Handles the chatbox initiated event, on the first time the user clicks on the chatbox (triggers your callback function)
chat:opened - $crisp.push(["on", "chat:opened", callback]) - Handles the chatbox opened event (triggers your callback function)
chat:closed - $crisp.push(["on", "chat:closed", callback]) - Handles the chatbox closed event (triggers your callback function)
message:sent - $crisp.push(["on", "message:sent", callback]) - Handles the message sent event (triggers your callback function, with message as first argument)
message:received - $crisp.push(["on", "message:received", callback]) - Handles the message received event (triggers your callback function, with message as first argument)
message:compose:sent - $crisp.push(["on", "message:compose:sent", callback]) - Handles the message compose sent event (triggers your callback function, with compose as first argument)
message:compose:received - $crisp.push(["on", "message:compose:received", callback]) - Handles the message compose received event (triggers your callback function, with compose as first argument)
user:email:changed - $crisp.push(["on", "user:email:changed", callback]) - Handles the user email changed event (triggers your callback function, with email as first argument)
user:phone:changed - $crisp.push(["on", "user:phone:changed", callback]) - Handles the user phone changed event (triggers your callback function, with phone as first argument)
user:nickname:changed - $crisp.push(["on", "user:nickname:changed", callback]) - Handles the user nickname changed event (triggers your callback function, with nickname as first argument)
user:avatar:changed - $crisp.push(["on", "user:avatar:changed", callback]) - Handles the user avatar changed event (triggers your callback function, with avatar as first argument)
website:availability:changed - $crisp.push(["on", "website:availability:changed", callback]) - Handles the website availability changed event (triggers your callback function, with is_available as first argument)

Un-register a callback on event

session:loaded - $crisp.push(["off", "session:loaded"]) - Stops previously registered callback on session:loaded
chat:initiated - $crisp.push(["off", "chat:initiated"]) - Stops previously registered callback on chat:initiated
chat:opened - $crisp.push(["off", "chat:opened"]) - Stops previously registered callback on chat:opened
chat:closed - $crisp.push(["off", "chat:closed"]) - Stops previously registered callback on chat:closed
message:sent - $crisp.push(["off", "message:sent"]) - Stops previously registered callback on message:sent
message:received - $crisp.push(["off", "message:received"]) - Stops previously registered callback on message:received
message:compose:sent - $crisp.push(["off", "message:compose:sent"]) - Stops previously registered callback on message:compose:sent
message:compose:received - $crisp.push(["off", "message:compose:received"]) - Stops previously registered callback on message:compose:received
user:email:changed - $crisp.push(["off", "user:email:changed"]) - Stops previously registered callback on user:email:changed
user:phone:changed - $crisp.push(["off", "user:phone:changed"]) - Stops previously registered callback on user:phone:changed
user:nickname:changed - $crisp.push(["off", "user:nickname:changed"]) - Stops previously registered callback on user:nickname:changed
user:avatar:changed - $crisp.push(["off", "user:avatar:changed"]) - Stops previously registered callback on user:avatar:changed
website:availability:changed - $crisp.push(["off", "website:availability:changed"]) - Stops previously registered callback on website:availability:changed

Changes runtime configuration

availability:tooltip - $crisp.push(["config", "availability:tooltip", value]) - Changes the availability tooltip visibility value for the current page (can be true or false)
Example 1: Disable the availability tooltip on current page with $crisp.push(["config", "availability:tooltip", [false]])
hide:on:away - $crisp.push(["config", "hide:on:away", value]) - Changes the hide on support away value for the current page (can be true or false)
Example 1: Hide the chatbox if support is away on current page with $crisp.push(["config", "hide:on:away", [true]])
hide:on:mobile - $crisp.push(["config", "hide:on:mobile", value]) - Changes the hide chatbox on mobile devices value for the current page (can be true or false)
Example 1: Hide the chatbox if using a mobile device (ie. a small screen) on current page with $crisp.push(["config", "hide:on:mobile", [true]])
position:reverse - $crisp.push(["config", "position:reverse", value]) - Changes the chatbox position value for the current page (can be true or false)
Example 1: Reverse the chatbox position on current page with $crisp.push(["config", "position:reverse", [true]])

If you think something is missing from that list, refer to the List All Actions section to get the up-to-date list from your Crisp.

Available Actions

$crisp lets you do actions on the Crisp chatbox. You have the following actions available (as JavaScript functions):

Set a value: $crisp.push(["set", namespace, [value]]) (async-safe)
Do something: $crisp.push(["do, namespace, [arguments]]) (async-safe)
Listen for an event: $crisp.push(["on", namespace, callback]) (async-safe)
Stop listening for an event: $crisp.push(["off", namespace]) (async-safe)
Change runtime configuration: $crisp.push(["config", namespace, value]) (async-safe)
Get a value: $crisp.get(namespace) (not async-safe)
Check a state: $crisp.is(namespace) (returns a boolean, in any case) (not async-safe)

List All Actions

If you want to list the supported actions, which may be useful in some debugging cases, you can open a browser Developer Tools console and call:

$crisp.help()

It will return the list of supported actions associated to supported namespaces.

Disable Errors

You may enable $crisp safe mode to prevent $crisp to emit errors when an exception occurs. An exception can be, for instance, triggered by a call such as $crisp.push(["set", "user:email", ["invalid-email"]]) in case the value is invalid, relative to what's expected.

The safe mode is disabled by default, which means you may get errors, which is actually fine for development purposes. By enabling safe mode, no error will ever get thrown (in any case), which makes integration with your code safe.

To enable safe mode:

$crisp.safe()

You should call this code before using any other $crisp method.

Use $crisp Before It Is Ready

If you need to use $crisp before the chatbox scripts are done loading (eg: at page load), you need to use the $crisp.push() aync-safe methods.

You can safely push $crisp actions anywhere in your code using the $crisp.push() call:

// Set user email, async-safe
$crisp.push(["set", "user:email", "valerian@crisp.chat"]);

// Opens chatbox
$crisp.push(["do", "chat:open"]);


The first argument, is the action to execute. For example, for a set action, the first value will be "set". For an on action, the first value will be "on". For a do action, the first value will be "do", etc.

Also, if you need to call methods that cannot be passed to $crisp.push() because they return a value synchronously (eg. crisp.is() methods), you may use the window.CRISP_READY_TRIGGER register as such:

// This callback gets executed once $crisp is fully loaded and all methods (not only $crisp.push()) are available
window.CRISP_READY_TRIGGER = function() {
if ($crisp.is("chat:opened") === true) {
// Do something.
}
};
Was this article helpful?
Thank you!