@helllo-ai/agent-chat-widget/README.md

Bot Swarm Agent Chat Widget - Embeddable chat widget for AI agents

# @helllo-ai/agent-chat-widget

[![npm version](https://badge.fury.io/js/%40helllo-ai%2Fagent-chat-widget.svg)](https://badge.fury.io/js/%40helllo-ai%2Fagent-chat-widget)
[![unpkg](https://img.shields.io/badge/CDN-unpkg-blue)](https://unpkg.com/@helllo-ai/agent-chat-widget/)
[![jsdelivr](https://data.jsdelivr.com/v1/package/npm/@helllo-ai/agent-chat-widget/badge)](https://www.jsdelivr.com/package/npm/@helllo-ai/agent-chat-widget)

An embeddable chat widget for Helllo AI agents. This widget allows you to easily add AI-powered chat functionality to any website.

## 🚀 Quick Start

### Via unpkg (CDN)

#### Production Environment
```html
<script src="https://unpkg.com/@helllo-ai/agent-chat-widget@latest/agent-chat.prod.js"></script>
<script>
  // Initialize the widget (uses production URLs automatically)
  window.AgentChatWidget.init({
    agentId: 'your-agent-id',
    embedKey: 'your-embed-key',
    primaryColor: '#0f172a',
    backgroundColor: '#ffffff'
  });
</script>
```

#### Staging Environment
```html
<script src="https://unpkg.com/@helllo-ai/agent-chat-widget@staging/agent-chat.staging.js"></script>
<script>
  // Initialize the widget (uses staging URLs automatically)
  window.AgentChatWidget.init({
    agentId: 'your-agent-id',
    embedKey: 'your-embed-key'
  });
</script>
```

#### Development/Latest
```html
<script src="https://unpkg.com/@helllo-ai/agent-chat-widget@latest/agent-chat.latest.js"></script>
```

### Via jsDelivr (Alternative CDN)
```html
<!-- Production -->
<script src="https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@latest/agent-chat.prod.js"></script>

<!-- Staging -->
<script src="https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@staging/agent-chat.staging.js"></script>

<!-- Development -->
<script src="https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@latest/agent-chat.latest.js"></script>
```

### Via npm
```bash
npm install @helllo-ai/agent-chat-widget
```

```javascript
import '@bot-swarm/agent-chat-widget/agent-chat.latest.js';
```

## 📦 Available Versions

| File | Cache Strategy | Use Case |
|------|---------------|----------|
| `agent-chat.latest.js` | No cache | Development, always latest |
| `agent-chat.v0.1.0.js` | 1 year cache | Production (specific version) |
| `agent-chat.v0.1.js` | 1 month cache | Stay updated within minor version |
| `agent-chat.v0.js` | 1 week cache | Stay updated within major version |

## ⚙️ Configuration

```javascript
window.AgentChatWidget.init({
  agentId: 'your-agent-id',           // Required: Your agent ID
  embedKey: 'your-embed-key',         // Required: Your embed key
  primaryColor: '#0f172a',            // Optional: Primary color
  backgroundColor: '#ffffff',         // Optional: Background color
  title: 'Chat with us',              // Optional: Widget title
  apiBaseUrl: 'https://api.helllo.ai', // Optional: API base URL
  voiceServiceUrl: 'https://voice.helllo.ai', // Optional: Voice service URL
  wsUrl: null,                        // Optional: WebSocket URL override
  allowedDomains: ['example.com']     // Optional: Domain restrictions
});
```

## 🎯 Widget API

```javascript
// Initialize
const widget = window.AgentChatWidget.init(config);

// Programmatic control
widget.open();    // Open chat panel
widget.close();   // Close chat panel
widget.destroy(); // Remove widget completely
```

## 🔧 Development

### Building from source
```bash
# Install dependencies
npm install

# Build widget files (choose environment)
npm run build          # Development/latest
npm run build:staging  # Staging environment
npm run build:prod     # Production environment

# Version bump
npm run version:patch  # or version:minor, version:major

# Publish to npm (choose environment)
npm run publish:public    # Production release
npm run publish:staging   # Staging release
```

### File Structure
```
packages/agent-chat-widget/
├── agent-chat.latest.js     # Latest development version
├── agent-chat.staging.js    # Staging environment version
├── agent-chat.prod.js       # Production environment version
├── agent-chat.v0.1.0.js     # Specific version (production)
├── agent-chat.v0.1.js       # Minor version (auto-updates)
├── agent-chat.v0.js         # Major version (auto-updates)
├── build.js                 # Build script
├── package.json
└── README.md
```

## 📋 CDN URLs

### unpkg

#### Production Environment
```
https://unpkg.com/@helllo-ai/agent-chat-widget@latest/agent-chat.prod.js
https://unpkg.com/@helllo-ai/agent-chat-widget@0.1.0/agent-chat.v0.1.0.js
https://unpkg.com/@helllo-ai/agent-chat-widget@0/agent-chat.v0.js
```

#### Staging Environment
```
https://unpkg.com/@helllo-ai/agent-chat-widget@staging/agent-chat.staging.js
https://unpkg.com/@helllo-ai/agent-chat-widget@0.1.0-staging/agent-chat.v0.1.0.js
```

#### Development/Latest
```
https://unpkg.com/@helllo-ai/agent-chat-widget@latest/agent-chat.latest.js
```

### jsDelivr

#### Production Environment
```
https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@latest/agent-chat.prod.js
https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@0.1.0/agent-chat.v0.1.0.js
```

#### Staging Environment
```
https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@staging/agent-chat.staging.js
https://cdn.jsdelivr.net/npm/@helllo-ai/agent-chat-widget@0.1.0-staging/agent-chat.v0.1.0.js
```

## 📄 License

MIT © [Helllo AI](https://helllo.ai)

## 🐛 Issues

Report bugs and request features at: [GitHub Issues](https://github.com/helllo-ai/agent-chat-widget/issues)

## 📞 Support

For support, email support@helllo.ai or visit [helllo.ai](https://helllo.ai)