Chat Widget Embed

Add our chat widget to any website with a simple script tag. No framework required.

Quick Start

Add the widget to your website in two steps:

<!-- 1. Add the script -->
<script defer src="https://unpkg.com/@opencx/widget@latest/dist-embed/script.js"></script>

<!-- 2. Initialize the widget -->
<script>
  initOpenScript({
    token: 'YOUR_BOT_TOKEN',
    initialMessages: ['How can I help you today?'],
    settings: {
      persistSession: true,
      useSoundEffects: true
    }
  });
</script>

Configuration Options

Essential Options

{
  // Required
  token: string;                // Your bot authentication token
  initialMessages: string[];    // Welcome messages
  
  // Optional
  apiUrl?: string;             // Custom API endpoint
  socketUrl?: string;          // Custom WebSocket URL
  debug?: boolean;             // Enable debug mode
  language?: string;           // Interface language (default: "en")
}

Network Configuration

{
  // API Configuration
  apiUrl?: string;             // Custom API endpoint
  socketUrl?: string;          // Custom WebSocket URL
}

Action Configuration

These parameters are sent with every action request when the bot needs to execute an action or function:

{
  // Action Request Parameters
  headers?: {                  // Headers for action requests
    "Authorization": "Bearer token",
    "Custom-Header": "value"
  },
  queryParams?: {              // Query parameters for action URLs
    "workspace": "default",
    "environment": "prod"
  },
  pathParams?: {               // Path parameters for action URLs
    "version": "v1",
    "region": "us-east"
  }
}

For example, if your bot needs to make an API call to fetch order information:

{
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "X-API-Version": "2023-01"
  },
  queryParams: {
    "include_details": "true"
  },
  pathParams: {
    "store_id": "main"
  }
}

User Configuration

{
  user?: {
    external_id?: string;     // External user ID
    name?: string;            // User's name
    email?: string;           // User's email
    phone?: string;           // User's phone
    avatarUrl?: string;       // User's avatar URL
    customData?: {            // Additional user data
      [key: string]: string
    }
  },
  collectUserData?: boolean   // Show user data form before chat
}

Theme Customization

{
  theme?: {
    primaryColor: string;     // Primary color for the widget
    triggerOffset: string;    // Distance from edges for the widget button
  },
  
  // Assets
  assets?: {
    organizationLogo?: string; // URL to your organization's logo
  }
}

Bot Configuration

{
  bot?: {
    name?: string;           // Bot's display name
    avatarUrl?: string;      // Bot's avatar URL
  }
}

Behavior Settings

{
  settings?: {
    persistSession?: boolean;    // Keep chat history
    useSoundEffects?: boolean;   // Enable sound notifications
  },
  
  // Sound Effects
  soundEffectFiles?: {
    messageArrived?: string;     // Custom sound file URL for new messages
  }
}

For custom UI components and rich responses (like forms, data visualizations, etc.), you’ll need to use our React SDK. The embed script only supports basic text responses. See our Custom UI Components guide for more details.

Complete Example

const config = {
  // Required
  token: "YOUR_BOT_TOKEN",
  initialMessages: ["Hello! How can I help?"],
  
  // Network
  apiUrl: "https://api.example.com",
  headers: { "Custom-Header": "value" },
  queryParams: { "source": "website" },
  
  // User
  user: {
    name: "John Doe",
    email: "john@example.com",
    customData: {
      userId: "123"
    }
  },
  
  // Theme
  theme: {
    primaryColor: "#0066ff",
    triggerOffset: "20px"
  },
  
  // Bot
  bot: {
    name: "AI Assistant",
    avatarUrl: "/bot-avatar.png"
  },
  
  // Settings
  settings: {
    persistSession: true,
    useSoundEffects: true
  },
  
  // Debug
  debug: false,
  language: "en"
};

// Initialize widget
initOpenScript(config);

Event Listeners

Listen to widget events:

// Message events
window.addEventListener('opencx:message', (event) => {
  const { message, type } = event.detail;
  console.log(`New ${type} message:`, message);
});

// State changes
window.addEventListener('opencx:state', (event) => {
  const { state } = event.detail;
  console.log('Widget state:', state);
});

// User events
window.addEventListener('opencx:user', (event) => {
  const { action, data } = event.detail;
  console.log(`User ${action}:`, data);
});

Common Issues

For more extensive customization options and advanced features: