AI Chat Widget SDK 🤖

A modern, customizable AI chatbot widget SDK with Shadow DOM isolation. Perfect for integrating AI-powered chat functionality into any website while maintaining complete style isolation and security.

!Version
!License
!Size

✨ Features

- 🎨 Customizable Themes - Light/Dark mode with smooth transitions
- 🌍 Multi-language Support - Built-in support for 6 languages (EN, ZH, ES, FR, JA)
- 🔒 Shadow DOM Isolation - Complete style isolation from host page
- 📱 Responsive Design - Works seamlessly on desktop and mobile
- 🎯 Draggable Interface - Move the chat window anywhere on screen
- 💾 Persistent Conversations - LocalStorage integration for chat history
- 📸 Image Upload Support - Send images with messages (PNG, JPG, WebP, GIF)
- ⚡ Lightweight - Less than 50KB minified
- 🔐 Security First - Built-in API key security warnings
- 🎬 Smooth Animations - Professional transitions and effects
- ♿ Accessibility - ARIA labels and keyboard navigation

🚀 Quick Start

$3

``html


`

$3

`javascript
const widget = new AIChatWidget({
apiProvider: 'dify',
apiKey: 'app-your-dify-api-key',
difyConfig: {
baseUrl: 'https://api.dify.ai',
streaming: true
}
}).init();
`

$3

`bash
npm install ai-chat-widget-sdk
`

`javascript
import AIChatWidget from 'ai-chat-widget-sdk';

const widget = new AIChatWidget({
theme: 'dark',
language: 'en',
apiEndpoint: 'https://your-api.com/chat'
}).init();
`

📋 Configuration Options

`javascript
const widget = new AIChatWidget({
// Appearance
position: 'bottom-right', // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
theme: 'light', // 'light' or 'dark'
primaryColor: '#007bff', // Custom primary color
width: 380, // Chat window width
height: 600, // Chat window height
zIndex: 9999, // z-index for stacking

// Content
title: 'AI Assistant', // Chat window title
subtitle: 'Powered by AI', // Subtitle text
welcomeMessage: 'Hello!', // Initial bot message
placeholder: 'Type here...', // Input placeholder
buttonIcon: '💬', // Floating button icon
userAvatar: '👤', // User message avatar
botAvatar: '🤖', // Bot message avatar

// Behavior
language: 'en', // 'en', 'zh', 'es', 'fr', 'ja'
enableDrag: true, // Allow dragging chat window
autoOpen: false, // Auto-open on load
autoOpenDelay: 3000, // Delay before auto-open (ms)
persistConversation: true, // Save chat history
maxMessageLength: 1000, // Max input length

// API Configuration
apiEndpoint: null, // Your chat API endpoint
apiKey: null, // API key (⚠️ Use server-side!)
apiProvider: 'custom', // 'custom' or 'dify'
difyConfig: { // Dify.ai specific config
baseUrl: 'https://api.dify.ai',
user: null, // User identifier
streaming: true // Enable streaming responses
}

// Advanced Features
enableFileUpload: false, // Enable file attachments
enableVoiceInput: false, // Enable voice input
animations: {
enabled: true,
duration: 300
},
sounds: {
enabled: false,
newMessage: null, // Sound file URL
sendMessage: null // Sound file URL
}
});
`

🔌 API Methods

`javascript
// Core Methods
widget.init(); // Initialize the widget
widget.destroy(); // Remove widget from DOM
widget.toggle(); // Toggle open/close
widget.open(); // Open chat window
widget.close(); // Close chat window

// Messaging
widget.sendMessage('Hello!'); // Send a message programmatically

// Customization
widget.setTheme('dark'); // Change theme
widget.setLanguage('zh'); // Change language

// Events
widget.on('message', callback); // Listen for events
widget.off('message', callback); // Remove listener
`

📡 Events

`javascript
widget.on('init', () => {
console.log('Widget initialized');
});

widget.on('open', () => {
console.log('Chat opened');
});

widget.on('close', () => {
console.log('Chat closed');
});

widget.on('message', (data) => {
console.log('User message:', data);
// { type: 'user', content: 'Hello', timestamp: '...' }
});

widget.on('response', (data) => {
console.log('Bot response:', data);
// { type: 'bot', content: 'Hi there!', timestamp: '...' }
});

widget.on('error', (error) => {
console.error('Error occurred:', error);
});

widget.on('theme-change', (theme) => {
console.log('Theme changed to:', theme);
});

widget.on('language-change', (lang) => {
console.log('Language changed to:', lang);
});
`

🔐 Security Best Practices

$3

Never expose API keys in frontend code! The SDK will warn you if it detects an API key without a server endpoint.

#### ❌ Bad (Insecure)
`javascript
const widget = new AIChatWidget({
apiKey: 'sk-abc123...' // NEVER DO THIS!
});
`

#### ✅ Good (Secure)
`javascript
// Frontend
const widget = new AIChatWidget({
apiEndpoint: 'https://your-server.com/api/chat'
// No API key here!
});

// Backend (Node.js example)
app.post('/api/chat', async (req, res) => {
const response = await openai.chat({
apiKey: process.env.OPENAI_API_KEY, // Secure!
message: req.body.message
});
res.json(response);
});
`

🎨 Styling & Theming

The widget uses Shadow DOM for complete style isolation. You can customize the appearance through:

1. Configuration options - Set colors, sizes, and positions
2. Theme presets - Light and dark themes included
3. Custom CSS variables - Override default styles

`javascript
// Custom theme example
const widget = new AIChatWidget({
primaryColor: '#ff6b6b',
theme: 'dark',
width: 400,
height: 550
});
`

🌍 Internationalization

Built-in support for multiple languages:

- 🇬🇧 English (en)
- 🇨🇳 Chinese (zh)
- 🇪🇸 Spanish (es)
- 🇫🇷 French (fr)
- 🇯🇵 Japanese (ja)

`javascript
// Change language dynamically
widget.setLanguage('zh');

// Or set during initialization
const widget = new AIChatWidget({
language: 'es'
});
`

📱 Mobile Support

The widget is fully responsive and adapts to mobile screens:

- Auto-fullscreen on small devices
- Touch-friendly interface
- Optimized keyboard handling
- Gesture support for dragging

🛠️ Development

$3

`bash


Clone the repository

git clone https://github.com/yourusername/ai-chat-widget-sdk.git

Install dependencies

npm install

Start development server

npm run dev

Build for production

npm run build
`

$3

`
ai-widget-sdk/
├── src/
│ ├── index.js # Main entry point
│ ├── core/
│ │ └── WidgetCore.js # Core widget logic
│ ├── components/
│ │ ├── ChatWindow.js # Chat window component
│ │ ├── FloatingButton.js # Floating button
│ │ ├── MessageList.js # Message list
│ │ └── InputArea.js # Input area
│ ├── utils/
│ │ ├── EventEmitter.js # Event system
│ │ ├── StorageManager.js # LocalStorage handler
│ │ ├── DragManager.js # Drag functionality
│ │ └── i18n.js # Translations
│ └── styles/
│ └── main.css # Global styles
├── dist/
│ └── widget.min.js # Production build
├── examples/
│ └── index.html # Demo page
└── package.json
`

🤝 Browser Support

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+
- Mobile browsers (iOS Safari, Chrome Mobile)

📄 License

MIT License - feel free to use in personal and commercial projects.

🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

💡 Examples

$3

`html








Welcome to my site!






`

$3

`jsx
import { useEffect, useRef } from 'react';
import AIChatWidget from 'ai-chat-widget-sdk';

function App() {
const widgetRef = useRef(null);

useEffect(() => {
widgetRef.current = new AIChatWidget({
theme: 'dark',
language: 'en'
}).init();

return () => {
widgetRef.current?.destroy();
};
}, []);

return

;
}
`

$3

`vue



``

🔗 Links

- Documentation
- NPM Package
- GitHub Repository
- Live Demo

📞 Support

For issues and questions:
- Open an issue on GitHub
- Email: support@example.com

---

Made with ❤️ by Your Team