npm package: @mazaal-dev/widget
Description: AI Agent widget for embedding on any website.
Author: Mazaal AI
Latest version: 1.1.4

# 🤖 Mazaal Chat Widget

A lightweight, embeddable AI chat widget for any website. Built with React and TypeScript, designed to be easily integrated and highly customizable.

## 🚀 Quick Start

### Basic Integration

```html
<!-- Mazaal AI Chat Widget -->
<script src="https://cdn.jsdelivr.net/npm/@mazaal-dev/widget@latest/dist/mazaal-widget.iife.js" async 
  onload='window.mazaalWidget = window.ChatWidget?.init({
    agentId: "cmf6eh6mq00019kz13qk7zwe0",
    apiUrl: "https://api.mazaal.ai",
    title: "Demo Agent",
    subtitle: "We'\''re here to help",
    primaryColor: "#FF6A2A",
    position: "bottom-right",
    theme: "light",
    welcomeMessage: "Hi! How can I help you today?",
    placeholder: "Type your message here...",
    enableIdentification: true,
    identifyAfterMessages: 3,
    identificationFields: { name: true, email: true, phone: false, company: false }
  })'>
</script>
<!-- End Mazaal AI Chat Widget -->
```

## 📚 Enhanced Examples

For comprehensive examples, advanced configurations, and use cases, see our [Enhanced Generator Samples](./docs/ENHANCED_GENERATOR_SAMPLES.md) documentation.

## ⚙️ Configuration Options

```typescript
interface WidgetConfig {
  // Required
  agentId: string;                   // Your AI agent ID
  
  // Optional
  apiUrl?: string;                   // API base URL (default: https://api.mazaal.ai)
  theme?: 'light' | 'dark';          // Theme (default: light)
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  welcomeMessage?: string;           // Initial bot message
  placeholder?: string;              // Input placeholder text
  primaryColor?: string;             // Brand color (default: #FF6A2A)
  logo?: string;                     // Logo URL for header
  title?: string;                    // Widget title
  subtitle?: string;                 // Widget subtitle
  agentName?: string;                // Agent name for display
  enableMarkdown?: boolean;          // Enable markdown parsing (default: true)
  enableAttachments?: boolean;       // Enable file uploads (default: false)
  maxHeight?: number;                // Max widget height (default: 600)
  maxWidth?: number;                 // Max widget width (default: 400)
  zIndex?: number;                   // CSS z-index (default: 1000)
  showAvatar?: boolean;              // Show agent avatar (default: true)
  enableNotifications?: boolean;     // Enable browser notifications (default: true)
  
  // Identification settings
  enableIdentification?: boolean;    // Enable user identification (default: false)
  identifyAfterMessages?: number;    // Ask for ID after X messages (default: 3)
  identificationFields?: {           // Which fields to collect
    name?: boolean;
    email?: boolean;
    phone?: boolean;
    company?: boolean;
  };
  identificationRequired?: boolean;  // Make identification mandatory (default: false)
  identificationMessage?: string;    // Custom ID request message
}
```

### Dynamic Configuration Updates

```javascript
// Update widget configuration after initialization
if (window.mazaalWidget) {
  window.mazaalWidget.updateConfig({
    primaryColor: "#e91e63",
    title: "New Title",
    welcomeMessage: "Updated welcome message!"
  });
}
```

### Multiple Widget Instances

```javascript
// Support widget
const supportWidget = ChatWidget.init({
  agentId: "support-agent-id",
  position: "bottom-right",
  primaryColor: "#007bff",
  title: "Customer Support",
  enableIdentification: true,
  identificationRequired: true
});

// Sales widget
const salesWidget = ChatWidget.init({
  agentId: "sales-agent-id", 
  position: "bottom-left",
  primaryColor: "#28a745",
  title: "Sales Team",
  enableIdentification: true,
  identifyAfterMessages: 1
});
```

### Error Handling

```javascript
// Simple error handling
(function() {
  if (window.mazaalWidgetInitialized) return;
  
  const script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/npm/@mazaal-dev/widget@latest/dist/mazaal-widget.iife.js';
  script.async = true;
  
  script.onload = function() {
    if (window.ChatWidget) {
      window.mazaalWidget = window.ChatWidget.init({
        agentId: "your-agent-id",
        apiUrl: "https://api.mazaal.ai"
      });
      window.mazaalWidgetInitialized = true;
    }
  };
  
  script.onerror = function() {
    console.error('Failed to load Mazaal widget');
  };
  
  document.head.appendChild(script);
})();
```