Chat Widget SDK

The Chat Widget SDK embeds a floating chat assistant into any page. In knowledge mode it answers strictly from the sources you trained it on (URLs, workspace files, folders) and refuses to invent answers. It is designed for public sites: the browser never holds a long-lived credential.

Loading the advanced bundle does not enable its features. They are controlled by the widget settings you configure in the dashboard, so you can change behaviour without redeploying your site.

The simplest integration is a single script tag:

<script src="https://cdn.thinkflyflow.com/chat-widget/thinkflyflow-chat-advanced.min.js" async></script>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    ThinkFlyFlow.init({
      mode: 'knowledge',
      widgetId: '<your-widget-id>',
      apiBaseUrl: 'https://api.laureljar.com/api/v2',
      getToken: async function () {
        // Your backend mints a short-lived visitor token (see Authentication)
        const res = await fetch('/api/widget-token', { method: 'POST' })
        const data = await res.json()
        return { token: data.token, features: data.features, tier: data.tier }
      },
    })
  })
</script>

The SDK can also be imported as ESM if you bundle your site: import { ThinkFlyFlow } from '@thinkflyflow/chat-widget'. A React wrapper is shown in the repository examples.

Where the script lives.We publish the bundles as static files. Serve them from your own domain if you prefer (copy the file into your project's public/ directory and point script.src at it). Serving from your own origin avoids third-party script CSP complications.

A browser embed must never carry a long-lived secret. The SDK takes a short-lived visitor token minted by your backend. The SDK never mints or stores credentials itself.

The flow is three steps:

// POST /api/widget-token  - runs server-side only
export async function POST() {
  const res = await fetch('https://api.laureljar.com/api/v2/widgets/token/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      public_key: process.env.WIDGET_PUBLIC_KEY,
      secret_key: process.env.WIDGET_SECRET_KEY,
      origin: 'https://your-site.com',
    }),
  })
  const body = await res.json()
  // Pass through features + tier so dashboard settings drive the widget.
  return Response.json({
    token: body.data.token,
    features: body.data.features,
    tier: body.data.tier,
  })
}

Pass features and tier through. If your endpoint drops them, the widget falls back to defaults and your dashboard toggles will appear to do nothing.

Tokens expire (default one hour). When a request returns 401 the SDK calls getToken() again automatically and retries once, so you never need to manage expiry yourself.

All options are passed to ThinkFlyFlow.init(config).

Features are resolved with this priority (highest first): init().features, then the flags returned by getToken(), then tier defaults, then hard defaults (everything off).

Operate features from the dashboard, not the site. Set your tier and per-feature toggles in the widget settings so changes take effect on every embedded page on the next load. Hardcoding features in init() overrides the server and makes the dashboard toggles appear broken.

Quick replies and handoff are never on by default, even on the advanced tier. They turn on only when you configure them, so a widget does not accidentally show a handoff form you did not ask for.

In knowledge mode the widget answers only from the content you trained it on. Train it in the dashboard by adding URLs, workspace files or folders, then run ingestion.

The widget answers with the visitor token only, so it works for anonymous visitors on third-party sites with no account and no login.

Owners control the widget's appearance from the dashboard (the widget detail page), so branding can change without editing the embedding site. Settings are delivered to the widget with the visitor token.

You can also set these per page through init(), which takes precedence over the dashboard. This is useful for a different logo on a landing page, for example:

ThinkFlyFlow.init({
  mode: 'knowledge',
  widgetId: '<your-widget-id>',
  getToken: mint,
  branding: {
    logoUrl: 'https://your-site.com/logo.png',
    primaryColor: '#0ea5e9',
    mode: 'light',
    hideAttribution: true,
  },
})

Hiding the attribution is available on white-label plans. If it is not enabled for your widget the footer stays, and the rest of your branding still applies.

Each widget can use a different model. Pick one from the dashboard (the widget page) or leave it on the platform default. The catalogue lists each model with a short description of what to expect and a relative cost hint, so you can trade quality against cost per widget.

If a model fails, visitors are still answered. The platform automatically falls back through its provider chain and then a free tier, so an outage never leaves a visitor without a reply. When this happens you are emailed, and the widget page shows a notice with the model that actually served the reply.

Alerts are throttled to one per model per hour so a prolonged outage does not flood your inbox. Only workspace owners and admins can change the model.

ThinkFlyFlow.init({
  // ...config
  model: 'deepseek-chat', // optional; omit to use the dashboard setting
})

ThinkFlyFlow.init({
  theme: { primaryColor: '#ce42f5', mode: 'light' }, // or 'dark'
  position: 'bottom-right',
  title: 'Ask Laurel Jar',
  greeting: 'Hi! Ask me anything.',
  logoUrl: '/logo.png',
  brandUrl: 'https://your-site.com',
})

The widget renders inside a shadow DOM, so your page CSS cannot leak in and the widget CSS cannot leak out. It sizes itself with dynamic viewport units and respects safe-area insets, so it does not clip on mobile browsers with collapsing toolbars.

Subscribe with on(event, handler). It returns an unsubscribe function.

ThinkFlyFlow.on('ready', () => {})
ThinkFlyFlow.on('open', () => {})
ThinkFlyFlow.on('close', () => {})
ThinkFlyFlow.on('message', ({ role, content }) => {})
ThinkFlyFlow.on('error', ({ message, status, code }) => {})

When handoff is enabled, a visitor can ask for a human. Their name, email, message and the conversation transcript are recorded so nothing is lost even if email delivery fails. Requests appear in your widget inbox.

You can also take over any conversation without the visitor asking. While a team member is handling it, the visitor sees that a team member is responding and your replies appear in their chat. Whether the AI keeps answering during takeover is a per-widget setting (aiPausedDuringTakeover); a human is never the default responder.

Replies are delivered by short polling, which keeps the integration simple and works through restrictive networks. The transport is isolated inside the SDK, so it can be upgraded without changing your integration.