@timely-chatbot/widget

Embed-ready chatbot widget for the timely-chatbot SaaS. Lit web component with multi-turn chat, citations, image/text attachments, page-context tool, region screenshot, reactions, reports, and inquiries, packaged as a single self-contained bundle (no peer dependencies required on the host).

Install

Option 1: <script> tag (CDN / direct host)

<script src="https://cdn.your-host/widget.js"></script>
<script>
  window.TimelyChatbot.init({
    apiKey: 'pk_xxx',
    apiBaseUrl: 'https://api.your-host',
    getAccessToken: async () => {
      const res = await fetch('/api/widget-jwt', { credentials: 'include' });
      const { jwt } = await res.json();
      return jwt;
    },
  });
</script>

Option 2: npm

pnpm add @timely-chatbot/widget

import { init } from '@timely-chatbot/widget';

init({
  apiKey: 'pk_xxx',
  apiBaseUrl: 'https://api.your-host',
  getAccessToken: async () => {
    const res = await fetch('/api/widget-jwt', { credentials: 'include' });
    const { jwt } = await res.json();
    return jwt;
  },
});

Modes

• Authenticated: provide getAccessToken callback that returns a host-signed JWT (use @timely-chatbot/widget-sdk on the server).
• Guest: omit getAccessToken, widget obtains an anonymous token via /widget/guest-jwt (project must have guest mode enabled).

Options

interface InitOptions {
  apiKey: string;
  apiBaseUrl?: string;
  getAccessToken?: () => Promise<string>;
  mountTo?: HTMLElement;
  position?: "bottom-right" | "bottom-left";
  /** Per-page override merged over the dashboard theme. */
  theme?: Partial<WidgetTheme>;
}

The widget renders as a floating launcher (bottom-right by default). The host project's theme/title/position is fetched from /widget/init.

Design

The widget ships two looks and picks one from the project theme (theme.design):

• classic: the original look. Used when the theme has no design, so sites that already embed the widget keep looking the same after an update.
• modern: brand-colored header with auto-contrast text, white answer cards, a rounded input with a round send button, a ⋯ menu, bottom-sheet dialogs, full-screen panel on mobile, and error cards with a retry button.

modern also puts a "+" button left of the input that opens a small capture menu (the visible screen and a dragged region, whichever captures are on; with both off there is no button), "문의 남기기" (leave an inquiry) at the top of the header menu, document-name source chips under answers (from the citations the server already sends), and reads two theme fields:

• headerSubtitle: text under the title. Omitted means "보통 몇 초 안에 답해요", an empty string hides it.
• suggestedQuestions: up to 4 question buttons on the first screen. They disappear once the visitor asks something.

After an answer the server may send a hint: FAQ questions to tap, and a "담당자에게 문의 남기기" chip when the answer was not found or the visitor asks for a person. The dashboard theme's notFoundHandoffEnabled: false drops the chip for not-found answers (it still shows when the visitor asks for a person).

In both designs, answer links open in a new tab, line breaks in the visitor's message are kept, answer attachments survive a page reload, and on mobile the panel stays above a large launcher or label.

New projects are created with design: "modern". Existing projects switch in the dashboard (위젯 테마 → 디자인). A host page can also force one, e.g. for testing:

TimelyChatbot.init({ apiKey: "pk_live_xxx", theme: { design: "modern" } });

Compatibility

• Browsers: modern (ES2020). Safari 14+, Chrome/Edge/Firefox latest.
• Bundle: single file with all deps inlined (lit, marked, dompurify, html2canvas).