@agilie/rag-bot

v3.0.1

Published

4 months ago

RAG Chat Bot Web Component SDK

Downloads

595

0High
0Medium
0Low

agilie-admin

sergey-mell

RagBot - Chat Widget SDK

A modern, customizable chat widget built with Angular that can be easily embedded into any website or application. Features intelligent configuration handling and universal framework compatibility.

📦 Installation

npm install @rag-chat-bot/rag-bot

🎯 Quick Start

1. Include the Scripts

Add the following scripts to your HTML <head> section:

<!-- Include CSS -->
<link rel="stylesheet" href="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/styles.css" />

<!-- Include JavaScript (order matters!) -->
<script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js" type="module"></script>
<script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/main.js" type="module"></script>

Important Notes:

Scripts must be loaded in the correct order (polyfills first, then main.js)
Both scripts must have type="module" attribute
Make sure the paths are correct relative to your HTML file

2. Add the Widget

Place the widget element anywhere in your HTML body:

<body>
  <!-- Your existing content -->

  <!-- Add the chat widget -->
  <rag-chat-widget></rag-chat-widget>
</body>

🚀 Framework Integration

Static HTML Integration

1. Basic Static Setup

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Website</title>

    <!-- Include RagBot CSS -->
    <link rel="stylesheet" href="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/styles.css" />
  </head>
  <body>
    <h1>Welcome to My Website</h1>
    <p>Your website content here...</p>

    <!-- Add the chat widget -->
    <rag-chat-widget></rag-chat-widget>

    <!-- Include RagBot Scripts -->
    <script
      src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
      type="module"
    ></script>
    <script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/main.js" type="module"></script>

    <!-- Configure the widget -->
    <script>
      // Method 1: Direct configuration
      document.addEventListener('DOMContentLoaded', function () {
        const chatWidget = document.querySelector('rag-chat-widget');
        if (chatWidget) {
          chatWidget.setConfig({
            apiUrl: 'https://api.example.com',
            assetsBasePath: '/rag-bot/assets',
            primaryColor: '#007bff',
            baseColor: '#ffffff',
            fontColor: '#333333',
            secondaryColor: '#666666',
            logoUrl: '/logo.png',
            welcomeMessageTitle: 'Hi there! 👋',
            welcomeMessageSubtitle: 'How can we help you?',
          });
        }
      });

      // Method 2: Window configuration (fallback)
      window.chatWidget = {
        config: {
          apiUrl: 'https://api.example.com',
          assetsBasePath: '/rag-bot/assets',
          primaryColor: '#007bff',
          baseColor: '#ffffff',
          fontColor: '#333333',
          secondaryColor: '#666666',
          logoUrl: '/logo.png',
          welcomeMessageTitle: 'Hi there! 👋',
          welcomeMessageSubtitle: 'How can we help you?',
        },
      };
    </script>
  </body>
</html>

2. Advanced Static Configuration

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Website</title>
    <link rel="stylesheet" href="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/styles.css" />
  </head>
  <body>
    <rag-chat-widget></rag-chat-widget>

    <script
      src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
      type="module"
    ></script>
    <script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/main.js" type="module"></script>

    <script>
      // Advanced configuration with all options
      const chatConfig = {
        // Required fields
        primaryColor: '#007bff',
        baseColor: '#ffffff',
        fontColor: '#333333',
        secondaryColor: '#666666',
        logoUrl: '/assets/logo.png',
        welcomeMessageTitle: 'Welcome to our support!',
        welcomeMessageSubtitle: 'How can we help you today?',
        apiUrl: 'https://api.example.com',

        // Optional fields
        position: 'bottom-right',
        buttonMarginY: 32, // Vertical margin from screen edge (default: 24px)
        buttonMarginX: 32, // Horizontal margin from screen edge (default: 24px)
        assetsBasePath: '/rag-bot/assets',
        contactFormUrl: '/contact',
        contactFormTitle: 'Contact Us',
        contactFormBackground: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
        contactFormIcon: '/assets/contact-icon.svg',
        contactFormAvatar: '/assets/avatar.png',
        privacyPolicyUrl: 'https://example.com/privacy',
        termsOfServiceUrl: 'https://example.com/terms',

        // Quick actions
        quickActions: [
          {
            title: 'Get Help',
            icon: '/assets/help-icon.svg',
            type: 'help',
            avatar: '/assets/help-avatar.png',
          },
          {
            title: 'Schedule Call',
            icon: '/assets/call-icon.svg',
            type: 'call',
          },
        ],

        // Navigation options
        navOptions: [
          { title: 'Home', type: 'home' },
          { title: 'About', type: 'about' },
          { title: 'Contact', type: 'contact' },
        ],

        // Home page animations
        homeAnimations: ['/assets/animations/welcome.mp4', '/assets/animations/chat.mp4'],

        // Chat banner configuration
        chatBanner: {
          showBanner: true,
          title: 'Hi! 👋 I\'m Your AI Assistant!',
          description: 'I can assist you with inquiries about our company, services, and software.',
          buttonText: 'Start',
        },
      };

      // Initialize widget when DOM is ready
      document.addEventListener('DOMContentLoaded', function () {
        const chatWidget = document.querySelector('rag-chat-widget');
        if (chatWidget) {
          // Use the new setConfig method
          chatWidget.setConfig(chatConfig);

          // Optional: Listen for events
          chatWidget.addEventListener('quickAction', function (event) {
            console.log('Quick action triggered:', event.detail);
          });
        }
      });
    </script>
  </body>
</html>

Angular Integration

1. Add Scripts to index.html

<!-- src/index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Angular App</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />

    <!-- Add RagBot CSS -->
    <link rel="stylesheet" href="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/styles.css" />
  </head>
  <body>
    <app-root></app-root>

    <!-- Add RagBot Scripts -->
    <script
      src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
      type="module"
    ></script>
    <script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/main.js" type="module"></script>
  </body>
</html>

2. Use in Component

// app.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <div>
      <h1>My Angular App</h1>
      <rag-chat-widget [config]="chatConfig"></rag-chat-widget>
    </div>
  `
})
export class AppComponent {
  chatConfig = {
    apiUrl: environment.chatApiUrl,
    ...
    // you can find full CONFIG obj below
  };
}

React Integration

1. Add Scripts to public/index.html

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="My React App" />

    <!-- Add RagBot CSS -->
    <link rel="stylesheet" href="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/styles.css" />
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>

    <!-- Add RagBot Scripts -->
    <script
      src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
      type="module"
    ></script>
    <script src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/main.js" type="module"></script>
  </body>
</html>

2. Use in Component

// App.js
import React, { useEffect, useRef } from 'react';

function App() {
  const chatWidgetRef = useRef(null);
  const config = {
    apiUrl: process.env.REACT_APP_CHAT_API_URL,
    assetsBasePath: '/rag-bot/assets',
    primaryColor: '#007bff',
    baseColor: '#ffffff',
    fontColor: '#333333',
    secondaryColor: '#666666',
    logoUrl: '/logo.png',
    welcomeMessageTitle: 'Hi there! 👋',
    welcomeMessageSubtitle: 'How can we help you?',
  };

  useEffect(() => {
    const chatWidget = chatWidgetRef.current;

    if (chatWidget) {
      // Use the new setConfig method for better reliability
      if (typeof chatWidget.setConfig === 'function') {
        chatWidget.setConfig(config);
      } else {
        // Fallback to direct assignment
        chatWidget.config = config;
      }
    }
  }, []);

  return (
    <div className="App">
      <h1>My React App</h1>
      <rag-chat-widget ref={chatWidgetRef}></rag-chat-widget>
    </div>
  );
}

export default App;

####### FULL EXAMPLE ######

chatConfig = {
  // Required fields
  primaryColor: '#007bff',
  baseColor: '#ffffff',
  fontColor: '#333333',
  secondaryColor: '#666666',
  logoUrl: '/logo.png',
  welcomeMessageTitle: 'Welcome to our support!',
  welcomeMessageSubtitle: 'How can we help you today?',
  apiUrl: environment.chatApiUrl,

  position: 'bottom-right',
  buttonMarginY: 32, // Vertical margin from screen edge (default: 24px)
  buttonMarginX: 32, // Horizontal margin from screen edge (default: 24px)
  contactFormUrl: 'https://your-domain.com/contact',
  contactFormTitle: 'Contact Us',
  contactFormBackground: '#f8f9fa',
  contactFormIcon: 'https://your-domain.com/contact-icon.svg',
  contactFormAvatar: 'https://your-domain.com/avatar.png',
  privacyPolicyUrl: 'https://your-domain.com/privacy',
  termsOfServiceUrl: 'https://your-domain.com/terms',

  // Quick actions
  quickActions: [
    {
      title: 'Get Help',
      icon: 'https://your-domain.com/help-icon.svg',
      type: 'help',
      avatar: 'https://your-domain.com/help-avatar.png',
    },
    {
      title: 'Schedule Call',
      icon: 'https://your-domain.com/call-icon.svg',
      type: 'call',
    },
  ],

  // Navigation options
  navOptions: [
    {
      title: 'Home',
      type: 'home',
    },
    {
      title: 'Chat',
      type: 'chat',
    },
  ],

  // Assets configuration
  assetsBasePath: 'https://your-domain.com/assets/',

  // Home page animations
  homeAnimations: [
    'https://your-domain.com/animations/welcome.mp4',
    'https://your-domain.com/animations/chat.mp4',
  ],

  // Chat banner configuration
  chatBanner: {
    showBanner: true,
    title: 'Hi! 👋 I\'m Your AI Assistant!',
    description: 'I can assist you with inquiries about our company, services, and software.',
    buttonText: 'Start',
  },
};

🆕 New Features & Improvements

Intelligent Configuration Handling

The widget now features smart configuration processing that handles various input formats:

Direct Object: widget.setConfig({...})
JSON String: Automatically parses JSON configuration
Window Fallback: Uses window.chatWidget.config as fallback
Delayed Initialization: Waits for configuration before initializing
Multiple Fallbacks: Graceful degradation with multiple fallback options

Universal Framework Compatibility

Works seamlessly with:

✅ React (with hooks and refs)
✅ Angular (with property binding)
✅ Vue (with reactive components)
✅ Static HTML (with vanilla JavaScript)
✅ WordPress (with PHP integration)
✅ Next.js (with SSR support)
✅ Any other framework

Enhanced API Methods

// New methods available on the widget
const chatWidget = document.querySelector('rag-chat-widget');

// Set configuration dynamically
chatWidget.setConfig({
  apiUrl: 'https://api.example.com',
  assetsBasePath: '/rag-bot/assets',
  primaryColor: '#007bff',
});

// Force re-initialization
chatWidget.forceInitialize();

// Access current configuration
console.log(chatWidget.config);

Smart Asset Loading

The widget now intelligently handles asset paths:

Automatically uses assetsBasePath from configuration
Falls back to default paths if not specified
Supports both relative and absolute paths
Handles CDN and local asset scenarios

⚙️ Configuration

TypeScript Interface

interface ChatConfig {
  // Required fields
  primaryColor: string;
  baseColor: string;
  fontColor: string;
  secondaryColor: string;
  logoUrl: string;
  welcomeMessageTitle: string;
  welcomeMessageSubtitle: string;
  apiUrl: string;

  // Optional fields
  contactFormUrl?: string;
  contactFormTitle?: string;
  contactFormBackground?: string;
  contactFormIcon?: string;
  contactFormAvatar?: string;
  privacyPolicyUrl?: string;
  termsOfServiceUrl?: string;
  position?: 'bottom-left' | 'bottom-right';
  buttonMarginY?: number;
  buttonMarginX?: number;
  quickActions?: ChatQuickAction[];
  navOptions?: ChatNavOption[];
  assetsBasePath?: string;
  homeAnimations?: string[];
  chatBanner?: ChatBanner;
}

interface ChatBanner {
  showBanner: boolean;
  title: string;
  description: string;
  buttonText: string;
}

interface ChatQuickAction {
  title: string;
  icon: string;
  type: string;
  avatar?: string;
}

interface ChatNavOption {
  title: string;
  type: string;
}

Configuration Fields

| Field | Type | ------------------------ | primaryColor | baseColor | fontColor | secondaryColor | logoUrl | welcomeMessageTitle | welcomeMessageSubtitle | apiUrl | contactFormUrl | contactFormTitle | contactFormBackground | contactFormIcon | contactFormAvatar | privacyPolicyUrl | termsOfServiceUrl | position | buttonMarginY | buttonMarginX | quickActions | navOptions | assetsBasePath | homeAnimations | chatBanner | Required | Description | | ----------------- | -------- | -------------------------------------------------- | | string | ✅ | Primary brand color | | string | ✅ | Base background color | | string | ✅ | Text color | | string | ✅ | Secondary text color | | string | ✅ | Logo image URL | | string | ✅ | Welcome message title | | string | ✅ | Welcome message subtitle | | string | ✅ | API endpoint URL for chat backend | | string | ❌ | Contact form URL | | string | ❌ | Contact form title | | string | ❌ | Contact form background | | string | ❌ | Contact form icon | | string | ❌ | Contact form avatar | | string | ❌ | Privacy policy URL | | string | ❌ | Terms of service URL | | string | ❌ | Widget position (bottom-left or bottom-right) | | number | ❌ | Vertical margin from screen edge (default: 24px) | | number | ❌ | Horizontal margin from screen edge (default: 24px) | | ChatQuickAction[] | ❌ | Quick action buttons | | ChatNavOption[] | ❌ | Navigation menu options | | string | ❌ | Base path for assets | | string[] | ❌ | Video animation files (MP4 format) for home page | | ChatBanner | ❌ | Chat banner configuration |

Note: homeAnimations should contain video files in MP4 format that will be randomly displayed on the home page.

Chat Banner Configuration

The chat banner is a new feature that displays a welcome message to users before they start chatting. Here's how to configure it:

chatBanner: {
  showBanner: true,                    // Enable/disable the banner
  title: 'Hi! 👋 I\'m Your AI Assistant!',  // Banner title
  description: 'I can assist you with inquiries about our company, services, and software.',  // Banner description
  buttonText: 'Start',                // Button text (default: 'Start')
}

Banner Behavior:

Appears: 5 seconds after page load (if not closed in current session)
Animation: Smooth fade-in/fade-out transitions
Session Storage: Banner state persists until browser session ends
Auto-close: Banner closes when user clicks chat icon or "Start" button
Manual close: Users can close banner with "X" button

Banner Features:

✅ Responsive design - works on all screen sizes
✅ Smooth animations - fade in/out transitions
✅ Session persistence - remembers if user closed it
✅ Auto-trigger - opens chat when "Start" is clicked
✅ Customizable - title, description, and button text

🔍 Troubleshooting

Common Issues

Widget not appearing
- Check if scripts are loaded in correct order
- Verify paths to CSS and JS files
- Ensure type="module" is present on script tags
- Wait for DOM to be ready before configuring
Configuration not applied
- Use setConfig() method instead of direct assignment
- Check for JavaScript errors in console
- Verify all required fields are provided
- Try using window.chatWidget.config as fallback
Assets not loading (404 errors)
- Ensure assetsBasePath is correctly set in configuration
- Check that asset files exist at the specified paths
- Verify the path format (relative vs absolute)
- Use browser dev tools to check network requests
Styling issues
- Ensure CSS file is loaded before widget initialization
- Check for CSS conflicts with your existing styles
- Verify color values are in correct format (hex, rgb, etc.)

Debug Mode

// Check widget status and configuration
const chatWidget = document.querySelector('rag-chat-widget');

// Check if widget is ready
console.log('Widget element:', chatWidget);
console.log('Widget methods:', typeof chatWidget.setConfig);

// Check current configuration
if (chatWidget) {
  console.log('Current config:', chatWidget.config);
  console.log('Widget initialized:', chatWidget.initialized);
}

// Force re-initialization if needed
if (chatWidget && typeof chatWidget.forceInitialize === 'function') {
  chatWidget.forceInitialize();
}

Configuration Debugging

// Debug configuration issues
const chatWidget = document.querySelector('rag-chat-widget');

// Method 1: Direct configuration
chatWidget.setConfig({
  apiUrl: 'https://api.example.com',
  assetsBasePath: '/rag-bot/assets',
  primaryColor: '#007bff',
});

// Method 2: Window fallback
window.chatWidget = {
  config: {
    apiUrl: 'https://api.example.com',
    assetsBasePath: '/rag-bot/assets',
    primaryColor: '#007bff',
  },
};

// Method 3: JSON string (for dynamic configs)
const configString = JSON.stringify({
  apiUrl: 'https://api.example.com',
  assetsBasePath: '/rag-bot/assets',
});
// The widget will automatically parse this

📱 Mobile Considerations

Widget is fully responsive and works on all mobile devices
Touch interactions are optimized for mobile use
Position automatically adjusts for mobile screens
Supports both portrait and landscape orientations

🆘 Support

If you have any questions or issues, please check the troubleshooting section above or contact our support team.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

RagBot - Chat Widget SDK

📦 Installation

🎯 Quick Start

1. Include the Scripts

2. Add the Widget

🚀 Framework Integration

Static HTML Integration

1. Basic Static Setup

2. Advanced Static Configuration

Angular Integration

1. Add Scripts to index.html

2. Use in Component

React Integration

1. Add Scripts to public/index.html

2. Use in Component

🆕 New Features & Improvements

Intelligent Configuration Handling

Universal Framework Compatibility

Enhanced API Methods

Smart Asset Loading

⚙️ Configuration

TypeScript Interface

Configuration Fields

Chat Banner Configuration

Banner Behavior:

Banner Features:

🔍 Troubleshooting

Common Issues

Debug Mode

Configuration Debugging

📱 Mobile Considerations

🆘 Support