$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.

The $crisp JavaScript SDK is included in the Crisp chatbox. You don't need to install or enable anything, as it is built-in. You can start using it straight with no specific configuration.

Available Namespaces

You can find the list of supported actions here.

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]

Description: Returns true if the chatbox is opened, else false.
Code: $crisp.is("chat:opened")

[chat:closed]

Description: Returns true if the chatbox is closed, else false.
Code: $crisp.is("chat:closed")

[chat:visible]

Description: Returns true if the chatbox is visible, else false.
Code: $crisp.is("chat:visible")

[chat:hidden]

Description: Returns true if the chatbox is hidden, else false.
Code: $crisp.is("chat:hidden")

[chat:small]

Description: Returns true if the chatbox is small, else false.
Code: $crisp.is("chat:small")

[chat:large]

Description: Returns true if the chatbox is large, else false.
Code: $crisp.is("chat:large")

[session:ongoing]

Description: Returns true if a session is ongoing (ie. messages have been received or sent), else false.
Code: $crisp.is("session:ongoing")

[website:available]

Description: Returns true if the website support is online, else false if away.
Code: $crisp.is("website:available")

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]

Description: Returns the number of unread messages in chat.
Code: $crisp.get("chat:unread:count")

[message:text]

Description: Returns the current message text entered in the chatbox but not yet sent.
Code: $crisp.get("message:text")

[session:identifier]

Description: Returns the current session identifier (or null if not yet loaded).
Code: $crisp.get("session:identifier")

[session:data]

Description: Returns the current session data (all data if key is null, or data for given key).
Code: $crisp.get("session:data", key)

Example 1: Get a saved session data key with $crisp.get("session:data", "user-bill-amount")

[user:email]

Description: Returns the user email (or null if not set).
Code: $crisp.get("user:email")

[user:phone]

Description: Returns the user phone (or null if not set).
Code: $crisp.get("user:phone")

[user:nickname]

Description: Returns the user nickname (or null if not set).
Code: $crisp.get("user:nickname")

[user:avatar]

Description: Returns the user avatar (or null if not set).
Code: $crisp.get("user:avatar")

[user:company]

Description: Returns the user company (or null if not set).
Code: $crisp.get("user:company")

Set a value

[message:text]

Description: Pre-fill the current message text in the chatbox.
Code: $crisp.push(["set", "message:text", [message_text]])

Example 1: Set a prefilled chatbox input message with $crisp.push(["set", "message:text", ["Hi! I'd like to get help."]])

[session:segments]

Description: Sets the session segments (each segment must be a string).
Code: $crisp.push(["set", "session:segments", [[segment_1, segment_2, ...]]])

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]

Description: Sets the session data for given key, with a value (value must be either a string, boolean or number).
Code: $crisp.push(["set", "session:data", [[[key_1, value_1], [key_2, value_2], ...]]])

Example 1: Set session data with $crisp.push(["set", "session:data", [[["user-bill-amount", "$200"]]]])

[session:event]

Description: 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).
Code: $crisp.push(["set", "session:event", [[[text_1, data_1, color_1], [text_2, data_2, color_2], ...]]])

Example 1: Set session data with $crisp.push(["set", "session:event", [[["product_bought", { price: "$200", name: "iPhone 6S" }, "red"]]]])

[user:email]

Description: Sets the user email (must be a valid email).
Code: $crisp.push(["set", "user:email", [email]])

Example 1: Set user email with $crisp.push(["set", "user:email", ["valerian@crisp.chat"]])

[user:phone]

Description: Sets the user phone (must be a valid phone number).
Code: $crisp.push(["set", "user:phone", [phone]])

Example 1: Set user phone with $crisp.push(["set", "user:phone", ["+14152370800"]])

[user:nickname]

Description: Sets the user nickname.
Code: $crisp.push(["set", "user:nickname", [nickname]])

Example 1: Set user nickname with $crisp.push(["set", "user:nickname", ["Valerian Saliou"]])

[user:avatar]

Description: Sets the user avatar.
Code: $crisp.push(["set", "user:avatar", [avatar]])

Example 1: Set user avatar with $crisp.push(["set", "user:avatar", ["https://pbs.twimg.com/profile_images/834424630630817795/TfyS4uXb_400x400.jpg"]])

[user:company]

Description: Sets the user company.
Code: $crisp.push(["set", "user:company", [name, { url, description, geolocation: [country, city] }]])

Example 1: Set all user company details with $crisp.push(["set", "user:company", ["Crisp", { url: "https://crisp.chat/", description: "Give your customer experience a human touch.", geolocation: ["FR", "Nantes"] }]])
Example 2: Set user company name only with $crisp.push(["set", "user:company", ["Crisp"]])
Example 3: Set user company name and geolocation only with $crisp.push(["set", "user:company", ["Crisp", { geolocation: ["FR", "Nantes"] }]])

Do an action

[chat:open]

Description: Opens the chatbox.
Code: $crisp.push(["do", "chat:open"])

[chat:close]

Description: Closes the chatbox.
Code: $crisp.push(["do", "chat:close"])

[chat:toggle]

Description: Toggles the chatbox (close if opened, open if closed).
Code: $crisp.push(["do", "chat:toggle"])

[chat:show]

Description: Shows the chatbox (restore visibility to visible).
Code: $crisp.push(["do", "chat:show"])

[chat:hide]

Description: Hides the chatbox (don't close it if open, sets it invisible).
Code: $crisp.push(["do", "chat:hide"])

[helpdesk:search]

Description: Opens helpdesk search interface (only if an helpdesk is configured).
Code: $crisp.push(["do", "helpdesk:search"])

[message:send]

Description: 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}).
Code: $crisp.push(["do", "message:send", [type, content]])

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]

Description: 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}).
Code: $crisp.push(["do", "message:show", [type, content]])

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]

Description: Marks all unread messages as read, clearing the pending messages notification and the unread counter.
Code: $crisp.push(["do", "message:read"])

[session:reset]

Description: Resets the chatbox session to a new session (reload controls whether to reload page upon reset or not, reloading is required to start from a fresh state, defaults to true).
Code: $crisp.push(["do", "session:reset", [reload]])

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]

Description: Runs a trigger with given identifier (from configured triggers, if the Triggers plugin is enabled on your website).
Code: $crisp.push(["do", "trigger:run", [identifier]])

Example 1: Run a saved trigger identifier with $crisp.push(["do", "trigger:run", ["growth-hack-1"]])

Register a callback on event

[session:loaded]

Description: Handles the session loaded event (triggers your callback function, with session_id as first argument).
Code: $crisp.push(["on", "session:loaded", callback])

[chat:initiated]

Description: Handles the chatbox initiated event, on the first time the user clicks on the chatbox (triggers your callback function).
Code: $crisp.push(["on", "chat:initiated", callback])

[chat:opened]

Description: Handles the chatbox opened event (triggers your callback function).
Code: $crisp.push(["on", "chat:opened", callback])

[chat:closed]

Description: Handles the chatbox closed event (triggers your callback function).
Code: $crisp.push(["on", "chat:closed", callback])

[message:sent]

Description: Handles the message sent event (triggers your callback function, with message as first argument).
Code: $crisp.push(["on", "message:sent", callback])

[message:received]

Description: Handles the message received event (triggers your callback function, with message as first argument).
Code: $crisp.push(["on", "message:received", callback])

[message:compose:sent]

Description: Handles the message compose sent event (triggers your callback function, with compose as first argument).
Code: $crisp.push(["on", "message:compose:sent", callback])

[message:compose:received]

Description: Handles the message compose received event (triggers your callback function, with compose as first argument).
Code: $crisp.push(["on", "message:compose:received", callback])

[user:email:changed]

Description: Handles the user email changed event (triggers your callback function, with email as first argument).
Code: $crisp.push(["on", "user:email:changed", callback])

[user:phone:changed]

Description: Handles the user phone changed event (triggers your callback function, with phone as first argument).
Code: $crisp.push(["on", "user:phone:changed", callback])

[user:nickname:changed]

Description: Handles the user nickname changed event (triggers your callback function, with nickname as first argument).
Code: $crisp.push(["on", "user:nickname:changed", callback])

[user:avatar:changed]

Description: Handles the user avatar changed event (triggers your callback function, with avatar as first argument).
Code: $crisp.push(["on", "user:avatar:changed", callback])

[website:availability:changed]

Description: Handles the website availability changed event (triggers your callback function, with is_available as first argument).
Code: $crisp.push(["on", "website:availability:changed", callback])

Un-register a callback on event

[session:loaded]

Description: Stops previously registered callback on session:loaded.
Code: $crisp.push(["off", "session:loaded"])

[chat:initiated]

Description: Stops previously registered callback on chat:initiated.
Code: $crisp.push(["off", "chat:initiated"])

[chat:opened]

Description: Stops previously registered callback on chat:opened.
Code: $crisp.push(["off", "chat:opened"])

[chat:closed]

Description: Stops previously registered callback on chat:closed.
Code: $crisp.push(["off", "chat:closed"])

[message:sent]

Description: Stops previously registered callback on message:sent.
Code: $crisp.push(["off", "message:sent"])

[message:received]

Description: Stops previously registered callback on message:received.
Code: $crisp.push(["off", "message:received"])

[message:compose:sent]

Description: Stops previously registered callback on message:compose:sent.
Code: $crisp.push(["off", "message:compose:sent"])

[message:compose:received]

Description: Stops previously registered callback on message:compose:received.
Code: $crisp.push(["off", "message:compose:received"])

[user:email:changed]

Description: Stops previously registered callback on user:email:changed.
Code: $crisp.push(["off", "user:email:changed"])

[user:phone:changed]

Description: Stops previously registered callback on user:phone:changed.
Code: $crisp.push(["off", "user:phone:changed"])

[user:nickname:changed]

Description: Stops previously registered callback on user:nickname:changed.
Code: $crisp.push(["off", "user:nickname:changed"])

[user:avatar:changed]

Description: Stops previously registered callback on user:avatar:changed.
Code: $crisp.push(["off", "user:avatar:changed"])

[website:availability:changed]

Description: Stops previously registered callback on website:availability:changed.
Code: $crisp.push(["off", "website:availability:changed"])

Changes runtime configuration

[availability:tooltip]

Description: Changes the availability tooltip visibility value for the current page (can be true or false).
Code: $crisp.push(["config", "availability:tooltip", value])

Example 1: Disable the availability tooltip on current page with $crisp.push(["config", "availability:tooltip", [false]])

[hide:vacation]

Description: Changes the hide chatbox for support on vacation value for the current page (can be true or false).
Code: $crisp.push(["config", "hide:vacation", value])

Example 1: Hide the chatbox if support is on vacation on current page with $crisp.push(["config", "hide:vacation", [true]])

[hide:on:away]

Description: Changes the hide on support away value for the current page (can be true or false).
Code: $crisp.push(["config", "hide:on:away", value])

Example 1: Hide the chatbox if support is away on current page with $crisp.push(["config", "hide:on:away", [true]])

[hide:on:mobile]

Description: Changes the hide chatbox on mobile devices value for the current page (can be true or false).
Code: $crisp.push(["config", "hide:on:mobile", value])

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]

Description: Changes the chatbox position value for the current page (can be true or false).
Code: $crisp.push(["config", "position:reverse", value])

Example 1: Reverse the chatbox position on current page with $crisp.push(["config", "position:reverse", [true]])

[color:theme]

Description: Changes the chatbox color theme for the current page (any color variant in: default, amber, black, blue, blue_grey, light_blue, brown, cyan, green, light_green, grey, indigo, orange, deep_orange, pink, purple, deep_purple, red, teal).
Code: $crisp.push(["config", "color:theme", value]

Example 1: Change the chatbox color on current page to red with $crisp.push(["config", "color:theme", ["red"]])

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 Warnings & 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.

Without safe mode, Crisp may also throw warnings in your console logs to help you address potential issues with your chatbox integration. If you choose to ignore any warning, enabling the safe mode is also the way to go.

To enable safe mode:

$crisp.push(["safe", true])

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!