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

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

🎯 Quick Start

$3

Add the following scripts to your HTML section:

`html






`

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

$3

Place the widget element anywhere in your HTML body:

`html






`

🚀 Framework Integration

$3

#### 1. Basic Static Setup

`html







Welcome to My Website





`

#### 2. Advanced Static Configuration

`html











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





`

$3

#### 1. Add Scripts to index.html

`html











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



`

#### 2. Use in Component

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

@Component({
selector: 'app-root',
template:

`html











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



`

#### 2. Use in Component

`jsx
// 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 (


export default App;
`

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

`typescript
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

$3

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

$3

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

$3

`javascript
// 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);
`

$3

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

$3

`typescript
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;
}
`

$3

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

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

$3

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

`typescript
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

$3

1. 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

2. 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

3. 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

4. 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.)

$3

`javascript
// 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();
}
`

$3

`javascript
// 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.