5 min read

Chat Widget

Install and customize the CommFlow chat widget on your website for real-time customer support.

Chat Widget#

The CommFlow chat widget lets you provide real-time support directly on your website. Visitors can start conversations without leaving your site.

Installation#

Basic Installation#

Add this code snippet before the closing </body> tag on your website:

<script>
  (function(w, d, s, o, f, js, fjs) {
    w['CommFlow'] = o;
    w[o] = w[o] || function() { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s); fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1;
    fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script', 'cf', 'https://widget.commflow.io/widget.js'));
 
  cf('init', {
    workspaceId: 'YOUR_WORKSPACE_ID'
  });
</script>

Replace YOUR_WORKSPACE_ID with your actual workspace ID found in Settings > Live Support > Widget.

Finding Your Workspace ID#

  1. Go to Settings in CommFlow
  2. Select Live Support
  3. Click Widget Configuration
  4. Copy your Workspace ID

Configuration Options#

Basic Configuration#

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  primaryColor: '#10b981',           // Widget accent color
  position: 'bottom-right',          // Widget position
  greeting: 'Hi! How can we help?',  // Welcome message
  placeholder: 'Type a message...'   // Input placeholder
});

Full Configuration Reference#

OptionTypeDefaultDescription
workspaceIdstringrequiredYour workspace identifier
primaryColorstring#10b981Widget theme color (hex)
positionstringbottom-rightbottom-right or bottom-left
greetingstringHi there!Initial greeting message
placeholderstringType a message...Input field placeholder
launcherIconstringchatchat, message, or custom URL
hideWhenOfflinebooleanfalseHide widget when no agents online
requireEmailbooleanfalseRequire email before chatting
languagestringenWidget language code

Advanced Configuration#

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  primaryColor: '#10b981',
  position: 'bottom-right',
  greeting: 'Welcome! How can we assist you today?',
 
  // Require visitor info before chat
  requireEmail: true,
  requireName: true,
 
  // Custom launcher
  launcherIcon: 'https://yoursite.com/chat-icon.svg',
  launcherText: 'Chat with us',
 
  // Behavior
  autoOpen: false,           // Auto-open widget on page load
  autoOpenDelay: 5000,       // Delay before auto-open (ms)
  hideWhenOffline: false,    // Show offline message instead
  soundEnabled: true,        // Play sound on new messages
 
  // Branding
  showBranding: true,        // Show "Powered by CommFlow"
 
  // Pre-chat form
  preChatForm: {
    enabled: true,
    fields: [
      { name: 'name', label: 'Your Name', required: true },
      { name: 'email', label: 'Email', type: 'email', required: true },
      { name: 'topic', label: 'Topic', type: 'select', options: ['Sales', 'Support', 'Other'] }
    ]
  }
});

Customization#

Colors & Styling#

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  primaryColor: '#10b981',     // Main accent color
  textColor: '#1f2937',        // Text color
  backgroundColor: '#ffffff',   // Widget background
  headerColor: '#10b981',      // Header background
  headerTextColor: '#ffffff'   // Header text color
});

Position & Size#

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  position: 'bottom-right',    // or 'bottom-left'
  offsetX: 20,                 // Horizontal offset (px)
  offsetY: 20,                 // Vertical offset (px)
  width: 380,                  // Widget width (px)
  height: 600                  // Widget max height (px)
});

Custom Launcher Button#

Replace the default chat bubble with a custom element:

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  customLauncher: true  // Hide default launcher
});
 
// Trigger widget open from your own button
document.getElementById('my-chat-button').onclick = function() {
  cf('open');
};

JavaScript API#

Control the widget programmatically:

Opening & Closing#

// Open the widget
cf('open');
 
// Close the widget
cf('close');
 
// Toggle open/close
cf('toggle');

Pre-filling Visitor Data#

// Set visitor information
cf('setVisitor', {
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890',
  customFields: {
    plan: 'Enterprise',
    accountId: '12345'
  }
});

Sending Events#

// Track custom events
cf('track', 'page_viewed', {
  page: '/pricing',
  referrer: document.referrer
});
 
// Track conversions
cf('track', 'purchase_completed', {
  amount: 99.99,
  product: 'Pro Plan'
});

Event Listeners#

// Listen to widget events
cf('on', 'open', function() {
  console.log('Widget opened');
});
 
cf('on', 'close', function() {
  console.log('Widget closed');
});
 
cf('on', 'message:sent', function(message) {
  console.log('Visitor sent:', message);
});
 
cf('on', 'message:received', function(message) {
  console.log('Agent replied:', message);
});

Destroying the Widget#

// Remove widget completely
cf('destroy');

Mobile Responsiveness#

The widget automatically adapts to mobile screens:

  • Full-screen mode on small devices
  • Touch-optimized interface
  • Native keyboard handling
  • Responsive message bubbles

Mobile-Specific Options#

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  mobile: {
    fullScreen: true,          // Full screen on mobile
    hideOnScroll: false,       // Keep visible when scrolling
    bottomOffset: 60           // Space for mobile nav bars
  }
});

Offline Behavior#

Configure what happens when no agents are online:

cf('init', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  offline: {
    enabled: true,
    message: 'We\'re currently offline. Leave a message and we\'ll get back to you!',
    showForm: true,            // Show contact form
    collectEmail: true,
    collectMessage: true
  }
});

Single-Page App Support#

For React, Vue, Angular, or other SPAs:

// Re-initialize on route change
cf('update', {
  page: window.location.pathname
});
 
// Or use framework-specific integration
// React example:
useEffect(() => {
  cf('update', { page: location.pathname });
}, [location]);

Security#

Domain Restriction#

Limit which domains can use your widget:

  1. Go to Settings > Live Support > Widget
  2. Under Allowed Domains, add your domains
  3. Only listed domains will load the widget

Content Security Policy#

If you use CSP headers, add these directives:

script-src 'self' https://widget.commflow.io;
frame-src 'self' https://widget.commflow.io;
connect-src 'self' https://api.commflow.io wss://realtime.commflow.io;

Troubleshooting#

Widget Not Appearing#

  1. Check workspace ID - Verify it's correct
  2. Check domain allowlist - Is your domain allowed?
  3. Check console errors - Look for JavaScript errors
  4. Check ad blockers - May block chat widgets

Messages Not Sending#

  1. Check internet connection
  2. Verify API connectivity - Test https://api.commflow.io
  3. Check browser console - Look for WebSocket errors

Styling Conflicts#

If the widget looks broken:

  1. Check for CSS conflicts with !important rules
  2. The widget uses Shadow DOM to prevent most conflicts
  3. Contact support if issues persist

Next Steps#

Was this page helpful?

Let us know if you found what you were looking for.