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.
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");
Enable/Disable Availability Tooltip
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.