Embed script & control

How the loader works

Every Qalyb widget you create in Deploy is backed by a secret widget token. The token connects one agent to your site. The public loader at https://cdn.qalyb.ai/widget.js reads that token, fetches the widget's saved appearance and behavior, mounts the UI, and exposes a control API on window.Qalyb.

The bundle is the @qalyb/widget package — a tiny Preact app. It does two things on load: it auto-mounts if it finds a script tag carrying data-qalyb-token, and it attaches the window.Qalyb object so you can drive the widget yourself.

1. Drop in the script tag (recommended)

The simplest install: paste one <script> tag before </body>. On DOMContentLoaded the loader finds the tag by its data-qalyb-token attribute, reads every other data-qalyb-* attribute as config, and mounts the widget — no further code needed.

<script
  src="https://cdn.qalyb.ai/widget.js"
  data-qalyb-token="wgt_yourfulltoken"
  data-qalyb-mode="chat"
  data-qalyb-primary-color="#5c5cf6"
  data-qalyb-title="Acme Support"
  data-qalyb-subtitle="Online now"
  data-qalyb-launcher-label="Ask Acme"
  data-qalyb-launcher-variant="pill"
></script>

Copy a pre-filled version of this snippet (with your appearance already baked in) from the Embed tab of the widget editor.

app.qalyb.ai/channels/widgets/[id]

Common data-qalyb-* attributes

2. Or initialize from JavaScript

If you prefer to control mounting yourself — for example, only after a consent banner is accepted — load widget.js without the data-qalyb-token attribute and call window.Qalyb.init() when you're ready. The config object takes the same fields as the data attributes, in camelCase.

<script src="https://cdn.qalyb.ai/widget.js"></script>
<script>
  window.Qalyb.init({
    token: "wgt_yourfulltoken", // your full widget token
    mode: "chat",
    theme: "light",
    position: "bottom-right",
    primaryColor: "#5c5cf6",
    accentColor: "#06B6D4",
    borderRadius: 16,
    title: "Acme Support",
    subtitle: "Online now",
    welcomeMessage: "Hi! How can we help?",
    autoOpen: false,
    surface: "classic",
    launcherLabel: "Ask Acme",
    launcherIcon: "chat",
    launcherVariant: "pill",
  });
</script>

3. Or use the React component

For React and Next.js apps, import QalybWidget from the @qalyb/widget package. It mounts on render, unmounts on cleanup, and accepts the same config as props plus lifecycle callbacks (covered below).

import { QalybWidget } from '@qalyb/widget';

export function App() {
  return (
    <QalybWidget
      token="wgt_yourfulltoken" // your full widget token
      mode="chat"
      theme="light"
      position="bottom-right"
      primaryColor="#5c5cf6"
      accentColor="#06B6D4"
      borderRadius={16}
      title="Acme Support"
      subtitle="Online now"
      launcherLabel="Ask Acme"
      launcherIcon="chat"
      launcherVariant="pill"
      autoOpen={false}
      surface="classic"
      onOpen={() => console.log('widget opened')}
      onMessage={(m) => console.log('message', m)}
      onCallEnd={(s) => console.log('call ended', s)}
    />
  );
}

The control API

Once widget.js has loaded, window.Qalyb exposes these methods. They all act on the single mounted widget instance.

Open, close, toggle

The most common pattern is wiring the widget to a button you already have on the page — a "Need help?" link in your nav, a hero CTA, or a footer item. Hide the built-in launcher (set hideLauncher on the embed) and drive everything yourself.

// The launcher button on your page
const button = document.querySelector('#open-support');

button.addEventListener('click', () => {
  window.Qalyb.open();
});

// Toggle from anywhere
document.querySelector('#help-link')?.addEventListener('click', () => {
  window.Qalyb.toggle();
});

// Close it when the user finishes a flow
window.Qalyb.close();

Send a message programmatically

sendMessage() posts a message as if the visitor typed it and resolves with the agent's ChatMessage reply (id, role, content, timestamp). Use it to seed a conversation from a button — for example, a "Track my order" CTA that opens the widget and asks the question for the user.

// Send a message on the visitor's behalf (chat-enabled widgets).
// Resolves with the agent's reply.
try {
  const reply = await window.Qalyb.sendMessage('What are your opening hours?');
  console.log(reply.role, reply.content); // "assistant", "We're open 9–6 ..."
} catch (err) {
  console.error('Send failed:', err.message);
}

Start and end voice

For Voice Widgets, startVoice() begins a session and endVoice() hangs up. This lets a single "Talk to us" button on your page launch the agent's voice orb.

// Start a voice session (voice-enabled widgets only).
const callBtn = document.querySelector('#talk-to-us');
callBtn.addEventListener('click', () => {
  window.Qalyb.startVoice();
});

// End the current voice session
window.Qalyb.endVoice();

Tear down and remount

In single-page apps, call destroy() on route changes where the widget shouldn't appear, and init() again where it should. (The React component handles this for you automatically on mount and unmount.)

// Tear the widget down (e.g. on a single-page-app route change)
window.Qalyb.destroy();

// Re-create it later with fresh config
window.Qalyb.init({ token: 'wgt_yourfulltoken', mode: 'chat' });

Events & lifecycle callbacks

The React QalybWidget component accepts callback props that fire as the visitor interacts. These are the events Qalyb surfaces — use them for analytics, support handoffs, or custom UI:

import { QalybWidget } from '@qalyb/widget';

export function SupportWidget() {
  return (
    <QalybWidget
      token="wgt_yourfulltoken"
      mode="voice"
      surface="voice-widget"
      onOpen={() => track('widget_opened')}
      onClose={() => track('widget_closed')}
      onMessage={(message) => track('widget_message', { role: message.role })}
      onCallStart={() => track('voice_call_started')}
      onCallEnd={(summary) =>
        track('voice_call_ended', {
          sessionId: summary.sessionId,
          duration: summary.duration,
          status: summary.status,
        })
      }
      onError={(error) => report(error)}
    />
  );
}

Restricting where the widget can load

Each widget token has an Allowed Domains list, set in the dashboard. Qalyb enforces it server-side: the request's Origin/Referer hostname must match an entry (exact or subdomain) or the API rejects it with Origin not allowed for this widget. Leaving the list empty allows any origin — fine for testing, but scope it to your real domains before launch so a leaked token can't be embedded elsewhere.

Putting it together

Related guides

• Create & embed a widget — the dashboard flow for tokens, appearance, and the Embed tab.
• Web widget channel — chat vs. voice widgets, customization, and how the embedded runtime behaves.