Website chat for developers: cookie choice and signed-in customers

The website chat's install code defines a JavaScript function, window.AIChatbot, that your own code calls to pass a visitor's cookie choice, link the chat to a signed-in customer, forget that customer at sign-out, and open or close the chat. You only need this page if your website asks visitors about cookies or has customer accounts; the chat works without any of it.

What does the install code contain?

The install code you copy from "Add chat to your website" is one line with two parts:

• A queue line that defines window.AIChatbot straight away. Commands sent before the chat has loaded wait in this queue and run in order as soon as the chat loads.
• The chat script, widget.js, with your site key.

Paste the whole line just before </body> on every page, as getting started describes. Code that runs before the install code, for example in <head>, starts with the same queue line:

window.AIChatbot=window.AIChatbot||function(){(window.AIChatbot.q=window.AIChatbot.q||[]).push(arguments)};

Running the queue line more than once is safe, because it never replaces a function that already exists. If your website sets a Content Security Policy that blocks inline scripts, give the queue line's script tag your nonce, or put the queue line in a script file you already load.

How do you pass a visitor's cookie choice?

The chat records visits with Microsoft Clarity, including what visitors type, to help improve the service. If your website asks visitors about cookies, send their answer to the chat:

window.AIChatbot('consent', { analytics: false });

• Send analytics: true when the visitor accepts analytics cookies and analytics: false when they decline. Any value other than true counts as a decline.
• Until your website sends a choice, the chat records the visit.
• Send the choice on every page, in the same page load as the install code, so a visitor who declined is never recorded. The chat does not remember the choice between pages.
• When the visitor changes their mind, send the new choice; the chat passes it to Clarity straight away.

Most cookie banners can run your code with the saved choice when a page loads and again when the visitor saves a new choice; call window.AIChatbot('consent', ...) from both. The same code with its queue line, ready to copy, is under "Visitor recording and cookie choice" on the Website chat page under Channels in your dashboard.

How do you link chats to signed-in customers?

When a customer is signed in to your website, the chat can follow them: the same customer gets the same chat history on every device, and your team sees the name and email you send in the Inbox.

Keep the secret key on your server. When you create an install code, the dashboard shows the "Secret key for signed-in customers" once. Store it with your other server secrets and never put it in website code.

Sign the customer's ID on your server. userHash is the HMAC-SHA256 of the customer's ID with the secret key, written as lowercase hex. In Node.js:

import { createHmac } from 'node:crypto';

const userHash = createHmac('sha256', process.env.AICHATBOT_IDENTITY_SECRET).update(customerId).digest('hex');

Send the identity on every page where the customer is signed in, in the same page as the install code:

<script>
  window.AIChatbot=window.AIChatbot||function(){(window.AIChatbot.q=window.AIChatbot.q||[]).push(arguments)};
  window.AIChatbot('identify', {
    externalId: 'CUSTOMER_ID',
    userHash: 'USER_HASH_FROM_YOUR_SERVER',
    name: 'Lan Nguyen',
    email: 'lan@example.com'
  });
</script>

• When userHash does not match, the chat ignores the identity, opens as an anonymous visitor and writes [aichatbot] identify rejected to the browser console.
• name and email sent without externalId and userHash are saved as unverified contact details for the current visitor.
• A name longer than 80 characters or an email that is not valid is ignored.
• Send identify before the chat loads, as above, so the chat starts as the signed-in customer. If you call it later, for example right after the customer signs in without a page load, the chat links the current visitor to the customer; when that customer has chatted while signed in before, their earlier history appears from the next page load.

What should happen when a customer signs out?

Call reset when the customer signs out, so the next person on that browser does not see their chat:

window.AIChatbot('reset');

reset makes the chat forget the visitor on this browser. A chat already open on the page keeps going until the next page load, so call reset just before your sign-out redirect, or once on the page the sign-out lands on; the chat then starts fresh as an anonymous visitor. Only call it at sign-out: calling it on every page starts a new anonymous chat each time and loses the visitor's history.

How do you open or close the chat from your own button?

window.AIChatbot('open');
window.AIChatbot('close');

open sent before the chat has loaded opens the chat as soon as it is ready. A button such as "Chat with us" can call window.AIChatbot('open') when it is clicked.

Which commands are there?

To set up the chat itself, see getting started; the security page explains how data is protected.