Floater Chatbot - React NPM Package

A professional, AI-powered floating chat widget for React applications that integrates with n8n workflows for intelligent customer support.

Features

• 🤖 AI-Powered: Integrates with your n8n workflow for intelligent responses
• 🎨 Customizable: Fully customizable appearance and positioning
• 🔐 Secure: Token-based authentication
• 📱 Responsive: Works seamlessly on desktop and mobile
• 🎯 TypeScript: Built with TypeScript for type safety
• ⚡ Lightweight: Minimal dependencies, optimized bundle size
• 🔄 Conversation Context: Maintains conversation history via conversation IDs
• 🎫 Ticket Support: Handles Zendesk ticket creation callbacks

Installation

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

Quick Start

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

function App() {
  return (
    <ChatWidget
      config={{
        webhookUrl: "http://localhost:5678/webhook/chat",
        accessToken: "your-access-token",
        apiEndpoints: {
          profileApi: "https://api.example.com/profile",
          servicesApi: "https://api.example.com/services",
          zendeskApi: "https://your-domain.zendesk.com",
        },
        appearance: {
          primaryColor: "#007bff",
          position: "bottom-right",
          title: "Chat Support",
          subtitle: "How can we help you?",
        },
        callbacks: {
          onMessageSent: (message) => console.log("Sent:", message),
          onMessageReceived: (response) => console.log("Received:", response),
          onTicketCreated: (ticketId, ticketUrl) => {
            console.log("Ticket created:", ticketId, ticketUrl);
          },
        },
      }}
    />
  );
}

Configuration Options

ChatWidgetConfig

| Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------------------------------------- | | webhookUrl | string | ✅ | n8n webhook endpoint URL (e.g., http://localhost:5678/webhook/chat) | | accessToken | string | ✅ | User authentication token | | conversationId | string | ❌ | Optional conversation ID for context | | apiEndpoints | object | ❌ | API endpoints to pass to n8n | | appearance | object | ❌ | Widget appearance configuration | | callbacks | object | ❌ | Event callback functions | | supportConfig | object | ❌ | Support-specific config (for SupportChatWidget) |

Appearance Options

appearance: {
  primaryColor?: string;        // Default: '#007bff'
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';  // Default: 'bottom-right'
  title?: string;                // Default: 'Chat Support'
  subtitle?: string;             // Default: 'How can we help you?'
  placeholder?: string;          // Default: 'Type your message...'
  showAvatar?: boolean;          // Default: true
  avatarUrl?: string;           // Default: auto-generated avatar
}

API Endpoints

apiEndpoints: {
  profileApi?: string;      // User profile API endpoint
  servicesApi?: string;     // Purchased services API endpoint
  zendeskApi?: string;      // Zendesk API endpoint
}

Callbacks

callbacks: {
  onMessageSent?: (message: string) => void;
  onMessageReceived?: (response: ChatResponse) => void;
  onError?: (error: Error) => void;
  onTicketCreated?: (ticketId: string, ticketUrl: string) => void;
}

SupportChatWidget Usage

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={{
        webhookUrl: "http://localhost:5678/webhook/support-chat",
        accessToken: "your-access-token",
        supportConfig: {
          custOrgId: 10556,
          serviceItemId: 2970,
        },
        apiEndpoints: {
          profileApi: "https://api.example.com/profile",
          servicesApi: "https://api.example.com/services",
          zendeskApi: "https://your-domain.zendesk.com",
        },
        appearance: {
          title: "Support Center",
          subtitle: "How can we help you?",
        },
      }}
    />
  );
}

Support Configuration

supportConfig: {
  custOrgId?: number;      // Customer organization ID
  serviceItemId?: number;  // Service item ID
  category?: string;        // Support category
  priority?: string;        // Priority level
  stage?: string;          // Conversation stage
}

Advanced Usage

Using the Hook Directly

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

function CustomChat() {
  const { messages, isLoading, sendMessage } = useChat({
    webhookUrl: "http://localhost:5678/webhook/chat",
    accessToken: "your-token",
  });

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

Using the API Client

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

const client = new ChatApiClient({
  webhookUrl: "http://localhost:5678/webhook/chat",
  accessToken: "your-token",
});

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

Response Format

The widget expects responses in the following format from your n8n workflow:

{
  "success": true,
  "response": "AI-generated answer",
  "conversation_id": "conv-123",
  "references": [
    {
      "id": "doc-id",
      "pdf_name": "document.pdf",
      "page_number": 1
    }
  ],
  "ticket_id": "optional-ticket-id",
  "ticket_url": "optional-ticket-url",
  "customer_context": {
    "name": "Customer Name",
    "plan": "Premium"
  }
}

n8n Integration

This widget is designed to work with the n8n workflow provided in templates/chat.json. The workflow expects:

Request:

{
  "token": "user-access-token",
  "message": "user question",
  "conversation_id": "optional-conversation-id",
  "api_endpoints": {
    "profileApi": "https://api.example.com/profile",
    "servicesApi": "https://api.example.com/services",
    "zendeskApi": "https://your-domain.zendesk.com"
  }
}

Styling

The widget includes default styles, but you can override them:

.chat-widget-container {
  /* Your custom styles */
}

.chat-widget-button {
  /* Button styles */
}

.chat-widget-window {
  /* Window styles */
}

TypeScript Support

Full TypeScript definitions are included:

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

Development

Building the Package

To build the npm package:

cd chat-widget
npm install
npm run build

This will create the compiled files in the dist/ directory:

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

Development Mode

For development with watch mode (auto-rebuild on changes):

npm run dev

Publishing to NPM

For detailed instructions on building and publishing, see BUILD.md.

Quick publish steps:

# 1. Update version
npm version patch  # or minor, major

# 2. Build (runs automatically before publish)
npm run build

# 3. Publish
npm publish --access public

Browser Support

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

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.