RAG Chat Bot Web Component SDK
npm install @agilie/rag-botA 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.
``bash`
npm install @rag-chat-bot/rag-bot
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
My Website
Welcome to My Website
Your website content here...
src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
type="module"
>
`#### 2. Advanced Static Configuration
`html
My Website
src="node_modules/@rag-chat-bot/rag-bot/dist/rag-bot/polyfills.js"
type="module"
>
`$3
#### 1. Add Scripts to index.html
`html
My Angular App
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:
})
export class AppComponent {
chatConfig = {
apiUrl: environment.chatApiUrl,
...
// you can find full CONFIG obj below
};
}
`$3
#### 1. Add Scripts to public/index.html
`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 (
My React App
);
}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 configuring2. 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 fallback3. 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 requests4. 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
``- 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
If you have any questions or issues, please check the troubleshooting section above or contact our support team.