qkit-chatbot-widget

A premium, lightweight, standalone embeddable chatbot widget runtime package for the QKIT Nexus platform. It provides a real-time chat interface that can be embedded on any website, supporting both AI-powered automated conversations and smooth transition to live human agents (handoff).

Features

• Multi-modal Integration: Supports modern ES Modules (ESM) imports and standalone browser script tags (IIFE).
• Real-time Communication: Built on WebSockets (Socket.IO) for instant message delivery, agent typing indicators, and real-time handoff status updates.
• Rich Interactive UI: Features modern glassmorphism options, fully responsive layout, dynamic theme variables (colors, border-radius, font sizes, custom welcome message, custom buttons/avatars).
• Inline Lead Capture: Automatically triggers contact forms depending on the user sentiment and contact intents.
• Smart Attachment Control: Fully supports file attachments, securely toggling uploads based on session state (restricted when chatting with AI, automatically enabled when talking to a live agent).
• Lightweight & High Performance: Zero frame dependencies (React/Vue/Angular), compiles to a lightweight, standalone 98kb bundle.

Installation

ESM (NPM/Yarn/PNPM)

Install the package using your favorite package manager:

npm install qkit-chatbot-widget
# or
yarn add qkit-chatbot-widget
# or
pnpm add qkit-chatbot-widget

Import and initialize the widget in your application entry file:

import { QKitChatbot } from "qkit-chatbot-widget";

QKitChatbot.mount({
  deployToken: "dt_your_deploy_secret_token",
  apiBaseUrl: "https://api.nexus.qkit.vn", // Optional: defaults to QKIT production endpoint
  locale: "vi", // Optional: "vi" | "en" | "he", defaults to visitor browser language
  metadata: {
    userId: "user_991823",
    plan: "premium",
  }
});

Note: The npm package is a thin loader. Only this small loader is bundled into your build; the widget core is fetched from the CDN on first mount(), so you always run the latest core even from an older install. Trade-offs: the first mount makes one network request for the core, and the client site's CSP must allow scripts from the CDN host. To override where the core is loaded from (e.g. self-hosting), set QKitChatbot.coreUrl before calling mount().

CDN / Standalone Script Tag (IIFE)

Add the loader script to your HTML document. It is a tiny (~1 KB) bootstrap: it automatically initializes the widget if a data-deploy-token is present, then fetches the latest core bundle from the CDN at runtime. Because the loader always pulls the latest core, hotfixes reach embedded sites automatically — visitors just reload the page, no re-embedding required.

<script 
  src="https://unpkg.com/qkit-chatbot-widget@latest/dist/loader.iife.js" 
  data-deploy-token="dt_your_deploy_secret_token"
  data-api-base-url="https://api.nexus.qkit.vn"
  data-locale="vi"
  async
></script>

Auto-update model. Use @latest (always newest) or @^0.1 (only patch releases within the 0.1.x line, safer) — never a fully pinned version like @0.1.13, which unpkg serves immutably and would freeze the widget forever. The loader is what gets cached by the client; the heavy core is loaded fresh from @latest on each mount, so publishing a new patch propagates to everyone.

Requires the client's Content-Security-Policy (if any) to allow scripts from the CDN host (e.g. script-src https://unpkg.com).

Alternatively, load the loader without auto-initialization and call mount() manually:

<script src="https://unpkg.com/qkit-chatbot-widget@latest/dist/loader.iife.js"></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    if (window.QKitChatbot) {
      window.QKitChatbot.mount({
        deployToken: "dt_your_deploy_secret_token",
        apiBaseUrl: "https://api.nexus.qkit.vn"
      });
    }
  });
</script>

API Reference

QKitChatbot.mount(options)

Mounts and renders the chatbot widget to the target element or body.

Options Parameters

| Parameter | Type | Required | Default | Description | | :--- | :--- | :---: | :--- | :--- | | deployToken | string | Yes | — | The deployment token generated in the QKIT Nexus Dashboard. | | apiBaseUrl | string | No | "https://api.nexus.qkit.vn" | Base URL of the QKIT Nexus API services. | | targetElement | string | HTMLElement | No | document.body | Element or CSS selector where the widget will be mounted. If not specified, mounts as a floating window. | | visitorSessionCode | string | No | Auto-generated UUID | Persistent identifier of the visitor. Saved in localStorage to resume transcripts across tabs. | | locale | string | No | Browser language | Language of the widget interface. Supported: "vi", "en", "he". | | metadata | Record<string, unknown> | No | {} | Custom payload (e.g. customer data, tags, current page context) attached to the session. |

QKitChatbot.destroy()

Disconnects the active Socket.IO connection, tears down event listeners, and completely removes all chatbot widget UI components from the DOM.

QKitChatbot.destroy();

QKitChatbot.isOpen()

Returns a boolean indicating whether the chatbot widget window is currently open (visible to the visitor).

const isVisible = QKitChatbot.isOpen(); // true | false

QKitChatbot.setUnreadBadge(count)

Programmatically updates the red unread message count badge on the floating toggle button.

• count (number): The unread message count. Set to 0 or negative to hide the badge.

QKitChatbot.setUnreadBadge(5);

QKitChatbot.setComposerDisabled(disabled)

Enables or disables the text input area, send button, and starter quick reply questions.

• disabled (boolean): If set to true, visitor inputs are locked.

QKitChatbot.setComposerDisabled(true); // Visitor cannot type messages

Customization and Theming

The widget automatically retrieves the chatbot's configuration during the bootstrap phase. You can customize the look and feel from the QKIT Nexus Dashboard, which applies the parameters directly on initialization:

• Colors: Customize the primary button background color, hover colors, text color, bot message bubble backgrounds, and user message bubble gradients.
• Branding: Supports custom welcome messages, custom launcher icons, and custom bot name/avatar assets.
• UX Layout: Enable or disable glassmorphism backdrop blur filters, border radiuses, box-shadow depth presets (none, soft, default, heavy), launcher diameter, and screen position offset metrics.

License

This project is licensed under the MIT License. Copyright © 2026 QKIT Software. All rights reserved.