🤖 ConvAI Widget

A lightweight, embeddable ConvAI widget that works in any web page - just like ElevenLabs! Simply drop in a script tag and start chatting with your AI agent.

✨ Features

• 🚀 Zero Dependencies - Pure vanilla JavaScript
• 🎨 Customizable Themes - Light and dark modes
• 📱 Responsive Design - Works on all devices
• 🔧 Easy Integration - One script tag, that's it!
• 💬 Real-time Chat - Smooth conversation flow
• 🎯 Agent-based - Each widget connects to specific agents
• 🛡️ Shadow DOM - Isolated styles, no conflicts

🚀 Quick Start

1. Add to Your Website

<!-- Basic usage -->
<my-convai-widget agent-id="your-agent-id"></my-convai-widget>
<script src="https://unpkg.com/@ahmad/convai-widget@latest" async></script>

2. That's It! 🎉

Your widget is now live and ready to chat. Users can type messages and get responses from your AI agent.

📖 Usage Examples

Basic Widget

<my-convai-widget agent-id="customer-support-bot"></my-convai-widget>
<script src="https://unpkg.com/@ahmad/convai-widget@latest" async></script>

Dark Theme

<my-convai-widget agent-id="your-agent-id" theme="dark"></my-convai-widget>
<script src="https://unpkg.com/@ahmad/convai-widget@latest" async></script>

Custom Size

<my-convai-widget 
    agent-id="your-agent-id" 
    width="500px" 
    height="600px"
    theme="dark">
</my-convai-widget>
<script src="https://unpkg.com/@ahmad/convai-widget@latest" async></script>

🎛️ Configuration Options

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | agent-id | string | "default" | Your AI agent identifier | | theme | string | "light" | Theme: "light" or "dark" | | width | string | "400px" | Widget width (CSS value) | | height | string | "500px" | Widget height (CSS value) |

🔧 JavaScript API

Get Widget Reference

const widget = document.querySelector('my-convai-widget');

Send Message Programmatically

widget.sendMessageToWidget('Hello from JavaScript!');

Clear All Messages

widget.clearMessages();

Get Message History

const messages = widget.getMessages();
console.log(messages);

Listen for Events

// Listen for new messages
widget.addEventListener('message-sent', (event) => {
    console.log('Message sent:', event.detail);
});

widget.addEventListener('message-received', (event) => {
    console.log('Message received:', event.detail);
});

🎨 Styling

The widget uses Shadow DOM for style isolation, so it won't conflict with your existing CSS. However, you can still customize it:

/* Target the widget container */
my-convai-widget {
    --primary-color: #your-color;
    --bg-color: #your-bg;
    --text-color: #your-text;
    --border-color: #your-border;
}

🧪 Testing Locally

1. Clone this repository
2. Open test.html in your browser
3. Try the interactive demo with different themes and settings

# Serve locally (optional)
npx serve .
# Open http://localhost:3000/test.html

📦 Installation

Via CDN (Recommended)

<script src="https://unpkg.com/@ahmad/convai-widget@latest" async></script>

Via npm

npm install @ahmad/convai-widget

import '@ahmad/convai-widget';
// Widget is now available globally

🔌 Backend Integration

Currently, the widget includes simulated responses. To connect to your real AI service:

1. Replace the simulateAgentResponse method in index.js
2. Add your API endpoint
3. Handle authentication and error cases

Example:

async simulateAgentResponse(userMessage) {
    try {
        const response = await fetch(`https://your-api.com/chat/${this.agentId}`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ message: userMessage })
        });
        
        const data = await response.json();
        this.addMessage(data.reply, 'agent');
    } catch (error) {
        this.addMessage('Sorry, I encountered an error.', 'agent');
    }
}

🌐 Browser Support

• ✅ Chrome 54+
• ✅ Firefox 63+
• ✅ Safari 10.1+
• ✅ Edge 79+
• ✅ Mobile browsers

📄 License

MIT License - feel free to use in your projects!

🤝 Contributing

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

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

🎯 Roadmap

• [ ] Voice input/output
• [ ] File upload support
• [ ] Multiple language support
• [ ] Advanced theming options
• [ ] Analytics integration
• [ ] A/B testing support

Made with ❤️ by Ahmad

Just like ElevenLabs, but yours! 🚀