@conversea/widget
v1.2.0
Published
Embeddable AI chatbot widget for websites with React and Next.js components
Maintainers
jahidulsaeidReadme
Conversea Widget Integration Guide
Package Overview
The @conversea/widget is a lightweight, framework-agnostic npm package that provides an embeddable AI chat widget for websites. Companies can integrate this widget using their API key to provide AI-powered customer support based on their products, services, and FAQs.
Installation
npm install @conversea/widget
# or
yarn add @conversea/widget
# or
pnpm add @conversea/widgetQuick Start
1. Basic Integration (ES Modules)
import ConverseaWidget from '@conversea/widget';
// Initialize the widget
const widget = ConverseaWidget.init({
apiKey: 'tc_your_company_api_key',
position: 'bottom-right',
themeColor: '#3B82F6',
welcomeMessage: 'Hello! How can I help you today?',
placeholder: 'Type your message...',
autoOpen: false
});2. CommonJS Integration
const ConverseaWidget = require('@conversea/widget');
const widget = ConverseaWidget.init({
apiKey: 'tc_your_company_api_key',
// ... other options
});3. Browser Integration (UMD)
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<!-- Include the widget -->
<script src="https://unpkg.com/@conversea/widget@latest/dist/index.umd.js"></script>
<script>
ConverseaWidget.init({
apiKey: 'tc_your_company_api_key',
position: 'bottom-right',
themeColor: '#3B82F6',
welcomeMessage: 'Hello! How can I help you today?'
});
</script>
</body>
</html>Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| apiKey | string | Required | Your company's API key (starts with 'tc_') |
| position | string | 'bottom-right' | Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left' |
| themeColor | string | '#3B82F6' | Primary theme color for the widget |
| welcomeMessage | string | 'Hello! How can I help you today?' | Initial message shown to users |
| placeholder | string | 'Type your message...' | Input field placeholder text |
| height | string | '500px' | Chat window height |
| width | string | '350px' | Chat window width |
| autoOpen | boolean | false | Whether to auto-open the chat window |
| showCloseButton | boolean | true | Show close button in chat header |
| enableSounds | boolean | false | Enable notification sounds |
API Methods
ConverseaWidget.init(config)
Initializes and returns a new chat widget instance.
const widget = ConverseaWidget.init({
apiKey: 'tc_your_api_key',
position: 'bottom-right'
});ConverseaWidget.destroy()
Removes the widget from the page and cleans up resources.
ConverseaWidget.destroy();ConverseaWidget.getInstance()
Returns the current widget instance or null if no widget is active.
const currentWidget = ConverseaWidget.getInstance();
if (currentWidget) {
console.log('Widget is active');
}Instance Methods
const widget = ConverseaWidget.init(config);
// Update configuration
widget.updateConfig({
themeColor: '#FF6B6B',
welcomeMessage: 'Hi there! How can I assist you?'
});
// Get current state
const state = widget.getState();
console.log(state.isOpen, state.messages);
// Manually destroy
widget.destroy();Advanced Usage
Dynamic Configuration
// Initialize with basic config
let widget = ConverseaWidget.init({
apiKey: 'tc_your_api_key'
});
// Update based on user preference
function updateTheme(color) {
widget.updateConfig({
themeColor: color
});
}
// Update welcome message based on time
const hour = new Date().getHours();
const welcomeMessage = hour < 12
? 'Good morning! How can I help?'
: 'Good afternoon! How can I assist you?';
widget.updateConfig({ welcomeMessage });Conditional Loading
// Only load widget for specific pages
if (window.location.pathname.includes('/support')) {
ConverseaWidget.init({
apiKey: 'tc_your_api_key',
autoOpen: true,
welcomeMessage: 'Welcome to our support center!'
});
}React Integration
import { useEffect, useRef } from 'react';
import ConverseaWidget from '@conversea/widget';
function App() {
const widgetRef = useRef(null);
useEffect(() => {
// Initialize widget
widgetRef.current = ConverseaWidget.init({
apiKey: process.env.REACT_APP_CONVERSEA_API_KEY,
position: 'bottom-right',
themeColor: '#3B82F6'
});
// Cleanup on unmount
return () => {
if (widgetRef.current) {
widgetRef.current.destroy();
}
};
}, []);
return (
<div className="App">
{/* Your app content */}
</div>
);
}Vue.js Integration
<template>
<div id="app">
<!-- Your app content -->
</div>
</template>
<script>
import ConverseaWidget from '@conversea/widget';
export default {
name: 'App',
mounted() {
this.widget = ConverseaWidget.init({
apiKey: process.env.VUE_APP_CONVERSEA_API_KEY,
position: 'bottom-right',
themeColor: '#3B82F6'
});
},
beforeDestroy() {
if (this.widget) {
this.widget.destroy();
}
}
};
</script>Getting Your API Key
- Sign up at Conversea Admin Portal
- Complete your company profile
- Navigate to Settings > API Keys
- Generate a new API key
- Copy the key (starts with 'tc_') and use it in your widget configuration
Customization
Custom Styling
The widget automatically injects minimal CSS. You can override styles:
/* Customize chat bubble */
#conversea-widget .chat-bubble {
background-color: #your-color !important;
width: 70px !important;
height: 70px !important;
}
/* Customize chat window */
#conversea-widget .chat-window {
border-radius: 20px !important;
box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3) !important;
}Multiple Widgets
// Not recommended, but possible
const supportWidget = ConverseaWidget.init({
apiKey: 'tc_support_key',
position: 'bottom-right'
});
// Destroy first widget before creating second
supportWidget.destroy();
const salesWidget = ConverseaWidget.init({
apiKey: 'tc_sales_key',
position: 'bottom-left'
});TypeScript Support
The package includes full TypeScript declarations:
import ConverseaWidget, { ChatWidgetConfig, ChatWidget } from '@conversea/widget';
const config: ChatWidgetConfig = {
apiKey: 'tc_your_api_key',
position: 'bottom-right',
themeColor: '#3B82F6'
};
const widget: ChatWidget = ConverseaWidget.init(config);Browser Support
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
- Mobile browsers (iOS Safari, Chrome Mobile)
Performance
- Bundle Size: ~11KB gzipped
- Runtime: Zero external dependencies
- Memory: < 2MB typical usage
- Load Time: < 100ms initialization
Troubleshooting
Common Issues
Widget not appearing
- Check if API key is valid
- Ensure key starts with 'tc_'
- Check browser console for errors
API key validation failed
- Verify API key is active in admin portal
- Check network connectivity
- Ensure correct API endpoint
Styling conflicts
- Widget uses CSS isolation
- Check for z-index conflicts
- Use
!importantfor overrides
Debug Mode
// Enable debug logging
window.CONVERSEA_DEBUG = true;
ConverseaWidget.init({
apiKey: 'tc_your_api_key'
});Examples
See the /examples directory for complete integration examples:
- Vanilla HTML/JS
- React application
- Vue.js application
- WordPress plugin
- Shopify integration
Support
For technical support:
- Documentation: docs.conversea.ai
- Issues: GitHub Issues
- Email: [email protected]
License
MIT License - see LICENSE file for details.