Widget JavaScript API
Open the chat from your own buttons, tell it who's signed in, pass page context to the AI and react to what happens in the conversation.
Installing
Paste the snippet from Web widget → Installation before </body>. To call the API before the script has loaded, add this stub above it; calls wait in a queue and run once the widget is ready:
<script>
window.iGentrix = window.iGentrix || function () { (window.iGentrix.q = window.iGentrix.q || []).push(arguments); };
</script>
<script src="https://www.igentrix.com/widget/YOUR_AGENT_ID/embed.js" defer></script>
Every method can be called as iGentrix('open') or, once loaded, iGentrix.open().
Methods
| Method | What it does |
|---|---|
open(), close(), toggle() | Opens or closes the chat window. |
show(), hide() | Shows or hides the widget entirely, e.g. when you use your own chat button. |
identify(user) | A signed-in user. Their details fill the lead, and the pre-chat contact form is skipped. |
setContext(data) | Page or cart data the AI can use in its answers, e.g. { page: "checkout", cartTotal: 499 }. Up to 4 KB. |
sendMessage(text) | Opens the widget and sends a message as the visitor. |
on(event, callback) | Subscribes to an event. Returns a function that unsubscribes. |
off(event, callback) | Unsubscribes. |
shutdown() | Call on logout: forgets the user and starts a new, anonymous session. |
Events
| Event | Data |
|---|---|
open, close | none |
message | { role, text, author } where role is user, assistant (the AI), agent (a team member) or system |
escalated | { status } when the conversation is handed to your team |
unread | { count } messages that arrived while the window was closed |
iGentrix('on', 'escalated', function () {
analytics.track('Chat handed to team');
});
document.querySelector('#help').addEventListener('click', function () {
iGentrix('open');
});
Identifying signed-in users
iGentrix('identify', {
externalId: 'user_123', // your own id for the user
name: 'Thandi Nkosi',
email: 'thandi@example.com',
phone: '+14155550123',
customFields: { plan: 'Gold' }, // keys of the agent's lead fields
userHash: '…' // see below
});
A lead is created (or updated, matched on externalId then email) when the conversation starts, and the AI knows who it's talking to.
Identity verification
Anyone can call identify() from the browser console, so sign it. In Web widget → Developers, generate an identity secret, keep it on your server, and send userHash = hex HMAC-SHA256 of the user's externalId (or email if you don't pass an id):
// Node.js
import { createHmac } from 'node:crypto';
const userHash = createHmac('sha256', process.env.IGENTRIX_IDENTITY_SECRET).update(user.id).digest('hex');
// or, with the npm package
import { userHash } from '@igentrix/widget/server';
$userHash = hash_hmac('sha256', $user->id, getenv('IGENTRIX_IDENTITY_SECRET'));
A wrong userHash is always refused. Turn on Require verification to refuse unsigned identify() calls too. Unverified identities still work when verification isn't required, but the AI is told not to rely on them for account-specific information.
npm package
npm install @igentrix/widget
import { loadIGentrix, iGentrix } from '@igentrix/widget';
await loadIGentrix({ agentId: 'YOUR_AGENT_ID' });
iGentrix.identify({ externalId: user.id, email: user.email, userHash });
const off = iGentrix.on('unread', ({ count }) => setBadge(count));
All methods are typed and safe to call during server rendering (they do nothing there).
React and Next.js
// app/layout.tsx (Next.js App Router)
import { IGentrixWidget } from '@igentrix/widget/react';
export default async function RootLayout({ children }) {
const user = await getCurrentUser(); // your auth
return (
<html>
<body>
{children}
<IGentrixWidget
agentId="YOUR_AGENT_ID"
user={user ? { externalId: user.id, name: user.name, email: user.email, userHash: user.igentrixHash } : null}
onEscalated={() => console.log('With the team')}
/>
</body>
</html>
);
}
Passing user={null} after logout calls shutdown(). Use the hook for your own button:
'use client';
import { useIGentrix } from '@igentrix/widget/react';
export function HelpButton() {
const { open, unread } = useIGentrix();
return <button onClick={open}>Help {unread > 0 && `(${unread})`}</button>;
}
