Chat Widget Overview

The Nexus Chat Widget is a lightweight, embeddable component that brings AI-powered chat to your website or application.

Features

Core Capabilities

Floating Button Mode - Non-intrusive chat button in the corner
Embedded Mode - Integrate chat directly into your page layout
Customizable Themes - Match your brand with colors, fonts, and styling
Multi-language Support - Voice input in multiple languages
Rich Content - Support for markdown, HTML, images, and links
Feedback System - Collect user ratings and feedback
Event Tracking - Monitor all user interactions

Advanced Features

Message Interceptor - Intercept and handle messages before they reach the backend
Voice Input - Speech-to-text for hands-free interaction
Text-to-Speech - Audio output for accessibility
Session Management - Persistent conversations across page loads
Agent Handover - Seamless transition to human agents
Custom Disclaimers - Display terms, privacy policies, or warnings

Installation

npm Package (Recommended)

Install the widget via npm, yarn, or pnpm:

# npm
npm install @knowbl_ai/nexus-chat

# yarn
yarn add @knowbl_ai/nexus-chat

# pnpm
pnpm add @knowbl_ai/nexus-chat

ES Module Import

import { initWidget } from "@knowbl_ai/nexus-chat";

const widget = initWidget({
  experienceId: "your-experience-id",
  apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",
});

// Control the widget programmatically
widget.open();
widget.close();
widget.toggle();

CommonJS Require

const { initWidget } = require("@knowbl_ai/nexus-chat");

const widget = initWidget({
  experienceId: "your-experience-id",
  apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",
});

// Control the widget programmatically
widget.open();
widget.close();
widget.toggle();

TypeScript

The package includes built-in TypeScript definitions:

import type { ChatEvent, WidgetAPI, WidgetConfig } from "@knowbl_ai/nexus-chat";
import { initWidget } from "@knowbl_ai/nexus-chat";

// Full type safety for configuration
const config: WidgetConfig = {
  experienceId: "your-experience-id",
  apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",
  features: {
    voice: true,
    feedback: true,
  },
};

// Typed widget API
const widget: WidgetAPI = initWidget(config);

// Type-safe event handling
widget.on("message", (event: ChatEvent) => {
  if (event.kind === "message") {
    console.log("Message received:", event.content);
  }
});

CDN

For quick prototyping, include the widget script directly in your HTML:

<script src="https://nexus-api.uat.knowbl.com/api/widget/widget.umd.js"></script>

Self-Hosted (Legacy)

Note: For new projects, we recommend using npm or CDN installation.

Download the widget files and host them on your own server:

Download Widget Files (.tar.gz)

Or download individually via command line:

# Download widget files
curl -O https://nexus-api.uat.knowbl.com/api/widget/widget.umd.js

Then reference them in your HTML:

<script src="/path/to/widget.umd.js"></script>

Basic Usage

<!doctype html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome to my website</h1>

    <!-- Load widget script -->
    <script src="https://nexus-api.uat.knowbl.com/api/widget/widget.umd.js"></script>

    <!-- Initialize widget -->
    <script>
      window.NexusChatWidget.init({
        experienceId: "your-experience-id",
        apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",
        theme: "light",

        // Comprehensive styling example
        window: {
          header: {
            title: "Support Chat",
            backgroundColor: "#003d7a",
            textColor: "#ffffff",
            padding: "1rem",
          },
        },
        bubbles: {
          user: {
            backgroundColor: "#ffffff",
            textColor: "#003d7a",
            border: "1px solid #003d7a",
            borderRadius: "18px",
          },
          assistant: {
            backgroundColor: "#f5f5f5",
            textColor: "#000000",
            borderRadius: "18px",
          },
        },
        input: {
          borderColor: "#005a9c",
          borderWidth: "1px",
          borderRadius: "8px",
          padding: "0.75rem 1rem",
          gap: "0.5rem",
          sendButton: {
            color: "#003d7a",
          },
        },
      });
    </script>
  </body>
</html>

<div id="chat-container" style="width: 400px; height: 600px"></div>

<script src="https://nexus-api.uat.knowbl.com/api/widget/widget.umd.js"></script>

<script>
  const container = document.getElementById("chat-container");

  window.NexusChatWidget.init({
    experienceId: "your-experience-id",
    apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",
    theme: "light",
    embedded: true,
    container: container,
  });
</script>

Configuration

The widget supports extensive configuration options. See the Configuration Guide for complete details.

Common Options

window.NexusChatWidget.init({
  // Required
  experienceId: "your-experience-id",
  apiUrl: "https://nexus-api.uat.knowbl.com/api/v2",

  // Appearance
  theme: "light", // or 'dark'

  // Button configuration
  button: {
    position: "bottom-right",
    text: "Chat with us",
    backgroundColor: "#007bff",
    textColor: "#ffffff",
  },

  // Window configuration
  window: {
    width: "384px",
    height: "600px",
    header: {
      title: "Support Chat",
      showCloseButton: true,
    },
  },

  // Messages
  messages: {
    welcomeMessage: "Hello! How can I help you today?",
    errorMessage: "Sorry, something went wrong. Please try again.",
  },

  // Features
  features: {
    voice: { enabled: true },
    tts: { enabled: false },
    feedback: { enabled: true },
  },
});

Next Steps

Configuration Guide - All configuration options
Events System - Track widget interactions
Message Interceptor - Custom message handling
Interactive Demos - See live examples

Browser Support

The Nexus Chat Widget supports all modern browsers:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

The widget is optimized for fast loading and minimal impact on your page performance.