sandia-chatbot-widget
Version:
Production-ready Sandia AI Chatbot Widget v3.0 with advanced themes, animations, notifications, and enterprise features
637 lines (532 loc) • 14.7 kB
Markdown
# Sandia AI Chatbot Widget v3.0 - Production Ready 🚀
**The most advanced, feature-rich chatbot widget for seamless AI assistant integration into any website or application.**
[](https://www.npmjs.com/package/sandia-chatbot-widget)
[](https://www.npmjs.com/package/sandia-chatbot-widget)
[](LICENSE)
## 🌟 **What's New in v3.0**
✨ **4 Beautiful Themes** - Modern, Classic, Minimal, Gradient
🎨 **Advanced Animations** - Smooth, Bouncy, Slide, Fade effects
🔔 **Smart Notifications** - Browser notifications & sound alerts
📱 **Mobile Excellence** - Full-screen mode & touch optimization
🎯 **Accessibility First** - WCAG compliant with screen reader support
💬 **Rich Conversations** - Message timestamps, copy functionality, reactions
📎 **File Uploads** - Drag & drop with progress indicators
🎤 **Voice Input** - Speech-to-text capabilities (coming soon)
⚡ **Performance** - Lazy loading, virtual scrolling, optimized rendering
🔧 **Developer Tools** - Enhanced APIs, debugging, and customization
## 🚀 **Quick Start**
### **NPM Installation**
```bash
npm install sandia-chatbot-widget@3.0.0
```
### **React Integration - Production Ready**
```tsx
import { SandiaWidget } from 'sandia-chatbot-widget';
function App() {
return (
<SandiaWidget
chatbotId="your-chatbot-id"
styles={{
theme: 'modern',
primaryColor: '#006FEE',
shadowStyle: 'soft',
animation: 'smooth',
darkMode: false,
showTimestamps: true,
allowFileUpload: true,
soundEnabled: true,
notificationsEnabled: true
}}
chatConfig={{
quickReplies: ['Hello', 'Help me', 'Learn more'],
maxFileSize: 10,
voiceEnabled: true
}}
onMessage={(msg) => console.log('New message:', msg)}
onFileUpload={(file) => console.log('File uploaded:', file.name)}
/>
);
}
```
### **Vanilla JavaScript - Enhanced**
```html
<!DOCTYPE html>
<html>
<head>
<script>
window.SandiaChatbot = {
chatbotId: 'your-chatbot-id',
version: '3.0',
styles: {
theme: 'gradient',
primaryColor: '#006FEE',
shadowStyle: 'glow',
animation: 'bouncy',
showAvatar: true,
showTimestamps: true,
soundEnabled: true,
notificationsEnabled: true,
darkMode: false,
autoMinimize: 5
},
chatConfig: {
quickReplies: ['Hi there!', 'How can you help?', 'Tell me more'],
allowedFileTypes: ['image/*', '.pdf', '.txt'],
maxFileSize: 10
}
};
</script>
<script src="https://unpkg.com/sandia-chatbot-widget@3.0.0/dist/vanilla.js"></script>
</head>
<body>
<!-- Your content -->
</body>
</html>
```
## 🎨 **Theme Showcase**
### **Modern Theme (Default)**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
theme: 'modern',
primaryColor: '#006FEE',
shadowStyle: 'soft',
animation: 'smooth'
}}
/>
```
### **Gradient Theme**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
theme: 'gradient',
primaryColor: '#006FEE',
shadowStyle: 'glow',
animation: 'bouncy'
}}
/>
```
### **Classic Corporate**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
theme: 'classic',
primaryColor: '#1e40af',
shadowStyle: 'hard',
size: 'lg',
customIcon: '🏢',
greeting: 'Welcome to our support center'
}}
/>
```
### **Minimal Design**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
theme: 'minimal',
primaryColor: '#059669',
shadowStyle: 'none',
animation: 'fade',
borderRadius: 12
}}
/>
```
## 🔧 **Production Configuration**
### **Complete Styling Options**
```typescript
interface WidgetStyles {
// Theme System
theme?: 'modern' | 'classic' | 'minimal' | 'gradient';
shadowStyle?: 'soft' | 'hard' | 'glow' | 'none';
animation?: 'smooth' | 'bouncy' | 'slide' | 'fade' | 'none';
// Basic Appearance
position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
primaryColor?: string;
backgroundColor?: string;
textColor?: string;
borderRadius?: number;
size?: 'sm' | 'md' | 'lg';
// Advanced Features
darkMode?: boolean;
showAvatar?: boolean;
showTimestamps?: boolean;
soundEnabled?: boolean;
notificationsEnabled?: boolean;
allowFileUpload?: boolean;
showTypingIndicator?: boolean;
// Conversation Management
messagePersistence?: boolean;
maxMessages?: number;
autoMinimize?: number; // minutes
// Customization
customAvatar?: string;
customIcon?: string;
greeting?: string;
customCSS?: string;
brandingEnabled?: boolean;
// Accessibility
highContrast?: boolean;
reducedMotion?: boolean;
// Mobile
mobileFullScreen?: boolean;
swipeToClose?: boolean;
}
```
### **Chat Configuration**
```typescript
interface ChatConfiguration {
// Quick Actions
quickReplies?: string[];
// File Upload
allowedFileTypes?: string[];
maxFileSize?: number; // MB
// Voice Features
voiceEnabled?: boolean;
voiceLanguage?: string;
// Performance
messagesPerMinute?: number;
// Analytics
trackingEnabled?: boolean;
customEvents?: string[];
}
```
## 🎯 **Enterprise Features**
### **Advanced Event Handling**
```tsx
<SandiaWidget
chatbotId="your-id"
// Core Events
onReady={() => console.log('Widget ready')}
onOpen={() => analytics.track('chat_opened')}
onClose={() => analytics.track('chat_closed')}
onMinimize={() => analytics.track('chat_minimized')}
onRestore={() => analytics.track('chat_restored')}
// Message Events
onMessage={(msg) => {
console.log('Message:', msg);
// Save to your analytics
analytics.track('message_sent', {
role: msg.role,
timestamp: msg.timestamp,
length: msg.content.length
});
}}
onTyping={(isTyping) => console.log('User typing:', isTyping)}
// Advanced Events
onFileUpload={(file) => {
console.log('File upload:', file.name, file.size);
// Handle file processing
}}
onVoiceStart={() => console.log('Voice recording started')}
onVoiceEnd={(transcript) => console.log('Voice:', transcript)}
// Error Handling
onError={(error) => {
console.error('Chat error:', error);
// Report to error tracking
}}
onSubscriptionError={(error) => {
console.warn('Subscription issue:', error);
// Handle billing issues
}}
/>
```
### **API Access & Control**
```javascript
// Global API for advanced control
window.SandiaChatbotAPI.open();
window.SandiaChatbotAPI.close();
window.SandiaChatbotAPI.minimize();
window.SandiaChatbotAPI.restore();
// Send programmatic messages
window.SandiaChatbotAPI.sendMessage('Hello from the website!');
// Update configuration dynamically
window.SandiaChatbotAPI.updateConfig({
primaryColor: '#ff6b35',
theme: 'gradient'
});
// Manage notifications
window.SandiaChatbotAPI.updateBadge(5);
window.SandiaChatbotAPI.resetUnreadCount();
// Get widget state
const isOpen = window.SandiaChatbotAPI.isOpen();
const messages = window.SandiaChatbotAPI.getMessages();
const config = window.SandiaChatbotAPI.getConfig();
```
## 📱 **Mobile Excellence**
### **Responsive Design**
- **Auto-detection** of mobile devices
- **Full-screen mode** on mobile for better UX
- **Touch-optimized** buttons and interactions
- **Swipe gestures** for navigation
- **iOS zoom prevention** with proper input handling
### **Mobile-Specific Configuration**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
mobileFullScreen: true,
swipeToClose: true,
position: 'bottom-right', // Auto-adjusts on mobile
size: 'lg' // Better visibility on mobile
}}
/>
```
## ♿ **Accessibility & Compliance**
### **WCAG 2.1 AA Compliant**
- ✅ **Screen reader support** with proper ARIA labels
- ✅ **Keyboard navigation** for all interactions
- ✅ **High contrast mode** support
- ✅ **Reduced motion** preferences
- ✅ **Focus management** and visual indicators
- ✅ **Color contrast** meeting accessibility standards
### **Accessibility Configuration**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
highContrast: true,
reducedMotion: true,
// Widget automatically adapts to user preferences
}}
/>
```
## 🔔 **Notifications & Alerts**
### **Smart Notification System**
- **Browser notifications** for new messages when chat is closed
- **Sound effects** for message alerts and interactions
- **Visual badges** with unread message counts
- **Auto-minimize** after inactivity periods
### **Notification Setup**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
soundEnabled: true,
notificationsEnabled: true,
autoMinimize: 5 // Auto-minimize after 5 minutes
}}
onMessage={(msg) => {
// Custom notification handling
if (!document.hasFocus() && msg.role === 'assistant') {
new Notification('New message from support', {
body: msg.content.substring(0, 100),
icon: '/your-icon.png'
});
}
}}
/>
```
## 📊 **Analytics Integration**
### **Google Analytics 4**
```tsx
<SandiaWidget
chatbotId="your-id"
onMessage={(message) => {
gtag('event', 'chat_message', {
event_category: 'chat',
event_label: message.role,
custom_parameter_1: message.content.length
});
}}
onOpen={() => {
gtag('event', 'chat_opened', {
event_category: 'engagement'
});
}}
/>
```
### **Custom Analytics**
```tsx
<SandiaWidget
chatbotId="your-id"
metadata={{
userId: user.id,
sessionId: sessionStorage.getItem('session'),
page: window.location.pathname,
source: 'homepage'
}}
onMessage={(msg) => {
analytics.track('Chat Message', {
direction: msg.role,
timestamp: msg.timestamp,
messageLength: msg.content.length,
conversationLength: messages.length
});
}}
/>
```
## 🌐 **Multi-Language Support**
### **Internationalization Ready**
```tsx
<SandiaWidget
chatbotId="your-id"
styles={{
greeting: t('chat.welcome_message'),
customIcon: '🌍'
}}
chatConfig={{
quickReplies: [
t('chat.quick.hello'),
t('chat.quick.help'),
t('chat.quick.contact')
],
voiceLanguage: locale // 'en-US', 'es-ES', 'fr-FR', etc.
}}
/>
```
## 🎛️ **Framework Integration**
### **Next.js (Recommended)**
```tsx
import dynamic from 'next/dynamic';
const SandiaWidget = dynamic(
() => import('sandia-chatbot-widget').then(mod => mod.SandiaWidget),
{
ssr: false,
loading: () => <div>Loading chat...</div>
}
);
export default function Layout({ children }) {
return (
<>
{children}
<SandiaWidget
chatbotId={process.env.NEXT_PUBLIC_CHATBOT_ID}
styles={{
theme: 'modern',
primaryColor: '#006FEE'
}}
/>
</>
);
}
```
### **Vue.js 3**
```vue
<template>
<div id="app">
<!-- Your content -->
</div>
</template>
<script setup>
import { onMounted } from 'vue';
import { initSandiaChatbot } from 'sandia-chatbot-widget';
onMounted(() => {
initSandiaChatbot({
chatbotId: 'your-chatbot-id',
styles: {
theme: 'gradient',
primaryColor: '#006FEE'
}
});
});
</script>
```
### **Angular**
```typescript
import { Component, OnInit } from '@angular/core';
import { initSandiaChatbot } from 'sandia-chatbot-widget';
@Component({
selector: 'app-root',
template: '<div>Your content</div>'
})
export class AppComponent implements OnInit {
ngOnInit() {
initSandiaChatbot({
chatbotId: 'your-chatbot-id',
styles: {
theme: 'modern',
primaryColor: '#006FEE',
darkMode: true
}
});
}
}
```
## 🔒 **Security & Performance**
### **Enterprise Security**
- 🔐 **Token-based authentication** for private chatbots
- 🌐 **Domain validation** and CORS protection
- 🛡️ **Rate limiting** protection
- 🔒 **HTTPS encryption** for all communications
- 📊 **Audit logging** for compliance
### **Performance Optimizations**
- ⚡ **Lazy loading** of components
- 🗃️ **Virtual scrolling** for long conversations
- 💾 **Smart caching** of messages and assets
- 📦 **Code splitting** for optimal bundle size
- 🔄 **Efficient re-rendering** with React optimization
## 🧪 **Testing & Debugging**
### **Debug Mode**
```tsx
<SandiaWidget
chatbotId="your-id"
debug={true} // Enables detailed console logging
version="3.0" // Specify API version
/>
```
### **Testing Environment**
```bash
# Test with different configurations
npm run test:widget
# Visual regression testing
npm run test:visual
# Performance testing
npm run test:performance
```
## 📚 **Migration Guide v2 → v3**
### **Breaking Changes**
- Minimum React version: 16.8+ (for hooks)
- New required peer dependencies for enhanced features
- Updated event handler signatures include timestamps
### **Migration Steps**
1. **Update package**: `npm install sandia-chatbot-widget@3.0.0`
2. **Update styles**: Add new v3.0 style properties
3. **Update events**: Use new enhanced event signatures
4. **Test thoroughly**: Verify all functionality works as expected
### **Backward Compatibility**
Most v2 configurations continue to work with v3, but you'll miss out on the new features.
## 🆘 **Support & Resources**
### **Documentation**
- 📖 **[Complete API Reference](https://docs.sandia.chat/api)**
- 🎥 **[Video Tutorials](https://docs.sandia.chat/tutorials)**
- 💡 **[Best Practices](https://docs.sandia.chat/best-practices)**
- 🔧 **[Troubleshooting Guide](https://docs.sandia.chat/troubleshooting)**
### **Community & Support**
- 💬 **[Discord Community](https://discord.gg/sandia)**
- 📧 **Email**: support@sandia.chat
- 🐛 **[GitHub Issues](https://github.com/sandia-ai/sandia-chatbot/issues)**
- 📝 **[Feature Requests](https://feedback.sandia.chat)**
### **Professional Services**
- 🏢 **Enterprise Support** available
- 🎨 **Custom Theming** services
- 🔧 **Integration Consulting**
- 📊 **Analytics Setup** assistance
## 📄 **License**
MIT License - free for commercial use.
## 🚀 **Get Started Today**
Ready to integrate the most advanced chatbot widget available?
1. **[Sign up for Sandia AI](https://sandia.chat/signup)**
2. **Create your first chatbot**
3. **Get your chatbot ID**
4. **Install and integrate in minutes!**
**Transform your website's user engagement with Sandia AI Chatbot Widget v3.0** ✨