@spectrumsense/spectrum-chat-dev/docs/INTEGRATION_GUIDE.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Spectrum Chat Integration Guide

**Quick guide to add AI chat to your website in 5 minutes**

---

## 🚀 Quick Start

Add AI-powered chat to your website with just a few lines of code.

### Step 1: Get Your Site Key

Contact your Spectrum Chat administrator to get your site key. It looks like this:
```
pub_customer_xyz123
```

### Step 2: Add to Your Website

Add this code before the closing `</body>` tag on every page where you want the chat widget:

```html
<!-- Spectrum Chat Widget -->
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',  // Replace with your site key
    title: 'Help Center',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Step 3: Done! 🎉

The chat widget will appear in the bottom-right corner of your page. Click the floating button to start chatting.

---

## 📋 Prerequisites

Before integrating, ensure:

1. **You have a site key** from your administrator
2. **Your domain is whitelisted** in the API's allowed origins list
3. **Your website uses HTTPS** (HTTP is only allowed for localhost during development)

---

## 🎨 Customization Options

### Basic Configuration

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    
    // Appearance
    title: 'Customer Support',
    primaryColor: '#2563eb',
    fabIcon: '💬',
    
    // Features
    enableCitations: true,
    showIntro: true,
    introText: 'Hello! How can we help you today?'
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### All Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | string | Required | Your API endpoint URL |
| `siteKey` | string | Required | Your public site key |
| `title` | string | `'AI Assistant'` | Chat window title |
| `primaryColor` | string | `'hsl(220 15% 25%)'` | Primary theme color |
| `userColor` | string | `'hsl(220 15% 45%)'` | User message bubble color |
| `aiColor` | string | `'hsl(220 15% 25%)'` | AI message bubble color |
| `fabIcon` | string | `'✦'` | Floating button icon (emoji or text) |
| `fabColor` | string | Same as primary | Floating button color |
| `enableCitations` | boolean | `true` | Show source citations |
| `showIntro` | boolean | `true` | Show welcome message |
| `introText` | string | Default message | Welcome message text |
| `position` | string | `'bottom-right'` | Widget position |
| `width` | string | `'320px'` | Chat window width |
| `height` | string | `'350px'` | Chat window height |

---

## 📍 Widget Positions

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: '...',
    siteKey: '...',
    position: 'bottom-right'  // bottom-right, bottom-left, top-right, top-left
  };
</script>
```

---

## 🎨 Custom Styling Examples

### Example 1: Blue Theme

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    title: 'Help Center',
    primaryColor: '#2563eb',
    userColor: '#3b82f6',
    aiColor: '#1e40af',
    fabIcon: '💬',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Example 2: Green Theme

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    title: 'Support Chat',
    primaryColor: '#059669',
    userColor: '#10b981',
    aiColor: '#047857',
    fabIcon: '🌟',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Example 3: Custom Size & Position

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    title: 'Chat',
    position: 'bottom-left',
    width: '400px',
    height: '600px',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

---

## 🔧 Advanced Integration

### Programmatic Control

Control the chat widget with JavaScript:

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123'
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>

<script>
  // Wait for widget to load
  window.addEventListener('load', () => {
    const chat = window.SpectrumChatGlobal;
    
    // Open chat programmatically
    document.getElementById('help-button').addEventListener('click', () => {
      chat.open();
    });
    
    // Close chat
    document.getElementById('close-help').addEventListener('click', () => {
      chat.close();
    });
    
    // Check if chat is open
    console.log('Chat is open:', chat.isOpen());
    
    // Clear session (logout)
    document.getElementById('logout').addEventListener('click', () => {
      chat.clearSession();
    });
  });
</script>
```

### Event Tracking

Track when users interact with the chat:

```html
<script>
  // Listen for chat events
  document.addEventListener('spectrum-chat-opened', (event) => {
    console.log('Chat opened!');
    // Track with your analytics
    gtag('event', 'chat_opened');
  });
  
  document.addEventListener('spectrum-chat-closed', (event) => {
    console.log('Chat closed!');
    // Track with your analytics
    gtag('event', 'chat_closed');
  });
</script>
```

---

## 🌐 Content Management Systems

### WordPress

Add to your theme's `footer.php` before `</body>`:

```php
<!-- Spectrum Chat Widget -->
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    title: '<?php echo get_bloginfo('name'); ?> Help',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Shopify

Add to **Settings → Checkout → Order status page → Additional scripts**:

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123',
    title: 'Support',
    enableCitations: true
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

### Google Tag Manager

1. Create a new **Custom HTML** tag
2. Add the widget code
3. Set trigger to **All Pages**
4. Publish

---

## 📱 Mobile Responsiveness

The widget automatically adapts to mobile screens:

- **Desktop**: Fixed size widget in corner
- **Tablet**: Responsive width, maintains functionality
- **Mobile**: Full-screen chat experience

No additional configuration needed!

---

## 🔒 Security

### How It Works

The widget uses a secure, two-layer authentication system:

1. **Site Key**: A public identifier tied to your domain
2. **Origin Validation**: The API automatically verifies requests come from your whitelisted domain
3. **JWT Tokens**: Secure, time-limited session tokens (auto-managed)

### What This Means for You

- ✅ Your site key can be public (in HTML source)
- ✅ Only your whitelisted domains can use it
- ✅ Conversations are protected from hijacking
- ✅ Sessions are secure and auto-expire
- ✅ HTTPS required in production

### No Security Configuration Needed

The widget handles all security automatically:
- JWT tokens are created on first message
- Tokens auto-refresh before expiration
- Conversations are bound to your domain
- All happens transparently

---

## 🐛 Troubleshooting

### Widget Not Appearing

**Check:**
1. Script is loaded (check browser console for errors)
2. Configuration is correct (site key, API URL)
3. No JavaScript errors blocking execution

**Solution:**
```javascript
// Enable debug mode
window.SpectrumChatConfig = {
  apiUrl: '...',
  siteKey: '...',
  debug: true  // Shows detailed logs in console
};
```

### "Domain Not Authorized" Error

**Cause:** Your domain is not whitelisted in the API

**Solution:** Contact your administrator to add your domain to the allowed origins list

### Chat Not Responding

**Check:**
1. API is accessible (check network tab)
2. Site key is correct
3. Domain is whitelisted

**Solution:**
```javascript
// Check configuration
console.log(window.SpectrumChatGlobal.getConfig());

// Clear session and retry
window.SpectrumChatGlobal.clearSession();
```

### HTTPS Required Error

**Cause:** Using HTTP on a production domain

**Solution:** 
- Enable HTTPS on your website
- HTTP is only allowed for localhost during development

---

## 📊 Testing

### Development (localhost)

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'http://localhost:8000/api/v1/conversations',  // HTTP OK for localhost
    siteKey: 'pub_customer_xyz123',
    debug: true  // Enable debug logging
  };
</script>
<script src="dist/spectrum-chat.js"></script>
```

### Production

```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://api.yoursite.com/api/v1/conversations',  // HTTPS required
    siteKey: 'pub_customer_xyz123',
    debug: false  // Disable debug in production
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

---

## 🎯 Best Practices

### 1. Use Environment-Specific Configuration

```javascript
// Detect environment
const isDevelopment = window.location.hostname === 'localhost';

window.SpectrumChatConfig = {
  apiUrl: isDevelopment 
    ? 'http://localhost:8000/api/v1/conversations'
    : 'https://api.yoursite.com/api/v1/conversations',
  siteKey: 'pub_customer_xyz123',
  debug: isDevelopment
};
```

### 2. Match Your Brand

```javascript
window.SpectrumChatConfig = {
  apiUrl: '...',
  siteKey: '...',
  title: 'YourBrand Support',
  primaryColor: '#your-brand-color',
  fabIcon: '💬'  // Or your brand emoji
};
```

### 3. Enable Citations

```javascript
window.SpectrumChatConfig = {
  apiUrl: '...',
  siteKey: '...',
  enableCitations: true  // Shows sources for AI responses
};
```

### 4. Monitor Usage

```javascript
// Track chat interactions
document.addEventListener('spectrum-chat-opened', () => {
  // Your analytics code
  analytics.track('Chat Opened');
});
```

---

## 📚 Additional Resources

### Documentation

- [Security Implementation](./SECURITY_IMPLEMENTATION.md) - Detailed security documentation
- [API Reference](./API_REFERENCE.md) - Complete API documentation
- [Migration Guide](./MIGRATION_GUIDE.md) - Upgrading from older versions

### Support

- **Questions?** Check the [API Reference](./API_REFERENCE.md)
- **Issues?** Enable debug mode: `debug: true`
- **Need help?** Contact your administrator

---

## ✅ Integration Checklist

Before going live:

- [ ] Site key obtained from administrator
- [ ] Domain added to allowed origins list
- [ ] HTTPS enabled on production site
- [ ] Widget tested on staging environment
- [ ] Configuration customized (title, colors, etc.)
- [ ] Debug mode disabled for production
- [ ] Analytics/tracking configured (optional)
- [ ] Team trained on widget features

---

## 🚀 You're All Set!

That's it! Your AI chat widget is now integrated and ready to help your users.

### Quick Reference

**Minimal Setup:**
```html
<script>
  window.SpectrumChatConfig = {
    apiUrl: 'https://your-api-domain.com/api/v1/conversations',
    siteKey: 'pub_customer_xyz123'
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

**Full Control:**
```javascript
const chat = window.SpectrumChatGlobal;
chat.open();          // Open widget
chat.close();         // Close widget
chat.isOpen();        // Check state
chat.clearSession();  // Clear data
```

---

**Need more details?** Check out the complete [Security Implementation Guide](./SECURITY_IMPLEMENTATION.md) or [API Reference](./API_REFERENCE.md).

**Happy chatting! 🎉**