🤖 Fyrebot AI Chatbot Widget

Production-ready, standalone chatbot popup widget for any React application. Features beautiful dark theme, multi-tenant support via X-API-Key authentication, and complete TypeScript support.

Made with ❤️ by Fyrebot

✨ Features

• 🎨 Beautiful dark theme UI with smooth animations
• 🔐 Secure X-API-Key authentication
• 🏢 Multi-tenant support (automatic tenant identification via API key)
• 💬 Session-based conversations with context retention
• 📚 Source citations with relevance scores
• ⚡ Real-time typing indicators
• 📱 Fully responsive design
• 🎯 TypeScript support with complete type definitions
• 🔄 Error handling with user-friendly messages
• ⚙️ Highly customizable (colors, position, messages, etc.)
• 📦 Zero external UI dependencies (self-contained)

📦 Installation

npm install fyrebot-widget
# or
yarn add fyrebot-widget
# or
pnpm add fyrebot-widget

🚀 Quick Start

Basic Usage

import { ChatbotWidget } from 'fyrebot-widget';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      <ChatbotWidget
        apiUrl="https://api.fyreway.com/api"
        apiKey="your-api-key-from-dashboard"
      />
    </div>
  );
}

Get Your API Key

1. Sign up at fyrebot.fyreway.com
2. Go to your dashboard
3. Copy your API key
4. Use it in the widget configuration

Advanced Configuration

import { ChatbotWidget } from 'fyrebot-widget';

function App() {
  return (
    <ChatbotWidget
      // Required
      apiUrl="https://api.fyreway.com/api"
      apiKey="your-api-key-from-dashboard"
      
      // Customization
      title="Support Assistant"
      subtitle="We're here to help"
      brandName="Your Company"
      primaryColor="#6366f1"
      welcomeMessage="Hello! How can I assist you today?"
      placeholder="Ask me anything..."
      position="bottom-right"
      
      // Features
      showTypingIndicator={true}
      showTimestamps={true}
      showSources={true}
      
      // Sizing
      maxHeight="600px"
      maxWidth="400px"
      
      // Callbacks
      onOpen={() => console.log('Chat opened')}
      onClose={() => console.log('Chat closed')}
      onMessageSent={(message) => console.log('Sent:', message)}
      onMessageReceived={(message) => console.log('Received:', message)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

🎨 Customization Options

Configuration Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiUrl | string | Required | Your API endpoint URL | | apiKey | string | Required | X-API-Key for authentication | | title | string | 'AI Assistant' | Header title | | subtitle | string | 'Ask me anything' | Header subtitle | | brandName | string | undefined | Brand name for welcome message | | primaryColor | string | '#6366f1' | Primary theme color (hex) | | welcomeMessage | string | 'Hello! How can I help you today?' | Initial welcome message | | placeholder | string | 'Type your message...' | Input placeholder text | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Chat button position | | showTypingIndicator | boolean | true | Show typing animation | | showTimestamps | boolean | true | Show message timestamps | | showSources | boolean | true | Show source citations | | maxHeight | string | '600px' | Maximum chat window height | | maxWidth | string | '400px' | Maximum chat window width | | className | string | '' | Custom CSS class |

Callbacks

<ChatbotWidget
  // ... other props
  onOpen={() => {
    // Called when chat window opens
    console.log('Chat opened');
  }}
  
  onClose={() => {
    // Called when chat window closes
    console.log('Chat closed');
  }}
  
  onMessageSent={(message) => {
    // Called when user sends a message
    console.log('User said:', message);
  }}
  
  onMessageReceived={(message) => {
    // Called when bot responds
    console.log('Bot said:', message.content);
  }}
  
  onError={(error) => {
    // Called when an error occurs
    console.error('Error:', error.message);
  }}
/>

🔐 API Integration

Backend Requirements

Your backend API must support:

1. Authentication: X-API-Key header
2. Endpoint: POST /chat
3. Request Format:

   {
     "query": "User's message",
     "sessionId": "optional-session-id"
   }

4. Response Format:

   {
     "success": true,
     "data": {
       "answer": "Bot's response",
       "sessionId": "session-123",
       "sources": [
         {
           "title": "Source document",
           "score": 0.95,
           "content": "Optional excerpt"
         }
       ]
     }
   }

Multi-Tenant Support

The widget automatically includes the X-API-Key header in all requests. Your backend should:

1. Validate the X-API-Key
2. Identify the tenant from the key
3. Return responses based on the tenant's data

Example backend logic:

// Backend (Node.js/Express example)
app.post('/chat', async (req, res) => {
  const apiKey = req.headers['x-api-key'];
  
  // Validate and get tenant
  const tenant = await validateApiKey(apiKey);
  if (!tenant) {
    return res.status(401).json({ error: 'Invalid API key' });
  }
  
  // Process query with tenant's data
  const result = await processQuery(
    tenant.id,
    req.body.query,
    req.body.sessionId
  );
  
  res.json({ success: true, data: result });
});

🎯 TypeScript Support

Full TypeScript definitions included:

import { ChatbotWidget, ChatbotConfig, ChatMessage } from 'fyrebot-widget';

const config: ChatbotConfig = {
  apiUrl: 'https://api.fyreway.com/api',
  apiKey: 'your-key',
  title: 'Assistant',
  onMessageReceived: (message: ChatMessage) => {
    console.log(message.content);
  },
};

function App() {
  return <ChatbotWidget {...config} />;
}

📱 Responsive Design

The widget automatically adapts to:

• Desktop screens
• Tablets
• Mobile devices (full-screen on small screens)

🎨 Styling

The widget uses scoped inline styles with no external CSS dependencies. You can customize:

1. Theme Colors: Use primaryColor prop
2. Size: Use maxHeight and maxWidth props
3. Position: Use position prop
4. Custom Overrides: Use className prop with CSS variables

Example custom styling:

.my-custom-chatbot {
  /* Your custom styles */
}

<ChatbotWidget
  className="my-custom-chatbot"
  primaryColor="#ff6b6b"
/>

🔧 Advanced Usage

Programmatic Control

import { ChatbotWidget, ChatbotApiClient } from 'fyrebot-widget';
import { useRef } from 'react';

function App() {
  const apiClientRef = useRef<ChatbotApiClient>();

  const handleReset = () => {
    // Reset the conversation
    apiClientRef.current?.resetSession();
  };

  return (
    <>
      <button onClick={handleReset}>Reset Chat</button>
      <ChatbotWidget
        apiUrl="https://api.fyreway.com/api"
        apiKey="your-key"
      />
    </>
  );
}

🐛 Error Handling

The widget handles common errors gracefully:

• ❌ Invalid API key → "Invalid API key. Please check your credentials."
• ❌ Rate limiting → "Too many requests. Please wait a moment."
• ❌ Network issues → "Unable to connect to the server."
• ❌ Server errors → "Server error. Please try again later."

All errors are displayed in a user-friendly format within the chat window.

📦 Bundle Size

• Minified: ~45KB
• Gzipped: ~15KB
• Dependencies: React, Lucide Icons, Axios

🔒 Security

• ✅ X-API-Key authentication
• ✅ HTTPS required for production
• ✅ XSS protection (React's built-in escaping)
• ✅ CORS handled by your backend
• ✅ No data stored in localStorage (optional session storage)

🚀 Deployment

Option 1: Direct Copy (Easiest)

Copy the entire src folder to your React project:

cp -r chatbot-widget/src ./src/components/chatbot

Then import:

import { ChatbotWidget } from './components/chatbot';

Option 2: NPM Package

Build and publish:

npm run build
npm publish

Then install in your projects:

npm install fyrebot-widget

📄 License

MIT © Fyrebot

🤝 Support

For issues or questions:

• 📧 Email: [email protected]
• 🌐 Website: fyrebot.com
• 📚 Docs: docs.fyrebot.com

Made with ❤️ by Fyrebot - Empowering businesses with AI-powered conversations