Floater Chatbot - React NPM Package

A professional, AI-powered floating chat widget for React applications that integrates with RAG API endpoints for intelligent customer support.

Features

• AI-Powered: Integrates with your RAG API endpoint for intelligent responses
• Markdown Support: Bot responses render with full Markdown & GFM support
• Secure: API key-based authentication via X-API-Key header
• Responsive: Works seamlessly on desktop and mobile
• TypeScript: Built with TypeScript for type safety
• Lightweight: Minimal dependencies (axios, react-markdown, remark-gfm)
• Conversation Context: Maintains conversation history via session and conversation IDs
• Dual Widgets: General ChatWidget and advanced SupportChatWidget with ticket management

Installation

npm install @aktarulrahul/floater-chatbot
# or
yarn add @aktarulrahul/floater-chatbot

Peer dependencies (must be installed in your app):

npm install react react-dom

Requires React >= 16.8.0.

Quick Start

ChatWidget

import React from "react";
import { ChatWidget } from "@aktarulrahul/floater-chatbot";
import "@aktarulrahul/floater-chatbot/dist/index.css"; // Import bundled CSS

function App() {
  return (
    <ChatWidget
      chatbot_name="Support Bot"
      webhook_url="http://localhost:8008/api/chat/my-chatbot"
      api_key="your-api-key"
      user_email="[email protected]"
    />
  );
}

SupportChatWidget

For advanced support features with category selection, priority levels, and ticket management:

import React from "react";
import { SupportChatWidget } from "@aktarulrahul/floater-chatbot";
import "@aktarulrahul/floater-chatbot/dist/index.css";

function App() {
  return (
    <SupportChatWidget
      config={{
        chatbot_name: "Support Center",
        webhook_url: "http://localhost:8008/api/chat/support-chatbot",
        api_key: "your-api-key",
        user_email: "[email protected]",
        supportConfig: {
          custOrgId: 10556,
          serviceItemId: 2970,
        },
        appearance: {
          title: "Support Center",
          placeholder: "Describe your issue...",
        },
        callbacks: {
          onMessageReceived: (response) => console.log("Received:", response),
          onTicketCreated: (ticketId, ticketUrl) => {
            console.log("Ticket created:", ticketId, ticketUrl);
          },
          onError: (error) => console.error("Error:", error),
        },
      }}
    />
  );
}

API Reference

ChatWidget Props

Props are spread directly from ChatWidgetConfig (not wrapped in a config prop):

| Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------------ | | chatbot_name | string | Yes | Display name shown in the chat header | | webhook_url | string | Yes | Chat API endpoint URL (e.g., http://localhost:8008/api/chat/bot) | | api_key | string | Yes | API key sent via X-API-Key header | | user_email | string | Yes | User email for context and identification | | session_id | string | No | Session ID for conversation context (auto-generated if omitted) |

ChatWidgetConfig (TypeScript)

interface ChatWidgetConfig {
  chatbot_name: string;
  webhook_url: string;
  api_key: string;
  user_email: string;
  session_id?: string;
}

SupportChatConfig

Extends ChatWidgetConfig with additional support-specific options. Passed via a single config prop:

interface SupportChatConfig extends ChatWidgetConfig {
  supportCategories?: SupportCategory[];
  priorityLevels?: PriorityLevel[];
  supportConfig?: {
    custOrgId?: number;
    serviceItemId?: number;
    category?: string;
    priority?: string;
    stage?: string;
  };
  appearance?: {
    title?: string;        // Default: "Support Center"
    placeholder?: string;  // Default: "Type your message..."
  };
  callbacks?: {
    onMessageReceived?: (response: Record<string, unknown>) => void;
    onTicketCreated?: (ticketId: string, ticketUrl: string) => void;
    onError?: (error: Error) => void;
  };
}

Default Support Categories

| ID | Name | Description | | ------------------ | --------------------- | ------------------------------------------- | | general-query | General Query | Questions, information, general inquiries | | existing-service | Existing Service Issue | Problems with current services | | check-status | Check Ticket Status | Track existing tickets, get updates | | raise-ticket | Raise General Ticket | Create new support ticket for any issue |

Default Priority Levels

| ID | Name | Color | Description | | --------- | -------- | --------- | ---------------------------- | | low | Low | #10b981 | General questions, minor | | medium | Medium | #f59e0b | Standard support requests | | high | High | #ef4444 | Urgent issues affecting service | | critical| Critical | #dc2626 | Service down, data loss, security |

Exported Types

import {
  ChatWidgetConfig,
  ChatResponse,
  ChatMessage,
} from "@aktarulrahul/floater-chatbot";

Advanced Usage

Using the useChat Hook

import { useChat } from "@aktarulrahul/floater-chatbot";

function CustomChat() {
  const { messages, isLoading, error, sendMessage, clearMessages } = useChat({
    chatbot_name: "Bot",
    webhook_url: "http://localhost:8008/api/chat/bot",
    api_key: "your-api-key",
    user_email: "[email protected]",
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.text}</div>
      ))}
      <button onClick={() => sendMessage("Hello!")}>Send</button>
      <button onClick={clearMessages}>Clear</button>
    </div>
  );
}

The hook returns:

| Property | Type | Description | | -------------- | ----------------------------- | ------------------------------------ | | messages | ChatMessage[] | All chat messages with timestamps | | isLoading | boolean | Whether a response is pending | | error | string \| null | Last error message, if any | | sendMessage | (text: string) => void | Send a user message | | clearMessages| () => void | Clear all messages and reset session |

Using the ChatApiClient Directly

import { ChatApiClient } from "@aktarulrahul/floater-chatbot";

const client = new ChatApiClient({
  chatbot_name: "Bot",
  webhook_url: "http://localhost:8008/api/chat/bot",
  api_key: "your-api-key",
  user_email: "[email protected]",
});

const response = await client.sendMessage("Hello!");
console.log(response);

// Access session/conversation info
client.getSessionId();        // Auto-generated or custom session_id
client.getConversationId();   // Set from API response
client.setConversationId(id); // Override manually

API Integration

Request Format

The widget sends POST requests to your webhook_url with the following payload:

{
  "question": "user question",
  "conversation_id": "conv-123",
  "session_id": "session_1234567890_abc123",
  "user_email": "[email protected]"
}

Headers:

Content-Type: application/json
X-API-Key: your-api-key

Response Format

The widget handles two response formats:

Standard response:

{
  "success": true,
  "response": "AI-generated answer with **markdown** support",
  "conversation_id": "conv-123",
  "references": [
    {
      "id": "doc-id",
      "pdf_name": "document.pdf",
      "page_number": 1
    }
  ]
}

Wrapped response (e.g., API Gateway / Lambda proxy):

{
  "body": {
    "response": "AI-generated answer",
    "session_id": "conv-123",
    "references": []
  }
}

The ChatApiClient automatically unwraps the body field when present.

Styling

The widget includes default styles. Override CSS classes to customize appearance:

ChatWidget classes

.chat-widget-container { /* Outer container */ }
.chat-widget-button { /* Floating toggle button */ }
.chat-widget-window { /* Chat window panel */ }
.chat-widget-header { /* Header bar */ }
.chat-widget-title { /* Bot name */ }
.chat-widget-messages { /* Message list area */ }
.chat-widget-message-user { /* User message bubble */ }
.chat-widget-message-bot { /* Bot message bubble */ }
.chat-widget-input-container { /* Input bar */ }

SupportChatWidget classes

.chat-button { /* Floating toggle button */ }
.chat-widget { /* Main chat panel */ }
.chat-header { /* Header bar */ }
.category-selection { /* Category grid */ }
.priority-selection { /* Priority grid */ }
.chat-input-form { /* Input form */ }

Import the bundled CSS:

import "@aktarulrahul/floater-chatbot/dist/index.css";

Development

Building the Package

cd chat-widget
npm install
npm run build

Output in dist/:

• dist/index.js - CommonJS bundle
• dist/index.esm.js - ES Module bundle
• dist/index.d.ts - TypeScript declarations
• dist/index.css - Bundled CSS

Development Mode

Watch mode (auto-rebuild on changes):

npm run dev

Storybook

Component documentation and playground:

npm run storybook        # Start dev server on port 6006
npm run build-storybook  # Build static Storybook site

Publishing to NPM

For detailed instructions, see BUILD.md.

npm version patch    # or minor, major
npm run build
npm publish --access public

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Repository

• GitHub: https://github.com/Soft-Loop-Studio/chat-bot
• Issues: https://github.com/Soft-Loop-Studio/chat-bot/issues

License

MIT License - see the LICENSE file for details.