If your website shows the chatbox for authenticated users only - in other words: users for which you have an internal identification value, such as a user ID, an email or a token - you may want to ensure that the Crisp chat session associated to that user stays the same, whatever the device he is on and whether your user clears his cookies or not. This ensures you get chats from the same user in the same Crisp session.

You can do so using Crisp Tokens. A token is a private and secure arbitrary value that is known to your system, and sent when you inject Crisp in the page. Each user must be associated to a different token (if you use the token system).

• $crisp MethodsRead about the available $crisp JS methods.Read

How-To Video

How To Associate A Session To A Token?

Sessions can be associated to tokens, or restored from tokens, using the CRISP_TOKEN_ID variable.

You can use the following Crisp chatbox code (fill CRISP_TOKEN_ID with your secure user token ID, and CRISP_WEBSITE_ID with your Website ID):

<script type="text/javascript">
  $crisp = [];
  CRISP_TOKEN_ID = 'UserSecureTokenFromMyWebsite';
  CRISP_WEBSITE_ID = 'MyWebsiteID';
  (function(){d=document;s=d.createElement('script');s.src='//client.crisp.chat/l.js';s.async=1;d.getElementsByTagName('head')[0].appendChild(s);})();
</script>

Please note that:

• Tokens can only be passed before, or upon chatbox code injection, and not after the chatbox code loaded. If you retrieve the token after the chatbox is loaded (eg. after your user has logged in), then you should call $crisp.push(["do", "session:reset"]): it will take the new token into account.
• When users logout from their account on your website, make sure you clear the CRISP_TOKEN_ID variable and then reset their local session cookie with Crisp, by using $crisp.push(["do", "session:reset"]). This will not destroy the remote session with Crisp, it will only unbind the browser from it. This session will be recovered when the user logs in again to their account, via their token.

Example of logout handling:

function userLogout() {
  // Execute this sequence when your users are logging out
  CRISP_TOKEN_ID = null; // 1. Clear the token value

  $crisp.push(["do", "session:reset"]); // 2. Unbind the current session
}

How To Generate A Token?

Session tokens should be generated by your backend, and kept stored in your database. A given token should be associated to 1 single unique user, and not be shared amongst multiple users.

1. Here's how to generate a UUID V4-based token using NodeJS:

// UUID library from NPMJS
// @see: https://www.npmjs.com/package/uuid/
var UUID = require("uuid/v4");

// The token generation function
function generate_user_token() {
  return UUID();
}

// When you create your user in your database, or initialize their token, call 'generate_user_token()'

2. As an example, here's an UUID V4 token: 253cd617-5a8f-4963-85b3-77ab91687196

3. Now, when you serve a page to your authenticated user with token eg. 253cd617-5a8f-4963-85b3-77ab91687196, you'd generate the following HTML code for the Crisp chatbox:

<script type="text/javascript">
  $crisp = [];
  CRISP_TOKEN_ID = '253cd617-5a8f-4963-85b3-77ab91687196';
  CRISP_WEBSITE_ID = 'MyWebsiteID';
  (function(){d=document;s=d.createElement('script');s.src='//client.crisp.chat/l.js';s.async=1;d.getElementsByTagName('head')[0].appendChild(s);})();
</script>

How to merge messages from anonymous sessions to token sessions?

When your users start to chat with you on your public website before they are authenticated, Crisp creates an anonymous session for them. Once they login to their account on your website, you authenticate them with their token. The chatbox session is completely switched, with the messages that can be seen in the chatbox.

If you want to automatically merge messages from the previous anonymous session to the token session, you can opt-in for the session merge feature by adding this global JavaScript variable in your Crisp include code:

<script type="text/javascript">
  CRISP_RUNTIME_CONFIG = {
    session_merge : true
  };
</script>

Important Notes On Security

Please read everything that follows before implementing CRISP_TOKEN_ID on your website.

Because Crisp puts a strong emphasis on security, we do not allow sessions to be restored / merged when the user fills his email in the chatbox, after he sent his first message.

The reason is the following: some of your users may send sensitive information on your chat. They may have an email address known to some attackers. A very simple attack would then be possible to recover the user chat session: start a new chat session and fill the email field using the attacked user email address. Then, see all past messages from the attacked user. Of course, this type of attack is not possible with Crisp (this was an example).

Furthermore, in some companies, customer support team / admins log in to their end-users accounts, for customer / debugging purposes. In this specific case, we advise to either disable the CRISP_TOKEN_ID feature, or better, to not load the Crisp chatbox at all, to prevent merging sessions of different users. Let's say you connect to user A dashboard, and then to user B dashboard: using the CRISP_TOKEN_ID feature without resetting the Crisp session prior would have the effect to merge user A and user B sessions.

Also, here are few examples of unsafe tokens:

• Auto-incremented IDs (eg. 1234)
• Hashed emails (ie. via MD5, SHA256)
• Using your user email as token
• Using current time / timestamp as a token

Here are few examples of safe tokens:

• UUID V4 (eg. c77233db-15cd-4399-82ae-471440d045b8)
• String-encoded pseudorandom key, generated from a good source of entropy

If you use an unsecure identification token, such as an email address - in other words, a token which can be known from unauthenticated users - the attack described above is still possible. For instance, if you set CRISP_TOKEN_ID to the user's email address (which is then a value that can be known to an attacker), then the attacker can recover any previous chat session with the attacked user by setting the CRISP_TOKEN_ID value to the email he wants to target.

Crisp declines all responsibility for unsecure implementations of this feature. You have to ensure that the tokens you associate to sessions are secure and only known to an authenticated user.