@olotalk/widget

The Olotalk AI chat widget — a Svelte 5 component that mounts a RAG-powered, multilingual chat assistant into any web page via Shadow DOM.

Most users should use @olotalk/widget-loader instead. It handles config fetching, browser compatibility, and dynamic loading with a single <script> tag. Use this package directly only if you need low-level control over widget instantiation.

Install

npm install @olotalk/widget

Usage

import { createWidget } from '@olotalk/widget'

const widget = createWidget(document.body, {
  widgetId: 'YOUR_WIDGET_ID',
  origin: 'https://api.olotalk.com',
  config: widgetConfig,   // fetched from /public/widgets/:id/config
  theme: 'light',
  placement: 'floating',
  cssUrl: 'https://cdn.jsdelivr.net/npm/@olotalk/widget/dist/olotalk-widget.css',
})

CSS

The widget loads its styles via a <link> injected inside the Shadow DOM. The CSS URL will be resolved automatically from the widget config in a future release. Until then, pass it explicitly via cssUrl or import the stylesheet manually:

import '@olotalk/widget/style.css'

createWidget(mount, options)

Mounts the widget into the given element and returns a WidgetInstance.

Options

| Option | Type | Required | Description | |---|---|---|---| | widgetId | string | Yes | Your widget ID. | | origin | string | Yes | Base URL of your Olotalk API. | | config | WidgetConfig | Yes | Widget configuration object from the API. | | theme | "light" | "dark" | object | No | Color scheme or custom theme overrides. | | placement | "floating" | "embedded" | No | Floating launcher or inline panel (default: "floating"). | | cssUrl | string | No | URL of the widget stylesheet. Will be resolved automatically from the widget config in a future release. | | locale | string | No | Force a display language: "en" | "fr" | "en-CA" | "fr-CA". |

WidgetConfig shape

This is returned by the Olotalk API at /public/widgets/:id/config.

type WidgetConfig = {
  tenantId: string
  widgetId: string
  displayName?: string
  theme?: Record<string, any>
  launcher?: {
    logoUrl?: string
    position?: 'bottom-right' | 'bottom-left'
    teaser?: {
      enabled?: boolean
      messages?: string[]
      delayMs?: number
      durationMs?: number
      cooldownMs?: number
      maxShowsPerSession?: number
    }
  }
  allowedDomains?: string[]
  features?: {
    domRagEnabled?: boolean
    siteRagEnabled?: boolean
    citationsEnabled?: boolean
    streamingEnabled?: boolean
  }
  security?: {
    rateLimitPer5Min?: number
    captchaMode?: boolean
  }
  privacy?: {
    piiRedaction?: boolean
    retentionDays?: number
  }
}

WidgetInstance API

widget.open()                          // Open the chat panel
widget.close()                         // Close the chat panel
widget.setTheme(theme)                 // Change theme at runtime
widget.destroy(opts?: { outro?: boolean }) // Unmount and remove from DOM

// Subscribe to events
widget.on('ready', ({ widgetId }) => { ... })
widget.on('open',  () => { ... })
widget.on('close', () => { ... })
widget.on('send',  ({ text }) => { ... })

Distribution files

| File | Format | Use case | |---|---|---| | dist/olotalk-widget.js | ESM | Dynamic import() from CDN or bundler | | dist/olotalk-widget.iife.js | IIFE | Legacy browsers (<script> tag, no module support) | | dist/olotalk-widget.css | CSS | Styles loaded inside the Shadow DOM | | dist/index.d.ts | TypeScript | Type definitions |

Features

• RAG-powered answers — responses grounded in your website's knowledge base, not generic LLM output
• Multilingual — en and fr built-in (with en-CA / fr-CA variants); same-language retrieval with cross-language fallback
• Streaming — real-time text generation for a conversational feel
• Citations — optionally surfaces source URLs alongside answers
• Proactive teasers — configurable delay-based messages to prompt engagement
• Shadow DOM isolation — widget styles never bleed into the host page
• Anonymous by default — no visitor login required
• Domain whitelisting — control which sites can embed the widget
• Privacy controls — optional PII redaction and configurable data retention

License

MIT © Olotalk