@kaiachain/kaia-chat-ui NPM

Kaia Chat UI

A simple chat UI component for people to use and import in their React codebase.

Installation

Install the package using npm:

npm install @kaiachain/kaia-chat-ui

Usage

Import the ChatbotWidget component and its CSS, then use it in your React application:

import { ChatbotWidget } from '@kaiachain/kaia-chat-ui';
import '@kaiachain/kaia-chat-ui/dist/kaia-chat-ui.css';

function App() {
  return (
    <div>
      <ChatbotWidget
        apiBaseUrl="YOUR_BACKEND_API_URL"      // REQUIRED
        // agentId="YOUR_AGENT_ID"             // OPTIONAL
        // botName="YOUR_CHATBOT_NAME"         // OPTIONAL 
        // welcomeMessage="Hi, I am {botName}" // OPTIONAL
        // tncURL="YOUR_TERMS_URL"             // OPTIONAL
        // xLocation="44px"                    // OPTIONAL
        // yLocation="44px"                    // OPTIONAL
        // mobileXLocation="25px"              // OPTIONAL
        // mobileYLocation="25px"              // OPTIONAL
      />
    </div>
  );
}

export default App;

Props

The ChatbotWidget component accepts the following props:

Prop	Type	Default	Description
`apiBaseUrl`	string	Required	Base URL for the chatbot API
`agentId`	string	null	Optional ID to specify a specific agent/model
`botName`	string	"Kaia AI Agent"	Name of the chatbot
`welcomeMessage`	string	"Hello, I am {botName}, simply ask me a question! Anything is welcomed!"	Initial message shown when chat is opened. Add `{botName}` like shown in the example to dynamically add your Bot's name in the message.
`tncURL`	string	null	Optional URL for terms and conditions. When provided, shows a clickable "TnC applied" link that opens the URL in a new tab
`xLocation`	string	"44px"	X position of chat button (desktop)
`yLocation`	string	"44px"	Y position of chat button (desktop)
`mobileXLocation`	string	"25px"	X position of chat button (mobile)
`mobileYLocation`	string	"25px"	Y position of chat button (mobile)

Features

The ChatbotWidget includes the following features:

Online/offline status indicator - Shows real-time backend availability with visual indicators
Responsive design - Optimized for both desktop and mobile devices
Customizable positioning - Adjustable chat button placement for desktop and mobile
Welcome message - Personalized greeting with bot name placeholder support
Terms and conditions - Optional clickable TnC link that opens in a new tab
Markdown support - Rich text formatting for bot responses including tables, lists, and code blocks
Chat persistence - Automatic saving and restoration of chat history using localStorage
Transcript download - Export chat conversations as text files
Session management - End current chat and start fresh conversations
Real-time typing indicator - Shows when the bot is processing responses
Keyboard shortcuts - Enter to send, Shift+Enter for new lines
Touch device support - Enhanced mobile experience with touch-friendly interactions
Accessibility - ARIA labels and keyboard navigation support

Backend API Response Format

The component expects the backend API endpoint provided in apiBaseUrl (e.g., http://localhost:3001) to handle POST requests to the /message path, or /{agentId}/message if an agent ID is provided.

The request will have a JSON body containing the user's message and the room ID:

{
  "text": "User's message text",
  "roomId": "unique_room_identifier"
}

The endpoint should respond with a JSON object containing a success flag and an array of responses, where the first element contains the bot's reply text:

{
  "success": true,
  "data": [
    { "text": "Bot's response text" }
  ]
}

If an error occurs, the response might look like:

{
  "success": false,
  "data": "Error message or details"
}

Chat Persistence

The component automatically saves chat history to the browser's localStorage, including:

Room ID for maintaining conversation context
Complete message history between user and bot
Session restoration on page reload

Chat data is cleared when using the "End Chat" option from the options menu.

Supported Markdown Elements

The chatbot supports rich text formatting in responses, including:

Text formatting: Bold, italic, inline code
Headings: H1 through H6
Lists: Ordered and unordered lists
Links: Clickable hyperlinks
Tables: Structured data display
Code blocks: Syntax-highlighted code snippets
Paragraphs: Standard text formatting

Health Check Endpoint

The component periodically checks a /health endpoint (relative to apiBaseUrl) using a GET request to verify the server's status and update the chat widget's online indicator. This endpoint is required for the component to correctly display the backend status. It must respond with the following JSON when the server is healthy: