Ask your own question.

Someone from our team or the Crisp community will answer publicly.

We will ask your email to let you know when an answer is published.

Thanks! We will let you know when an answer is published.

Tell us why you are not satisfied.

Tell us how we can improve, and what is missing.

We will answer if we need more details, and improve this help section.

Thanks! We will get back to you if we need more information.

How to use $crisp JavaScript SDK?

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

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

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.
  }
};
Valerian Saliou
Was this article helpful?YesNo
Thanks! 👍
Don’t find what you are looking for?

Ask your own question.

Ask Now