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:
-
Check script loading:
// Open browser console and check for errors console.log(typeof KoiWidget); // Should not be 'undefined'
-
Verify script URL:
<!-- Make sure the URL is correct --> <script src="https://widget.koi.im/v1.js"></script>
-
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
-
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:
-
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
-
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
-
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:
-
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
-
Configuration timing:
1// Set config BEFORE loading the script 2window.KoiWidgetConfig = { primaryColor: '#ff6b6b' }; 3// Then load the script 4
-
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:
-
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
-
CSS conflicts:
1/* Check for conflicting CSS */ 2.koi-widget-container { 3 position: fixed !important; 4 z-index: 9999 !important; 5} 6
-
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:
-
Increase z-index:
1window.KoiWidgetConfig = { 2 zIndex: 99999 // Higher than other elements 3}; 4
-
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:
-
Use proper CSS specificity:
1customCSS: ` 2 .koi-widget-button { 3 background: red !important; /* Use !important */ 4 } 5` 6
-
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
-
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:
-
Check if feature is enabled:
1window.KoiWidgetConfig = { 2 enableFileUpload: true // Must be explicitly enabled 3}; 4
-
File size limits:
1window.KoiWidgetConfig = { 2 maxFileSize: 10485760, // 10MB in bytes 3 allowedFileTypes: ['image/*', 'application/pdf'] 4}; 5
-
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:
-
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
-
Network connectivity:
1// Test API connectivity 2KoiWidget.on('error', (error) => { 3 console.error('Widget error:', error); 4}); 5
-
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:
-
Viewport configuration:
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
-
Touch events:
// Widget automatically handles touch events // Ensure no other scripts interfere with touch
-
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:
- 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:
-
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
-
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
-
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:
-
Limit message history:
1window.KoiWidgetConfig = { 2 maxMessages: 50 // Limit stored messages 3}; 4
-
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:
-
Check browser support:
1if (KoiWidget.isSupported()) { 2 // Widget is supported 3} else { 4 // Show fallback contact form 5 showFallbackForm(); 6} 7
-
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:
- 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:
-
Check API key:
1window.KoiWidgetConfig = { 2 apiKey: 'your-correct-api-key' // Verify this is correct 3}; 4
-
Domain whitelist:
// Ensure your domain is whitelisted // Contact support to add your domain
Rate Limiting
Problem: Getting 429 (Too Many Requests) errors.
Solutions:
- 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:
- Check browser console for error messages
- Try in incognito/private mode to rule out extensions
- Test on different browsers to isolate browser-specific issues
- Disable ad blockers temporarily
- 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.