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.