@ngn-net/chatbot

Embeddable React chat widget for AI assistants and support workflows — SSE streaming, conversation history, theming, and email capture. Works with React 18 or 19.

Features

• Streaming replies over Server-Sent Events
• Conversation history (list, open, rename)
• Message feedback (thumbs up / down)
• Light, dark, and system theming via CSS variables
• Optional in-widget email capture (persisted to localStorage)
• TypeScript-first public API

Installation

npm install @ngn-net/chatbot

import { initializeChatComponent, NGNChatBot } from "@ngn-net/chatbot";
import "@ngn-net/chatbot/dist/style.css";

initializeChatComponent({
  apiKey: "your-api-key",
  clientId: "your-client-id",
  baseUrl: "https://api.example.com",
  projectId: 123,
});

export function App() {
  return (
    <div style={{ height: "100vh" }}>
      <NGNChatBot />
    </div>
  );
}

Configuration

Call initializeChatComponent once before rendering NGNChatBot.

| Option | Type | Required | Description | | --- | --- | --- | --- | | apiKey | string | Yes | Sent as the api_key request header. | | clientId | string | Yes | Sent as the client_id request header. | | baseUrl | string | Yes | Base URL for all API requests. | | projectId | number | Yes | Scopes all requests to this project. | | userEmail | string | No | Skips the email prompt. Falls back to a saved localStorage value when omitted. |

Auth is API key + client key only. Every request includes api_key and client_id.

Component props

<NGNChatBot
  mode="system"
  theme={{ "ngnchat-primary": "#2563eb" }}
  darkTheme={{ "ngnchat-primary": "#60a5fa" }}
  className="h-full"
/>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | theme | Partial<Theme> | — | Light palette overrides. | | darkTheme | Partial<Theme> | — | Dark palette overrides. | | mode | "light" \| "dark" \| "system" | "system" | Active palette. A dark class on an ancestor forces dark mode. | | className | string | — | Container class name. |

Theming

Tokens are CSS custom properties. Color values accept any CSS color (#hex, rgb(), hsl(), named colors, or R, G, B triplets). Non-color tokens take raw CSS values.

| Token | Notes | | --- | --- | | ngnchat-background / ngnchat-foreground | Page / text | | ngnchat-surface / ngnchat-surface-foreground | Panels | | ngnchat-primary / ngnchat-primary-foreground | Primary actions | | ngnchat-secondary / ngnchat-secondary-foreground | Secondary UI | | ngnchat-muted / ngnchat-muted-foreground | Subtle text / fills | | ngnchat-accent / ngnchat-accent-foreground | Accents | | ngnchat-destructive / ngnchat-destructive-foreground | Errors / danger | | ngnchat-success / ngnchat-success-foreground | Success | | ngnchat-border / ngnchat-ring | Borders / focus | | ngnchat-radius-md | Border radius | | ngnchat-shadow-sm / ngnchat-shadow-md | Shadows | | ngnchat-font | Font family |

Email collection

Before the first message, the widget prompts for an email and stores it in localStorage. Dismissing without a value re-prompts on the next send. Pass userEmail at init to skip the prompt.

Backend API contract

Your backend must expose:

| Method | Path | Purpose | | --- | --- | --- | | POST | /chat/stream | Chat message streaming (SSE) | | GET | /chat/history | List conversations | | GET | /chat/conversation/:id | Conversation details | | PATCH | /chat/conversation/:id | Rename conversation | | POST | /chat/message/:id/feedback | Record message feedback |

Auth headers

api_key: <apiKey>
client_id: <clientId>

Stream request body

{
  "message": "Hello",
  "userEmail": "[email protected]",
  "projectId": 123,
  "conversationId": 456
}

conversationId is omitted on the first message of a new conversation.

SSE events

Each data: line is JSON with a type and data payload:

| type | data | Meaning | | --- | --- | --- | | chunk | string | Assistant text delta | | messageId | number | Persisted assistant message id | | conversationId | number | Conversation id (new threads) | | title | string | Generated conversation title | | error | string | Stream error message |

Exports

import {
  initializeChatComponent,
  getChatConfig,
  NGNChatBot,
  DEFAULT_ENDPOINTS,
  defaultParseEvent,
} from "@ngn-net/chatbot";

import type {
  ChatComponentConfig,
  ChatEndpoints,
  ChatStreamEvent,
  ChatMessageDto,
  MessageFeedback,
  NGNChatBotProps,
  Theme,
} from "@ngn-net/chatbot";

License

MIT