Troubleshooting

Common issues and solutions for the Koi Widget. If you can't find your issue here, please contact our support team.

Installation Issues

Widget Not Appearing

Problem: The widget doesn't show up on your website.

Solutions:

  1. Check script loading:

    // Open browser console and check for errors
    console.log(typeof KoiWidget); // Should not be 'undefined'
    
  2. Verify script URL:

    <!-- Make sure the URL is correct -->
    <script src="https://widget.koi.im/v1.js"></script>
    
  3. Check for JavaScript errors:

    • Open browser Developer Tools (F12)
    • Look for red errors in the Console tab
    • Fix any JavaScript errors that might prevent the widget from loading
  4. Content Security Policy (CSP) issues:

    1<!-- Add these CSP directives -->
    2<meta http-equiv="Content-Security-Policy" content="
    3  script-src 'self' https://widget.koi.im;
    4  connect-src 'self' https://api.koi.im;
    5  style-src 'self' 'unsafe-inline' https://widget.koi.im;
    6">
    7

Widget Loads But Doesn't Function

Problem: Widget appears but clicking doesn't work or features are missing.

Solutions:

  1. Check configuration syntax:

    1// Ensure proper JSON syntax
    2window.KoiWidgetConfig = {
    3    primaryColor: '#2563eb', // Note the quotes and comma
    4    position: 'bottom-right'  // No comma on last item
    5};
    6
  2. Verify API connectivity:

    1// Check if API is reachable
    2fetch('https://api.koi.im/health')
    3  .then(response => console.log('API Status:', response.status))
    4  .catch(error => console.error('API Error:', error));
    5
  3. Clear browser cache:

    • Hard refresh: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
    • Or clear browser cache completely

Configuration Issues

Colors Not Applying

Problem: Custom colors in configuration are not showing up.

Solutions:

  1. Check color format:

    1// Correct formats
    2primaryColor: '#ff6b6b'     // Hex with #
    3primaryColor: 'rgb(255, 107, 107)'  // RGB format
    4primaryColor: 'hsl(0, 100%, 71%)'   // HSL format
    5
    6// Incorrect formats
    7primaryColor: 'ff6b6b'      // Missing #
    8primaryColor: 'red'         // Named colors not supported
    9
  2. Configuration timing:

    1// Set config BEFORE loading the script
    2window.KoiWidgetConfig = { primaryColor: '#ff6b6b' };
    3// Then load the script
    4
  3. CSS specificity issues:

    1// Use !important in custom CSS if needed
    2customCSS: `
    3  .koi-widget-button {
    4    background-color: #ff6b6b !important;
    5  }
    6`
    7

Position Not Working

Problem: Widget appears in wrong position despite configuration.

Solutions:

  1. Check valid position values:

    1// Valid positions only
    2position: 'bottom-right'  // ✓
    3position: 'bottom-left'   // ✓
    4position: 'top-right'     // ✓
    5position: 'top-left'      // ✓
    6
    7position: 'center'        // ✗ Invalid
    8
  2. CSS conflicts:

    1/* Check for conflicting CSS */
    2.koi-widget-container {
    3  position: fixed !important;
    4  z-index: 9999 !important;
    5}
    6
  3. Viewport issues:

    <!-- Ensure proper viewport meta tag -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    

Styling Issues

Widget Appears Behind Other Elements

Problem: Widget is hidden behind other page elements.

Solutions:

  1. Increase z-index:

    1window.KoiWidgetConfig = {
    2  zIndex: 99999  // Higher than other elements
    3};
    4
  2. Check parent element z-index:

    1/* Ensure parent elements don't have higher z-index */
    2.parent-element {
    3  z-index: 1000; /* Lower than widget */
    4}
    5

Custom CSS Not Working

Problem: Custom styles are not being applied.

Solutions:

  1. Use proper CSS specificity:

    1customCSS: `
    2  .koi-widget-button {
    3    background: red !important;  /* Use !important */
    4  }
    5`
    6
  2. Check CSS syntax:

    1// Correct
    2customCSS: `
    3  .koi-widget-button {
    4    background: red;
    5    border-radius: 50%;
    6  }
    7`
    8
    9// Incorrect - missing semicolons
    10customCSS: `
    11  .koi-widget-button {
    12    background: red
    13    border-radius: 50%
    14  }
    15`
    16
  3. Timing issues:

    1// Apply custom CSS after widget loads
    2KoiWidget.on('ready', () => {
    3  KoiWidget.configure({
    4    customCSS: 'your-css-here'
    5  });
    6});
    7

Functionality Issues

File Upload Not Working

Problem: File upload feature is not functioning.

Solutions:

  1. Check if feature is enabled:

    1window.KoiWidgetConfig = {
    2  enableFileUpload: true  // Must be explicitly enabled
    3};
    4
  2. File size limits:

    1window.KoiWidgetConfig = {
    2  maxFileSize: 10485760,  // 10MB in bytes
    3  allowedFileTypes: ['image/*', 'application/pdf']
    4};
    5
  3. Browser compatibility:

    1// Check if File API is supported
    2if (window.File && window.FileReader && window.FileList && window.Blob) {
    3  console.log('File API supported');
    4} else {
    5  console.log('File API not supported');
    6}
    7

Messages Not Sending

Problem: User messages are not being sent or processed.

Solutions:

  1. Check API configuration:

    1window.KoiWidgetConfig = {
    2  apiBaseUrl: 'https://api.koi.im',  // Correct API URL
    3  apiKey: 'your-valid-api-key'       // Valid API key
    4};
    5
  2. Network connectivity:

    1// Test API connectivity
    2KoiWidget.on('error', (error) => {
    3  console.error('Widget error:', error);
    4});
    5
  3. CORS issues:

    // Ensure your domain is whitelisted for API access
    // Contact support if you get CORS errors
    

Mobile Issues

Widget Not Responsive on Mobile

Problem: Widget doesn't work properly on mobile devices.

Solutions:

  1. Viewport configuration:

    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
    
  2. Touch events:

    // Widget automatically handles touch events
    // Ensure no other scripts interfere with touch
    
  3. Mobile-specific styling:

    1customCSS: `
    2  @media (max-width: 768px) {
    3    .koi-widget-container {
    4      width: 100% !important;
    5      height: 100% !important;
    6    }
    7  }
    8`
    9

Keyboard Issues on Mobile

Problem: Virtual keyboard interferes with widget.

Solutions:

  1. Viewport height adjustment:
    1// Widget automatically adjusts for virtual keyboard
    2// If issues persist, try:
    3customCSS: `
    4  .koi-widget-container {
    5    height: 100vh !important;
    6    height: 100dvh !important; /* Dynamic viewport height */
    7  }
    8`
    9

Performance Issues

Slow Loading

Problem: Widget takes too long to load.

Solutions:

  1. Lazy loading:

    1// Load widget only when needed
    2function loadWidget() {
    3  const script = document.createElement('script');
    4  script.src = 'https://widget.koi.im/v1.js';
    5  script.async = true;
    6  document.head.appendChild(script);
    7}
    8
    9// Load on user interaction
    10document.addEventListener('scroll', loadWidget, { once: true });
    11
  2. Preload resources:

    1<!-- Preload widget resources -->
    2<link rel="preload" href="https://widget.koi.im/v1.js" as="script">
    3<link rel="preload" href="https://widget.koi.im/v1.css" as="style">
    4
  3. CDN optimization:

    1// Use closest CDN endpoint
    2window.KoiWidgetConfig = {
    3  cdnRegion: 'auto'  // Automatically select closest region
    4};
    5

High Memory Usage

Problem: Widget consumes too much memory.

Solutions:

  1. Limit message history:

    1window.KoiWidgetConfig = {
    2  maxMessages: 50  // Limit stored messages
    3};
    4
  2. Disable unnecessary features:

    1window.KoiWidgetConfig = {
    2  enableEmojis: false,      // Disable if not needed
    3  enableFileUpload: false,  // Disable if not needed
    4  enableSounds: false       // Disable sounds
    5};
    6

Browser Compatibility

Internet Explorer Issues

Problem: Widget doesn't work in older browsers.

Solutions:

  1. Check browser support:

    1if (KoiWidget.isSupported()) {
    2  // Widget is supported
    3} else {
    4  // Show fallback contact form
    5  showFallbackForm();
    6}
    7
  2. Polyfills for older browsers:

    <!-- Add polyfills for IE11 -->
    <script src="https://polyfill.io/v3/polyfill.min.js?features=es6,fetch"></script>
    

Safari Issues

Problem: Widget behaves differently in Safari.

Solutions:

  1. Safari-specific CSS:
    1customCSS: `
    2  /* Safari-specific fixes */
    3  @supports (-webkit-appearance: none) {
    4    .koi-widget-container {
    5      -webkit-transform: translateZ(0);
    6    }
    7  }
    8`
    9

API Issues

Authentication Errors

Problem: Getting 401 or 403 errors.

Solutions:

  1. Check API key:

    1window.KoiWidgetConfig = {
    2  apiKey: 'your-correct-api-key'  // Verify this is correct
    3};
    4
  2. Domain whitelist:

    // Ensure your domain is whitelisted
    // Contact support to add your domain
    

Rate Limiting

Problem: Getting 429 (Too Many Requests) errors.

Solutions:

  1. Implement rate limiting:
    1// Limit message frequency
    2let lastMessageTime = 0;
    3const MESSAGE_COOLDOWN = 1000; // 1 second
    4
    5KoiWidget.on('beforeSend', (message) => {
    6  const now = Date.now();
    7  if (now - lastMessageTime < MESSAGE_COOLDOWN) {
    8    return false; // Cancel message
    9  }
    10  lastMessageTime = now;
    11  return true;
    12});
    13

Debugging Tools

Enable Debug Mode

1window.KoiWidgetConfig = {
2  debug: true  // Enable debug logging
3};
4
5// Or enable after loading
6KoiWidget.setDebugMode(true);
7

Console Commands

1// Useful debugging commands
2KoiWidget.getConfig()        // View current configuration
3KoiWidget.getMessages()      // View all messages
4KoiWidget.getUser()          // View user data
5KoiWidget.getSessionId()     // View session ID
6KoiWidget.isOpen()           // Check if widget is open
7

Event Monitoring

1// Monitor all widget events
2['ready', 'open', 'close', 'message', 'error'].forEach(event => {
3  KoiWidget.on(event, (data) => {
4    console.log(`[Koi Widget] ${event}:`, data);
5  });
6});
7

Getting Help

If you're still experiencing issues:

  1. Check browser console for error messages
  2. Try in incognito/private mode to rule out extensions
  3. Test on different browsers to isolate browser-specific issues
  4. Disable ad blockers temporarily
  5. Contact support with:
    • Browser and version
    • Operating system
    • Console error messages
    • Steps to reproduce the issue
    • Your configuration code

Still need help? Contact our support team with your specific issue and we'll help you resolve it quickly.