Our most capable AI model is now on the Scale plan. See plans

Docs/Widget JavaScript APIREST API

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

MethodWhat 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

EventData
open, closenone
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>;
}