Skip to content

Widget JavaScript and identity

Control the widget from your page, listen to its events and verify signed-in users.

On this page

The embed script adds one global function, ikazebot(...). Your page can use it to open the chat, send a message, listen to what happens, carry out Run on your page actions, and tell the agent who a signed-in customer is.

Commands

js
ikazebot('open');            // open the chat panel
ikazebot('close');
ikazebot('toggle');
ikazebot('centerStage');     // open it large, centred over the page
ikazebot('hideBubble');      // hide the floating button (e.g. use your own)
ikazebot('showBubble');
ikazebot('sendMessage', 'Where is my order?');  // opens the chat and sends it

Example: open the chat from your own "Contact us" button.

html
<button onclick="ikazebot('open')">Chat with us</button>

Calling commands before the script has loaded

The embed script loads async, so it may not be ready when your code runs. Add this line above the snippet. Commands sent early are queued and run once the widget is ready:

html
<script>window.ikazebot=window.ikazebot||function(){(window.ikazebot.q=window.ikazebot.q||[]).push(arguments)}</script>

Events

js
ikazebot('on', 'ready',   () => console.log('chat loaded'));
ikazebot('on', 'open',    () => analytics.track('chat_opened'));
ikazebot('on', 'close',   () => {});
ikazebot('on', 'message', ({ role, content }) => console.log(role, content));
ikazebot('on', 'action',  ({ name, args }) => { /* a "Run on your page" action */ });

ikazebot('off', 'open', listener);   // stop listening

Handling "Run on your page" actions

When the agent uses a Run on your page action, your page receives an action event. Your code decides what to do; nothing runs unless you handle it.

js
ikazebot('on', 'action', ({ name, args }) => {
  if (name === 'open_cart') document.querySelector('#cart').click();
  if (name === 'apply_coupon') applyCoupon(args.code);
});

Identity verification

By default every visitor is anonymous, known only by a random id in their browser. If your site has signed-in customers, you can tell the agent who they are. They then find their conversations on any device, become contacts, and {{verifiedUser}} becomes true in procedures.

You must sign the user's id on your server, so nobody can pretend to be someone else.

  1. 1Customer signs in to your site
  2. 2Your server signs their idwith your identity secret
  3. 3Your page calls identify
  4. 4ikazebot checks the signature

1. Get your identity secret

On the agent's Deploy tab, under Identity verification, create the secret. Copy it at once; it is shown only once. Store it in your server's environment, for example IKAZEBOT_IDENTITY_SECRET. Never put it in your web page.

2a. Sign with HMAC (simplest)

On your server:

js
import { createHmac } from 'node:crypto';

const userHash = createHmac('sha256', process.env.IKAZEBOT_IDENTITY_SECRET)
  .update(user.id)
  .digest('hex');

In your page, for the signed-in user:

js
ikazebot('identify', { userId: user.id, userHash });

2b. Or sign a JWT (to pass attributes too)

Sign an HS256 JWT with the same secret and a user_id claim. exp and nbf are honoured. Other claims are kept only if their name matches a contact attribute you have declared; everything else is ignored.

js
import jwt from 'jsonwebtoken';

const token = jwt.sign(
  { user_id: user.id, plan: 'pro' },              // "plan" kept only if declared
  process.env.IKAZEBOT_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' },
);
js
ikazebot('identify', { token });

Rotating the secret

Replace the secret if it may have leaked. Visitors signed with the old one become anonymous at once, so deploy the new secret to your server at the same time.

Want only signed-in customers to use the chat? Turn on Only verified visitors in the widget's Behaviour settings.

Something not working as described here? See Troubleshooting.

Get started free — 50 credits a month