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

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

Available Namespaces

If you read the Available Actions section, you may have noticed every action function call refers to a namespace as first argument.

The namespace defines what you take action on, eg: chat:open is a namespace of the do() action. This has the benefit of being self-documenting.

Here's the list of supported action:

$crisp.do()

  • $crisp.do("chat:open") - Opens the chatbox
  • $crisp.do("chat:close") - Closes the chatbox
  • $crisp.do("chat:toggle") - Toggles the chatbox (close if opened, open if closed)
  • $crisp.do("chat:show") - Shows the chatbox (restore visibility to visible)
  • $crisp.do("chat:hide") - Hides the chatbox (don't close it if open, sets it invisible)
  • $crisp.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.do("message:send", ["text", "Hello there!"])
    • Example 2: Send a file message with $crisp.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" }])
  • $crisp.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.do("message:show", ["text", "Can I help?"])
    • Example 2: Show an animation message with $crisp.do("message:show", ["animation", { url: "https://media.giphy.com/media/IThjAlJnD9WNO/giphy.gif", type: "image/gif" }])
  • $crisp.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.do("session:reset", [true])
    • Example 2: Reset session without page reload with $crisp.do("session:reset", [false])
  • $crisp.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.do("trigger:run", ["growth-hack-1"])

$crisp.is()

  • $crisp.is("chat:opened") - Returns true if the chatbox is opened, else false
  • $crisp.is("chat:closed") - Returns true if the chatbox is closed, else false
  • $crisp.is("chat:visible") - Returns true if the chatbox is visible, else false
  • $crisp.is("chat:hidden") - Returns true if the chatbox is hidden, else false
  • $crisp.is("chat:small") - Returns true if the chatbox is small, else false
  • $crisp.is("chat:large") - Returns true if the chatbox is large, else false
  • $crisp.is("website:available") - Returns true if the website support is online, else false if away

$crisp.get()

  • $crisp.get("chat:unread:count") - Returns the number of unread messages in chat
  • $crisp.get("message:text") - Returns the current message text entered in the chatbox but not yet sent
  • $crisp.get("session:identifier") - Returns the current session identifier (or null if not yet loaded)
  • $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")
  • $crisp.get("user:email") - Returns the user email (or null if not set)
  • $crisp.get("user:phone") - Returns the user phone (or null if not set)
  • $crisp.get("user:nickname") - Returns the user nickname (or null if not set)
  • $crisp.get("user:avatar") - Returns the user avatar (or null if not set)

$crisp.set()

  • $crisp.set("message:text", message_text) - Pre-fill the current message text in the chatbox
    • Example 1: Set a prefilled chatbox input message with $crisp.set("message:text", "Hi! I'd like to get help.")
  • $crisp.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.set("session:segments", [["customer"]])
    • Example 2: Set multiple segments with $crisp.set("session:segments", [["help", "customer"]])
  • $crisp.set("session:data", [key, value]) - 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.set("session:data", ["user-bill-amount", "$200"])
  • $crisp.set("user:email", email) - Sets the user email (must be a valid email)
    • Example 1: Set user email with $crisp.set("user:email", "valerian@crisp.im")
  • $crisp.set("user:phone", phone) - Sets the user phone (must be a valid phone number)
    • Example 1: Set user phone with $crisp.set("user:phone", "+14152370800")
  • $crisp.set("user:nickname", nickname) - Sets the user nickname
    • Example 1: Set user nickname with $crisp.set("user:nickname", "Valerian Saliou")
  • $crisp.set("user:avatar", avatar) - Sets the user avatar
    • Example 1: Set user avatar with $crisp.set("user:avatar", "https://avatars3.githubusercontent.com/u/1451907")

$crisp.on()

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

$crisp.off()

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

$crisp.push()

  • $crisp.push(["do", namespace, [options]]) - Pushes a do action to be processed in an async-safe way
    • Example 1: Opens chatbox in an async-safe way with $crisp.push(["do", "chat:open"])
    • Example 2: Sends a message in an async-safe way with $crisp.push(["do", "message:send", ["text", "Hello!"]])
  • $crisp.push(["set", namespace, [options]]) - Pushes a set action to be processed in an async-safe way
    • Example 1: Sets user email in an async-safe way with $crisp.push(["set", "user:email", "valerian@crisp.im"])
    • Example 2: Sets user nickname in an async-safe way with $crisp.push(["set", "user:nickname", "Valerian Saliou"])
    • Example 3: Sets session segments in an async-safe way with $crisp.push(["set", "session:segments", [["help", "customer"]]])
  • $crisp.push(["on", namespace, callback]) - Pushes an on action to be processed in an async-safe way
    • Example 1: Print a log when the chatbox is opened $crisp.push(["on", "chat:opened", function() {console.log("chat:opened")}]);
    • Example 2: Print a log when a message is sent $crisp.push(["on", "message:sent", function() {console.log("message:sent")}]);

$crisp.config()

  • $crisp.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.config("availability:tooltip", false)
  • $crisp.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.config("hide:on:away", true)
  • $crisp.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.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.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.im"]);

// 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".

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.
  }
};

Use The Regular $crisp Code

Here is an example of a regular $crisp call, used to set visitor email once the Crisp chatbox is ready:

// Set visitor email, not async-safe
$crisp.set("user:email", "valerian@crisp.im");

Beware: this code won't work if the chatbox is not yet loaded. If you need to trigger $crisp actions early (eg. at page load), use the safe $crisp.push() mode described above.

Valerian Saliou
Was this article helpful?YesNo
Thanks! 👍
Don’t find what you are looking for?

Ask your own question.

Ask Now