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
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.
<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:
<script>window.ikazebot=window.ikazebot||function(){(window.ikazebot.q=window.ikazebot.q||[]).push(arguments)}</script>
Events
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.
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.
- 1Customer signs in to your site
- 2Your server signs their idwith your identity secret
- 3Your page calls identify
- 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:
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:
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.
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' },
);
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.
Related
- Website widget and help pagePut an agent on your site with one script tag, style it and set its guardrails.
- Contacts and leadsYour customers, the attributes you keep about them, and the leads agents collect.
- ActionsLet the agent do things: call your API, collect leads, hand over to a person, show buttons.
Something not working as described here? See Troubleshooting.