Skip to main content

​
Overview

This guide helps you diagnose and resolve common issues with the Vaile chat widget. Follow these troubleshooting steps to get your widget working perfectly.

​
Widget Not Appearing

​
Initial Checks

1

Verify Installation

Check that the widget script is properly installed:
<!-- Should be before </body> tag -->
<script 
  src="https://embed.vaile.ai/chat-widget.iife.js"
  data-widget-key="YOUR_WIDGET_KEY"
  defer
></script>
2

Check Widget Key

Ensure your widget key is correct:
  • No quotes around the key
  • Correct format: wk_xxxxxxxxxxxxx
  • No extra spaces
3

Browser Console

Open Developer Tools (F12) and check for errors:
  • Red error messages
  • 404 (file not found)
  • Authentication errors
4

Network Tab

In DevTools Network tab, verify:
  • Widget script loads (200 status)
  • No blocked requests
  • HTTPS connection

​
Common Causes

Problem: Script in wrong locationSolution: Place script just before </body> tag, not in <head>
<!-- Wrong -->
<head>
  <script src="..."></script>
</head>

<!-- Correct -->
<body>
  <!-- content -->
  <script src="..."></script>
</body>
Problem: Other scripts causing conflictsSolutions:
  • Check console for JavaScript errors
  • Try on a test page with no other scripts
  • Ensure jQuery conflicts are resolved
  • Update conflicting libraries
Problem: Browser extensions blocking widgetSolutions:
  • Temporarily disable ad blockers
  • Whitelist your domain
  • Test in incognito mode
  • Check corporate firewall rules
Problem: Styles hiding the widgetSolutions:
  • Check for display: none on body
  • Look for high z-index elements
  • Inspect widget container element
  • Remove conflicting CSS

​
Widget Appears But Doesn’t Work

​
Functionality Issues

  • Can't Send Messages
  • No AI Responses
  • Widget Freezes
Symptoms:
  • Type message but can’t send
  • Send button doesn’t work
  • Messages disappear
Solutions:
  1. Check internet connection
  2. Verify widget key permissions
  3. Clear browser cache
  4. Check for console errors
  5. Test in different browser

​
Display Issues

​
Visual Problems

Wrong Position

Problem: Widget in wrong spotFix: Check for CSS conflicts
/* Override positioning */
.vaile-widget-container {
  position: fixed !important;
  bottom: 20px !important;
  right: 20px !important;
}

Cut Off Text

Problem: Messages truncatedFix: Viewport settings
<meta name="viewport" 
  content="width=device-width, 
  initial-scale=1">

​
Style Conflicts

Common CSS conflicts and fixes:

​
Performance Issues

​
Slow Loading

1

Check Network Speed

Use DevTools Network tab:
  • Widget load time
  • File size
  • Connection speed
2

Optimize Page

Reduce overall page weight:
  • Compress images
  • Minify scripts
  • Enable caching
  • Use CDN
3

Lazy Load Widget

Load widget after page:
window.addEventListener('load', () => {
  setTimeout(() => {
    // Load widget script
  }, 2000);
});

​
High Memory Usage

Signs and solutions:
Symptoms: Page slows over timeSolutions:
  • Update to latest widget version
  • Clear chat history periodically
  • Refresh page after long sessions
  • Check for console errors
Symptoms: Fan noise, lagSolutions:
  • Disable animations
  • Reduce polling frequency
  • Close unused tabs
  • Update graphics drivers

​
Mobile-Specific Issues

​
Common Mobile Problems

  • Not Responsive
  • Keyboard Issues
  • Can't Close
Issue: Widget doesn’t adapt to mobileFixes:
  • Add viewport meta tag
  • Check responsive breakpoints
  • Test orientation changes
  • Verify touch events work

​
Browser-Specific Issues

​
Compatibility Problems

​
Integration Issues

​
CMS-Specific Problems

Common Issues:
  • Plugin conflicts
  • Theme overrides
  • Cache problems
Solutions:
  • Use Code Snippets plugin
  • Clear all caches
  • Check theme footer.php
  • Disable plugins one by one
Common Issues:
  • Checkout page conflicts
  • Theme updates removing code
  • App conflicts
Solutions:
  • Use theme.liquid file
  • Create backup of changes
  • Test all page types
  • Check app compatibility
Common Issues:
  • Editor preview differs
  • Mobile view problems
  • Custom code limits
Solutions:
  • Publish to see changes
  • Use Wix dashboard
  • Check mobile editor
  • Upgrade plan if needed

​
Error Messages

​
Common Errors and Fixes

Always check the browser console (F12) for specific error messages
  • 401 Unauthorized
  • 404 Not Found
  • 500 Server Error
  • CORS Error
Meaning: Invalid widget keySolutions:
  • Verify key in dashboard
  • Check for typos
  • Regenerate if needed
  • Ensure account active

​
Debug Mode

​
Enable Detailed Logging

Add debug parameter to widget: 
<script 
  src="https://widget.vaile.ai/chat-widget.iife.js"
  data-widget-key="YOUR_WIDGET_KEY"
  data-debug="true"
  defer
></script>
This provides:
  • Detailed console logs
  • Network request info
  • Error stack traces
  • Performance metrics
Only use debug mode during troubleshooting, not in production

​
Getting Help

​
Before Contacting Support

​
Information to Provide

When contacting support, include:
  1. Widget key (first 8 characters)
  2. Website URL where issue occurs
  3. Browser and version
  4. Device type (desktop/mobile)
  5. Error messages (screenshots)
  6. Steps to reproduce
  7. What you’ve tried

​
Support Channels

Email Support

[email protected]
  • 24-48 hour response
  • Detailed assistance
  • File attachments

Dashboard Chat

Live chat in dashboard
  • Business hours
  • Quick questions
  • Real-time help

​
Preventive Measures

​
Best Practices

  • Test after site updates
  • Check different browsers
  • Monitor error logs
  • Verify mobile experience
  • Widget auto-updates
  • Check for announcements
  • Review changelog
  • Test new features
  • Check load times
  • Watch error rates
  • Track engagement
  • Review analytics

​
Quick Reference

​
Troubleshooting Checklist

​
Next Steps

Installation Guide

Review installation steps

Contact Support

Get personalized help