@olotalk/widget
v0.14.0
Published
The [Olotalk](https://olotalk.com) AI chat widget — a Svelte 5 component that mounts a RAG-powered, multilingual chat assistant into any web page via Shadow DOM.
Readme
@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-loaderinstead. 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/widgetUsage
import { createWidget } from '@olotalk/widget'
const widget = createWidget(document.body, {
widgetId: 'YOUR_WIDGET_ID',
config: widgetConfig, // fetched from /public/widgets/:id/config
theme: 'light',
placement: 'floating',
cssUrl: 'https://cdn.jsdelivr.net/npm/@olotalk/widget/dist/olotalk-widget.css',
// origin: 'https://your-bff.example.com', // self-hosters only —
// cloud builds bake in https://api.olotalk.com; dev falls back to
// window.location.origin
})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'When self-hosting the bundle for use with @olotalk/widget-loader, publish dist/version.json alongside the JS and CSS files so the loader can cache-bust asset URLs automatically.
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 | No | Base URL of your Olotalk API. Cloud builds bake in https://api.olotalk.com at build time; dev/self-host omits and the widget falls back to window.location.origin. Set this only when self-hosting the BFF on a different origin. |
| 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. Accepts any well-formed BCP-47 tag (e.g. "en", "fr", "en-CA", "vi", "ja"). When omitted, the widget resolves from a stored visitor preference, the page's <html lang>, the visitor's browser, then the operator's defaultLocale — bounded by the widget's supportedLocales. |
WidgetConfig shape
This is returned by the Olotalk API at /public/widgets/:id/config.
type WidgetConfig = {
tenantId: string
widgetId: string
displayName?: string // shown in the widget header; appears next to the logo when logoUrl is set
welcomeMessage?: string // greeting shown on the welcome screen
theme?: Record<string, any>
launcher?: {
logoUrl?: string // when set, the header shows the logo image + displayName side by side
position?: 'bottom-right' | 'bottom-left'
teaser?: {
enabled?: boolean
messages?: string[]
delayMs?: number
durationMs?: number
cooldownMs?: number
maxShowsPerSession?: number
}
}
// Suggested starter questions shown before the first message.
// Auto-generated from ingested content when not manually configured.
starters?: {
topics?: Array<{ label: string; questions?: string[] }>
questions?: string[]
}
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 }) => { ... })
widget.on('cta_click', ({ id, action, intent }) => { ... })
widget.on('lead_submit', ({ leadId, status, score }) => { ... })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/version.json | JSON | Build manifest used by the loader for cache-busting |
| dist/index.d.ts | TypeScript | Type definitions |
Features
- RAG-powered answers — responses grounded in your website's knowledge base, not generic LLM output
- Suggested starters — topic chips and question buttons auto-generated from ingested content; shown before the first message to guide visitors
- Human escalation — amber banner notifies visitors when the conversation is handed off to your team
- Multilingual — any BCP-47 locale supported.
en,fr,deship hand-translated dictionaries; other languages (e.g.vi,ja,ar,sw) get LLM-translated UI strings cached on the BFF. Operators declare their site'ssupportedLocalesonce; the widget auto-detects from the embedding page or browser. Visitors who type in a different supported language see an inline "Continue in {language}?" toast that swaps the entire chrome on accept (ADR 0050) - 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
- UTM + referrer attribution — first-touch UTM params and
document.referrerforwarded at session creation - 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