🔷 WebChat - Embedded Chat

📦 Quick Start

1. Add the widget to your website

<div id="webchat-component"></div>

<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
<script>
WebChat.initialize({
    title: "Customer Support",
    placeholder: "Ask us anything...",
    primaryColor: "#667eea"
});
</script>

2. That's it! 🎉

The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!

⚙️ Configuration Options

interface WebChatConfig {
  title?: string;                       // Chat window title
  placeholder?: string;                 // Input placeholder text
  primaryColor?: string;                // Primary theme color
  apiKey?: string;                      // Your chatbot UID (required for API)
  position?: 'bottom-right' | 'bottom-left'; // Widget position
  initialMessage?: string;              // Custom initial bot message
  closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
  closeButtonText?: string;             // Text for close button (when type is 'text')
  closeButtonCustomIcon?: string;       // Custom icon SVG or URL (when type is 'custom')
  marginBottom?: number;                // Distance from bottom edge in pixels (default: 16)
  marginSide?: number;                  // Distance from left/right edge in pixels (default: 16)
  mobile?: WebChatPositionConfig;       // Mobile-specific position settings
  desktop?: WebChatPositionConfig;      // Desktop-specific position settings
}

interface WebChatPositionConfig {
  position?: 'bottom-right' | 'bottom-left';
  marginBottom?: number;
  marginSide?: number;
}

Example:

WebChat.initialize({
    title: "Chat Assistant",
    placeholder: "Type your message...",
    primaryColor: "#007bff",
    apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
    position: "bottom-right",
    initialMessage: "Hi! 👋 I'm your virtual assistant. How can I help you today?",
    closeButtonIcon: "default", // or "text" or "custom"
    marginBottom: 20,           // Distance from bottom edge (default: 16px)
    marginSide: 20,             // Distance from side edge (default: 16px)
    // Device-specific overrides
    mobile: {
        position: "bottom-left",
        marginBottom: 80,
        marginSide: 15
    },
    desktop: {
        position: "bottom-right", 
        marginBottom: 30,
        marginSide: 30
    }
});

💬 EmbedChat - Embedded Chat

EmbedChat allows you to integrate a complete chat system directly into any element of your web page, with full control over size, position, and style.

📦 Installation and Basic Usage

Direct HTML

<!-- Element to embed the chat -->
<div id="my-chat-embed"></div>

<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
  EmbedChat.initialize({
    elementId: "my-chat-embed",
    apiKey: "your-api-key",
    title: "Chat Assistant",
    width: 400,
    height: 500
  });
</script>

JavaScript/TypeScript

import { EmbedChatAPI } from './webchat';

const chatInstance = EmbedChatAPI.initialize({
  elementId: "my-chat-embed",
  apiKey: "your-api-key",
  title: "Chat Assistant",
  width: 400,
  height: 500
});

⚙️ Complete Configuration

Required Properties

EmbedChatAPI.initialize({
  // REQUIRED
  elementId: "my-chat-embed",              // ID of the HTML element to embed the chat
  apiKey: "your-api-key",                  // API key of the service
})

Content Properties

EmbedChatAPI.initialize({
  // Texts and content
  title: "Chat Assistant",        // Title shown in the header
  placeholder: "Type your message...",    // Input placeholder text
  initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
  footerText: "Powered by NotChatBot", // Footer text (optional)
  avatar: "https://example.com/avatar.jpg", // Bot avatar URL
})

Size Properties

EmbedChatAPI.initialize({
  // Main dimensions
  width: 400,                        // Width: number (px) or string ("100%", "50vw")
  height: 500,                       // Height: number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,                     // Maximum width
  maxHeight: "90vh",                 // Maximum height (accepts CSS units)
  minWidth: 280,                     // Minimum width (default: 280px)
  minHeight: 300,                    // Minimum height (default: 300px)
})

Appearance Properties

EmbedChatAPI.initialize({
  // Colors
  primaryColor: "#3b82f6",           // Primary color (header, buttons, etc.)
  textColor: "#333333",              // Message text color
  bubbleUserColor: "#3b82f6",        // User message bubble background
  chatBackground: "#ffffff",         // Chat background color
  footerColor: "#f3f4f6",            // Footer background color
  
  // Borders
  borderRadius: 12,                  // Border radius: number (px) or string
  border: "2px solid #3b82f6",       // Custom border (CSS border)
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  chatTransparent: false,            // If true, chat background is transparent
})

Section Control Properties

EmbedChatAPI.initialize({
  showHeader: true,                  // Show/hide header (default: true)
  showFooter: true,                  // Show/hide footer (default: true if footerText is provided)
})

Input Configuration

EmbedChatAPI.initialize({
  input: {
    backgroundColor: "#ffffff",      // Input area background color
    inputBorder: "2px solid #e5e7eb", // Input field border
    inputBorderRadius: "8px",        // Input border radius
    iconColor: "#3b82f6"             // Send icon color
  }
})

Custom CSS

EmbedChatAPI.initialize({
  customCSS: `
    #notchatbot-embed-chat {
      /* Your custom styles here */
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
    }
  `
})

Size Control

EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Main sizes
  width: 400,           // Number (px) or string ("100%", "50vw")
  height: 500,          // Number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,        // Maximum size
  maxHeight: "90vh",    // Can use CSS units
  minWidth: 280,        // Minimum size
  minHeight: 300,
  
  // More
  width: "100%",        // Occupies the entire width of the container
  height: "50vh",       // 50% of the window height
  maxWidth: "500px",    // Maximum 500px
})

Visual Customization

EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Borders and effects
  borderRadius: 12,                 // Border radius in px
  border: "2px solid #3b82f6",     // Custom border
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  // Section control
  showHeader: true,                 // Show/hide header (default: true)
  showFooter: true,                 // Show/hide footer (default: true if footerText is provided)
  
  // 🆕 Custom CSS
  customCSS: `
    #notchatbot-embed-chat {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
      border-radius: 20px !important;
    }
  `
})

📋 Complete Property Reference

EmbedChatConfig Configuration Table

| Property | Type | Required | Default | Description | |-----------|------|-----------|---------|-------------| | elementId | string | ✅ | - | ID of the HTML element where the chat will be mounted | | apiKey | string | ✅ | - | API key for the chat service | | title | string | ❌ | "Chat" | Title shown in the chat header | | placeholder | string | ❌ | "Type your message..." | Input field placeholder text | | primaryColor | string | ❌ | "#3b82f6" | Primary color (header, buttons, links) | | avatar | string | ❌ | - | Bot avatar URL (optional) | | initialMessage | string | ❌ | - | First message shown by the bot | | footerText | string | ❌ | - | Footer text (if provided, it is shown) | | width | string \| number | ❌ | "100%" | Chat width (px or CSS units) | | height | string \| number | ❌ | 400 | Chat height (px or CSS units) | | maxWidth | string \| number | ❌ | "100%" | Maximum chat width | | maxHeight | string \| number | ❌ | "100vh" | Maximum chat height | | minWidth | string \| number | ❌ | 280 | Minimum chat width | | minHeight | string \| number | ❌ | 300 | Minimum chat height | | showHeader | boolean | ❌ | true | Show/hide the header | | showFooter | boolean | ❌ | true | Show/hide the footer (if footerText is provided) | | borderRadius | string \| number | ❌ | 12 | Container border radius | | border | string | ❌ | "1px solid #e5e7eb" | Container border (CSS border) | | boxShadow | string | ❌ | "0 10px 25px..." | Container shadow | | chatTransparent | boolean | ❌ | false | If true, chat background is transparent | | chatBackground | string | ❌ | "#ffffff" | Chat background color | | textColor | string | ❌ | - | Message text color | | bubbleUserColor | string | ❌ | - | User message bubble background color | | footerColor | string | ❌ | - | Footer background color | | input | EmbedChatInputConfig | ❌ | - | Input-specific configuration | | customCSS | string | ❌ | - | Custom CSS for the chat |

🛠️ Dynamic Control via API and Events

WebChat exposes a global API and custom events to dynamically control the position, padding, and visibility of the widget from anywhere in your app or from the browser console.

WebChat Global Methods

window.openWebChat();           // Open the floating chat
window.closeWebChat();          // Close the floating chat
window.toggleWebChat();         // Toggle open/close
window.unmountWebChat();        // Unmount the floating chat
window.mountWebChat();          // Mount the floating chat if it was unmounted
window.hideWebChat();           // Hide the chat (display: none)
window.showWebChat();           // Show the chat if it was hidden
window.injectWebChatCSS(css);   // Inject custom CSS into the shadow DOM
window.removeWebChatCSS();      // Remove custom CSS
window.setWebChatPosition(obj); // Change position/padding dynamically

EmbedChat Global Methods

window.unmountEmbedChat(elementId); // Unmount the EmbedChat instance for the given elementId
window.mountEmbedChat(elementId);   // Mount the EmbedChat instance again (with the last used config)

• window.unmountEmbedChat(elementId): Unmounts the EmbedChat instance from the specified element. The last configuration is saved.
• window.mountEmbedChat(elementId): Remounts the EmbedChat instance in the specified element using the last configuration used for that element. If no config was previously used, a warning is shown in the console.

Example

window.unmountEmbedChat('embed-small'); // Unmounts the chat from the element with id 'embed-small'
window.mountEmbedChat('embed-small');   // Remounts the chat in the same element with the last config

Listen to lifecycle & message events (🆕)

We emit custom browser events so you can capture interactions and feed them into Google Tag Manager, Google Analytics, Meta Pixel, or any other analytics tool.

| Widget | Event name | Fired when | detail payload | |--------|------------|------------|------------------| | WebChat | notchatbot-webchat-open | The floating chat is opened | { conversationId } | | WebChat | notchatbot-webchat-closed | The floating chat is closed | { conversationId } | | WebChat | notchatbot-webchat-message-sent | The user sends one or more messages | { messages: Message[] } | | WebChat | notchatbot-webchat-message-received | A message is received from the server | { message: Message, role: 'assistant' \| 'employee' } | | EmbedChat | notchatbot-embedchat-message-sent | The user sends a message | { message: Message } | | EmbedChat | notchatbot-embedchat-message-received | A message is received | { message: Message, role: 'assistant' \| 'employee' } |

Message follows the same interface used internally by the widget (id, text, sender, timestamp, etc.).

Quick example

window.addEventListener('notchatbot-webchat-open',  e => console.log('WebChat opened', e.detail));
window.addEventListener('notchatbot-webchat-closed',  e => console.log('WebChat closed', e.detail));
window.addEventListener('notchatbot-webchat-message-sent', e => console.log('Sent', e.detail.messages));
window.addEventListener('notchatbot-webchat-message-received', e => {
  const { role, message } = e.detail;
  console.log('Received', role, message);
});

Google Tag Manager / Google Analytics (GA4)

Push data directly to the dataLayer and create a trigger in GTM:

window.addEventListener('notchatbot-webchat-message-sent', e => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'webchat_message_sent',
    messages: e.detail.messages,
    conversationId: e.detail.messages[0]?.conversationId || null
  });
});

Then in GTM, add a Custom Event trigger called webchat_message_sent and link it to a GA4 event tag.

Meta / Facebook Pixel

window.addEventListener('notchatbot-webchat-open', () => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatOpened');
  }
});

window.addEventListener('notchatbot-webchat-message-received', e => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatMessageReceived', {
      role: e.detail.role
    });
  }
});

These events make it easy to measure engagement and conversions driven by the chat widget without modifying its source code.

Change position and padding dynamically (WebChat)

1. Change position and margin globally (flat)

window.setWebChatPosition({
  position: 'bottom-left',
  marginBottom: 40,
  marginSide: 30
});

2. Change only for mobile

window.setWebChatPosition({
  mobile: {
    position: 'bottom-right',
    marginBottom: 100,
    marginSide: 20
  }
});

3. Change only for desktop

window.setWebChatPosition({
  desktop: {
    position: 'bottom-left',
    marginBottom: 60,
    marginSide: 40
  }
});

4. Change using device format

window.setWebChatPosition({
  device: 'mobile',
  marginBottom: 120,
  marginSide: 15
});

Use custom events (addCustomPadding and open/close control)

You can dispatch events to change padding/margin or open/close the chat from anywhere in your app:

1. Open, close, or toggle the floating WebChat

window.dispatchEvent(new CustomEvent('openWebChatbot'));
window.dispatchEvent(new CustomEvent('closeWebChatbot'));
window.dispatchEvent(new CustomEvent('toggleWebChatbot'));

2. Change padding for both devices (flat)

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));

3. Change only for mobile

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));

4. Change only for desktop

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));

5. Change using nested object

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
  mobile: { marginBottom: 90, marginSide: 10 },
  desktop: { marginBottom: 50, marginSide: 30 }
}}));

Accepted object formats

• Flat: { marginBottom, marginSide, position } (applies to both if no override in mobile/desktop)
• By device: { device: 'mobile'|'desktop', marginBottom, marginSide }
• Nested: { mobile: { ... }, desktop: { ... } }
• Alias: { y, x } (y → marginBottom, x → marginSide)

You can combine these formats as needed.

Inject and remove custom CSS in WebChat

You can inject hot CSS into the floating WebChat using the global API:

// Change the header background color
window.injectWebChatCSS(`
  #notchatbot-webchat-header {
    background: #111 !important;
    color: #fff !important;
  }
`);

// Hide the floating button
window.injectWebChatCSS(`#notchatbot-webchat-button { display: none !important; }`);

// Change the chat window width
window.injectWebChatCSS(`#notchatbot-webchat-window { width: 500px !important; }`);

// Change the floating button color
window.injectWebChatCSS(`#notchatbot-webchat-button { background: #f59e0b !important; }`);

// Remove all custom styles
window.removeWebChatCSS();

Internal element IDs for WebChat

You can use these IDs to select and style specific parts of the widget:

• #notchatbot-webchat-button — Floating chat button
• #notchatbot-webchat-header — Chat window header
• #notchatbot-webchat-window — Main chat window

Example to change the header and button color:

window.injectWebChatCSS(`
  #notchatbot-webchat-header { background: #222 !important; color: #fff !important; }
  #notchatbot-webchat-button { background: #f59e0b !important; }
`);

You can combine these selectors to fully customize the widget.