Chatbox SDKs | Web SDK

NPM Package

Updated on December 15, 2022

The crisp-sdk-web package allows embedding Crisp chat widget using web frameworks such as React, Vue, or Angular. This SDK wraps the $crisp methods and provides TypeScript definitions.

This package is a wrapper over the $crisp JavaScript SDK. It will automatically inject the Crisp Widget in your web application and will provide more flexibility as well as autocompletion with your IDE.

Installation

npm install --save crisp-sdk-web

Basic Implementation

To add Crisp on your website, you will first need to create an account from the Crisp App.

Once you have your Crisp Website ID, you can then embbed Crisp in your app.

import { Crisp } from "crisp-sdk-web";

Crisp.configure(WEBSITE_ID);

// Crisp will be displayed

Manual loading

Deferring Crisp loading is possible, for instance, to display the chat after a login screen or custom button.

import { Crisp } from "crisp-sdk-web";

Crisp.configure(WEBSITE_ID, {
  autoload: false
});

// Crisp.load()

Then, you can include Crisp using Crisp.load(). Note that Methods such as Crisp.chat.open() or Crisp.chat.show() are implicitly calling the loading method.

Identity Management

You may attach user information so your customers don't need to manually fill their email address. Providing custom data is possible as well.


Crisp.user.setEmail("john.doe@gmail.com");
Crisp.user.setNickname("John Doe");

Crisp.session.setData({
  user_id : "123456",
  plan : "free"
});

Pushing Events

Crisp allows pushing custom events. Those events can then be used in order to trigger automated campaigns or bot scenarios.


Crisp.session.pushEvent("signup");

// Or with custom parameters
Crisp.session.pushEvent("purchase", {
  price: 66.66,
  item: "XXXX_XXXX"
});

Session Continuity

Crisp sessions are relying on Cookies. If you want Crisp sessions to be persisted on a user basis, you can use the tokenId feature. We are strongly recommending having a look to our security recommendations before enforcing session continuity.

import { Crisp } from "crisp-sdk-web";

Crisp.configure(WEBSITE_ID, {
  autoload: false
});

// await login();

Crisp.setTokenId("A_VERY_UNIQUE_AND_SECURE_TOKEN");
Crisp.user.setEmail("john.doe@gmail.com");
Crisp.user.setNickname("John Doe");

Create a simple bot

Creating simple bots using the crisp SDK is easy. In the following example we will send a message picker and receive an update once the user select a choice.

The first step is sending a message picker with id a-custom-id (you can select your own id):

Crisp.message.show("picker", {
  "id": "a-custom-id",
  "text": "What is your question about?",

  "choices": [
    {
      "value": "sales",
      "label": "Sales",
      "selected": false
    },

    {
      "value": "tech",
      "label": "Tech",
      "selected": false
    }
  ]
});

Then, you can send a follow-up response based on the selected choice:

Crisp.chat.onMessageReceived((data) => {
  // Skip responses not being updates
  if (data.origin !== "update") {
    return;
  }

  // Skip messages types other than pickers
  if (data.type !== "picker") {
    return;
  }

  // Skip other ids
  if (data.content.id !== "a-custom-id") {
    return;
  }

  let _choice = data.content.choices.find(choice => choice.selected)

  Crisp.message.send("text", "Current choice is " + _choice.label);
});

Available Methods

Configuration

Configure

To load the SDK you will need to use Crisp.configure(WEBSITE_ID, options).

Different options are available:

autoload: Autoload Crisp once Crisp is configured. Default: true
tokenId: Session continuty token. Default: null
locale: Set a custom locale (en, fr, de, ...) Default: null
sessionMerge: Enables session merge. Default: false
cookieDomain: Enforce a custom domain for Cookie storage. Default: null
cookieExpire: Enforce a custom expire time for Cookie storage. Default: null
lockMaximized: Prevents chatbox from being closed. Default: false
lockFullview: Enforces chatbox fullscreen mode. Default: false
safeMode: Enforces chatbox safe mode. Default: false

For instance, the following code will open Crisp in fullscreen and will prevent it from being closed:

Crisp.configure(WEBSITE_ID, {
  lockMaximized: true,
  lockFullview: true
});

Manual Loading

This methods needs to be used if autoload is disabled. To include the Chatbox manually use:

Crisp.load();

Set Token Identifier

This method is used in order to set a tokenID, to enable session continuity.

Crisp.setTokenId(tokenID);

Set Z-Index

This method wil update the Chatbox z-index:

Crisp.setZIndex(99999);

Set Color Theme

You can use different colors themes, including: default, amber, black, blue, blue_grey, light_blue, brown, cyan, green, light_green, grey, indigo, orange, deep_orange, pink, purple, deep_purple, red, teal

You can for instance set the chatbox color to green by calling:

Crisp.setColorTheme("green");

Hide On Away

This method will hide the Crisp chatbox when no one is available to answer.

Crisp.setHideOnAway(true);

Hide on Mobile

This method will hide the Crisp chatbox on mobile.

Crisp.setHideOnMobile(true);

Set Position (Left or Right)

This method will switch the Crisp chatbox position to the left or to the right position.

Crisp.setPosition("left");

This method will enable or disable the Crisp chatbox availability tooltip.

Crisp.setAvailabilityTooltip(false);

Enable/Disable Vacation Mode

This method will hide completely hide the Crisp chatbox when enabled.

Crisp.setVacationMode(true);

Mute Sounds

This method will hide mute notification sounds when enabled.

Crisp.muteSound(true);

Enable/Disable Operator Count

This method will stop displaying the operator count.

Crisp.toggleOperatorCount(true);

Safe Mode

This method will turn off all errors generated by the $crisp SDK

Crisp.setSafeMode(true);

Chat

Show the Chat

This method will show the Crisp chat widget.

Crisp.chat.show();

Hide the Chat

This method will hide the Crisp chat widget.

Crisp.chat.hide();

Open the Chat

This method will open the Crisp chat widget.

Crisp.chat.open();

Close the Chat

This method will close the Crisp chat widget.

Crisp.chat.close();

Get the Unread Count

This method will fetch unread the message count

var count = Crisp.chat.unreadCount();

Check if the Chat is Opened

This method will return is the chat is opened.

var isOpened = Crisp.chat.isChatOpened();

Check if the Chat is Visible

This method will return is the chat is visible.

var isVisibleOpened = Crisp.chat.isVisible();

Chat Initiated Callback

Crisp.chat.onChatInitiated(() => {
  // Executed once the chat was initiated from the user
})

Chat Opened Callback

Crisp.chat.onChatOpened(() => {
  // Executed once the chat was opened
})

Chat Closed Callback

Crisp.chat.onChatClosed(() => {
  // Executed once the chat was closed
})

Message

Send a Message (Generic)

Sends a message as visitor to conversation.

// Example 1: send a text message
Crisp.message.send("text", "Hello there!");

// Example 2: send a file message
Crisp.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
Crisp.message.send("animation", {
  url: "https://media.giphy.com/media/3oz8xPjPPvOwrGjip2/giphy.gif",
  type: "image/gif"
});

// Example 4: send an audio message
Crisp.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"
});

Send a Text Message

Sends a text message as visitor to conversation.

Crisp.message.sendText("Hello there!");

Send a File Message

Sends a file message as visitor to conversation.

Crisp.message.sendFile("Hello there!", {
  name: "Europa.jpg",
  url: "https://upload.wikimedia.org/wikipedia/commons/thumb/5/54/Europa-moon.jpg/600px-Europa-moon.jpg",
  type: "image/jpg"
});

Send an Animation Message

Sends a animation message as visitor to conversation.

Crisp.message.sendAnimation("Hello there!", {
  url: "https://media.giphy.com/media/3oz8xPjPPvOwrGjip2/giphy.gif",
  type: "image/gif"
});

Send an Audio Message

Sends a audio message as visitor to conversation.

Crisp.message.sendAudio("Hello there!", {
  duration: 40,
  url: "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/d70935e1-c79e-4199-9568-944541657b78.webm",
  type: "audio/webm"
});

Show a Message (Generic)

Shows a message as operator in local chatbox.

// Example 1: show a text message
Crisp.message.show("text", "Can I help?!");

// Example 2: show a file message
Crisp.message.show("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: show a picker message
Crisp.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
Crisp.message.show("field", {
  "id": "name-field",
  "text": "What is your name?",
  "explain": "Enter your name..."
});

// Example 5: show a carousel message
Crisp.message.show("carousel", {
  "text": "Sure! Here's what I have...",

  "targets": [
    {
      "title": "iPhone 12 Mini",
      "description": "Refurbished iPhone 12 Mini in excellent condition.",

      "actions": [
        {
          "label": "View Product",
          "url": "https://www.apple.com/shop/buy-iphone/iphone-12"
        }
      ]
    },

    {
      "title": "iPhone 13",
      "description": "Brand new iPhone 13, coming with Apple Care.",

      "actions": [
        {
          "label": "View Product",
          "url": "https://www.apple.com/shop/buy-iphone/iphone-13"
        }
      ]
    }
  ]
});

Show a Text Message

Shows a text message as operator in local chatbox.

Crisp.message.showText("Can I help?!");

Show a File Message

Shows a file message as operator in local chatbox.

Crisp.message.showFile({
  name: "Europa.jpg",
  url: "https://upload.wikimedia.org/wikipedia/commons/thumb/5/54/Europa-moon.jpg/600px-Europa-moon.jpg",
  type: "image/jpg"
});

Show a Picker Message

Shows a picker message as operator in local chatbox.

Crisp.message.showPicker({
  "id": "call-date",
  "text": "Pick your date!",

  "choices": [
    {
      "value": "1",
      "label": "Today, 1:00PM.",
      "selected": false
    },

    {
      "value": "2",
      "label": "Tomorrow, 3:45PM.",
      "selected": false
    }
  ]
});

Show a Field Message

Shows a field message as operator in local chatbox.

Crisp.message.showField({
  "id": "call-date",
  "text": "Pick your date!",

  "choices": [
    {
      "value": "1",
      "label": "Today, 1:00PM.",
      "selected": false
    },

    {
      "value": "2",
      "label": "Tomorrow, 3:45PM.",
      "selected": false
    }
  ]
});

Show a Carousel Message

Shows a carousel message as operator in local chatbox.

Crisp.message.showCarousel({
  "text": "Sure! Here's what I have...",

  "targets": [
    {
      "title": "iPhone 12 Mini",
      "description": "Refurbished iPhone 12 Mini in excellent condition.",

      "actions": [
        {
          "label": "View Product",
          "url": "https://www.apple.com/shop/buy-iphone/iphone-12"
        }
      ]
    },

    {
      "title": "iPhone 13",
      "description": "Brand new iPhone 13, coming with Apple Care.",

      "actions": [
        {
          "label": "View Product",
          "url": "https://www.apple.com/shop/buy-iphone/iphone-13"
        }
      ]
    }
  ]
});

Mark as Read

Marks all messages as read

Crisp.chat.markAsRead();

Message Sent Callback

Crisp.chat.onMessageSent((data) => {
  // Executed once a message is submitted by the visitor
})

Message Received Callback

Crisp.chat.onMessageReceived((data) => {
  // Executed once a message is received by the visitor
})

Message Compose Sent Callback

Crisp.chat.onMessageComposeSent(() => {
  // Executed once a message compose event is submitted by the visitor
})

Message Compose Receive Callback

Crisp.chat.onMessageComposeReceive(() => {
  // Executed once a message compose event is received by the visitor
})

User

Set User Nickname

This method will update user's name.

Crisp.user.setNickname("John Doe");

Set User Email

This method will update user's email.

Crisp.user.setEmail("john.doe@gmail.com");

If you want to enable session verification please check our documentation here: https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/identity-verification/

You can set your computed HMAC using:

Crisp.user.setEmail("john.doe@gmail.com", HMAC);

Set User Phone

This method will update user's phone number.

Crisp.user.setPhone("0044346354635");

Set User Avatar

This method will will update user's avatar.

Crisp.user.setAvatar("https://pbs.twimg.com/profile_images/834424630630817795/TfyS4uXb_400x400.jpg");

Set User Company

Example 1: set user company name only:

Crisp.user.setCompany("Stripe");

Example 2: set user company name and location:

Crisp.user.setCompany("Stripe", {
  geolocation: {
    city: "San Fransisco",
    country: "US"
  }
});

Example 3: set all user company details:

Crisp.user.setCompany("Stripe", {
  url: "https://stripe.com",
  description: "Payments infrastructure for the internet",

  employment: {
    title: "Product Manager"
  },

  geolocation: {
    city: "San Fransisco",
    country: "US"
  }
});

Get User Nickname

This method will gets user's name.

var nickname = Crisp.user.getNickname();

Get User Email

This method will gets user's email.

var nickname = Crisp.user.getEmail();

Get User Phone

This method will gets user's phone.

var nickname = Crisp.user.getPhone();

Get User Avatar

This method will gets user's avatar.

var nickname = Crisp.user.getAvatar();

Get User Company

This method will gets user's company.

var company = Crisp.user.getCompany();

User Nickname Changed Callback

Crisp.user.onNicknameChanged(() => {
  // Executed once user's nickname is changed
})

User Email Changed Callback

Crisp.user.onEmailChanged(() => {
  // Executed once user's email is changed
})

User Phone Changed Callback

Crisp.user.onPhoneChanged(() => {
  // Executed once user's phone is changed
})

User Avatar Changed Callback

Crisp.user.onAvatarChanged(() => {
  // Executed once user's avatar is changed
})

Session

Reset a Session

This method will reset the user's session.

Crisp.session.reset();

Set Session Segments

This method will set the user's session segments:

Crisp.session.setSegments(["bug", "ios"]); // appens `bug` and `ios` segments.

Alternatively, you may override segments by using:

Crisp.session.setSegments(["bug", "ios"], true);

Set Session Data

This method will add custom data to the current session.

Crisp.session.setData({
  user_id : "123456",
  plan : "free"
});

Push Session Events

Crisp allows pushing custom events. Those events can then be used in order to trigger automated campaigns or bot scenarios.

Crisp.session.pushEvent("signup");

// Or with custom parameters
Crisp.session.pushEvent("purchase", {
  price: 66.66,
  item: "XXXX_XXXX"
});

Get Session Data

Will get custom data key

var key = Crisp.session.getData("user_id");

Get Session Identifier

Will get current session identifier (session_id)

var sessionId = Crisp.session.getIdentifier();

Session Loaded Callback

Crisp.session.onLoaded((sessionId) => {
  // Executed once the Crisp session is loaded

  console.log(sessionId);
})

Trigger

Run a Trigger Manually

This method will run the a custom trigger.

Crisp.trigger.name("growth_hack"); // will run the `growth_hack` trigger.