Skip to main content

Troubleshooting Common Issues

Comprehensive guide to identifying and resolving common website integration problems with your AI assistant widget.

Before You Start Troubleshooting​

Essential Prerequisites Checklist​

⚠️ Verify these requirements before troubleshooting technical issues:

  1. ✅ Assistant Configuration:

    • Assistant is created and properly configured
    • Test assistant works in dashboard interface

  2. ✅ Role Assignment:

    • Assistant has roles assigned
    • Roles have appropriate permissions
    • Roles are connected to knowledge sources

  3. ✅ Website Channel Setup:

    • Website channel is created and active
    • Correct website URL is configured
    • Generated code is copied exactly as provided

Important: Most integration issues stem from incomplete assistant setup, not technical implementation problems.

Widget Not Appearing Issues​

Issue: Widget Doesn't Show on Website​

Symptoms:

  • No chat widget visible on your website
  • Page loads normally but assistant is missing
  • No errors visible to website visitors

Diagnostic Steps:

  1. Check Browser Console:

    • Press F12 to open developer tools
    • Look for JavaScript errors in Console tab
    • Note any error messages related to "wiil" or "widget"

  2. Verify Code Placement:

    • Ensure widget code is placed before closing body tag
    • Check that both div element and script tags are included
    • Confirm no missing quotation marks or brackets

  3. Validate Website URL:

    • Ensure URL in dashboard exactly matches your live site
    • Include or exclude "www" as it appears in browser
    • Verify protocol (http vs https) matches

Solutions:

<!-- Correct implementation -->
<div 
  id="your-unique-widget-id" 
  data-config-id="YOUR_CONFIG_ID" 
  data-primary-color="#ff6b35" 
  data-agent-name="Customer Support" 
  data-features="chat,voice" 
  data-prompt-message="Need help? We're here to assist!" 
></div>
<script src="https://cdn.wiil.io/public/wiil-widget.js"></script>
<script>WiilWidget.init();</script>

Common Fixes:

  • Move code to footer template for site-wide appearance
  • Clear browser cache and refresh page
  • Test in incognito/private browsing mode
  • Verify no ad blockers are interfering

Issue: Widget Appears But Looks Broken​

Symptoms:

  • Widget shows but appears distorted
  • Styling conflicts with website design
  • Widget overlaps with other elements

Solutions:

  1. CSS Conflicts:

    • Check for CSS rules affecting widget container
    • Ensure widget has sufficient z-index
    • Verify no conflicting position styles

  2. Theme Compatibility:

    • Test with default theme if using WordPress
    • Disable other plugins temporarily to identify conflicts
    • Check theme's CSS for widget interference

Assistant Not Responding Issues​

Issue: Widget Opens But Assistant Doesn't Respond​

Symptoms:

  • Chat interface opens successfully
  • Messages can be typed but no responses
  • Loading indicator may show indefinitely

Primary Cause Check:

  1. Assistant Configuration Status:

    Dashboard → My Assistants → [Your Assistant]
    Check: Roles are assigned
    Check: Knowledge sources are connected

  2. Test Assistant Separately:

    • Go to assistant dashboard
    • Use "Test Assistant" feature
    • Verify responses work in dashboard interface
    • If dashboard testing fails, assistant needs configuration

Solutions:

  1. Complete Assistant Setup:

    • Ensure assistant has at least one role assigned
    • Verify roles have knowledge sources attached
    • Test assistant functionality in dashboard first

  2. Role Configuration:

    • Check that assigned roles have appropriate permissions
    • Verify knowledge sources are processed and active
    • Confirm role settings match intended behavior

Issue: Partial Assistant Functionality​

Symptoms:

  • Some responses work, others don't
  • Inconsistent behavior across topics
  • Assistant seems to "forget" information

Diagnostic Approach:

  1. Knowledge Source Analysis:

    • Check which knowledge sources are assigned to role
    • Verify all sources show "Processed" status
    • Test specific topics that aren't working

  2. Role Scope Review:

    • Confirm role has access to relevant knowledge
    • Check if multiple roles might be conflicting
    • Verify role permissions are correctly set

Voice Features Not Working​

Issue: Voice Chat Unavailable or Not Functioning​

Symptoms:

  • Voice button doesn't appear
  • Microphone access denied
  • Voice recognition not working
  • Audio playback issues

Browser Requirements Check:

  1. HTTPS Requirement:

    • Voice features require HTTPS connection
    • Check website URL shows lock icon
    • HTTP sites cannot access microphone

  2. Browser Compatibility:

    • Chrome: Full support
    • Firefox: Full support
    • Safari: Limited support
    • Edge: Full support
    • Mobile browsers: Varies by device

Solutions:

  1. Enable Microphone Permissions:

    • Click microphone icon in browser address bar
    • Select "Allow" for microphone access
    • Refresh page after changing permissions

  2. Check Website Security:

    • Ensure website uses HTTPS
    • Verify SSL certificate is valid
    • Test on secure connection

  3. Browser Settings:

    • Clear browser cache and cookies
    • Check browser's site permissions
    • Test in different browser

Performance and Loading Issues​

Issue: Widget Loads Slowly or Causes Page Problems​

Symptoms:

  • Website takes longer to load with widget
  • Page becomes unresponsive
  • Widget doesn't initialize properly

Performance Optimization:

  1. Script Loading:

    • Ensure script is placed at bottom of page
    • Widget loads asynchronously by default
    • Check for conflicts with other scripts

  2. Network Connectivity:

    • Test with different internet connections
    • Check if CDN (cdn.wiil.io) is accessible
    • Verify no firewall blocking widget scripts

Solutions:

  1. Optimal Code Placement:

    - Place just before closing body tag
    <script src="https://cdn.wiil.io/public/wiil-widget.js"></script>
    <script>WiilWidget.init();</script>

  2. Conflict Resolution:

    • Test with other scripts temporarily disabled
    • Check JavaScript console for error messages
    • Ensure no duplicate widget implementations

Platform-Specific Issues​

WordPress Issues​

Common Problems:

  • Plugin conflicts preventing widget load
  • Theme overriding widget styles
  • Caching preventing widget updates

Solutions:

  • Deactivate plugins to identify conflicts
  • Use child theme for custom implementations
  • Clear caching plugins after widget installation

Shopify Issues​

Common Problems:

  • Theme updates removing custom code
  • Checkout process conflicts
  • Mobile theme differences

Solutions:

  • Backup theme before modifications
  • Use Shopify's Script Manager when available
  • Test widget on different theme sections

E-commerce Specific Issues​

Common Problems:

  • Cart/checkout page conflicts
  • SSL certificate issues on payment pages
  • Mobile responsiveness on product pages

Solutions:

  • Test widget on non-checkout pages first
  • Ensure HTTPS throughout entire site
  • Check mobile layout across different devices

Systematic Troubleshooting Process​

Step 1: Verify Prerequisites​

  1. Assistant is fully configured and tested
  2. Roles are assigned with knowledge sources
  3. Website channel is properly created

Step 2: Check Implementation​

  1. Code is copied exactly as generated
  2. Code placement is correct (before body tag)
  3. Website URL matches dashboard configuration

Step 3: Browser Diagnostics​

  1. Open browser developer tools (F12)
  2. Check Console tab for errors
  3. Test in different browsers and devices

Step 4: Test Functionality​

  1. Text chat features
  2. Voice features (if enabled)
  3. Assistant response quality

Step 5: Platform-Specific Checks​

  1. Follow platform-specific troubleshooting
  2. Check for theme/plugin conflicts
  3. Verify platform requirements

Getting Additional Help​

Before Contacting Support​

Gather This Information:

  • Website URL where widget is implemented
  • Browser and version where issue occurs
  • Specific error messages (if any)
  • Screenshots of the problem
  • Steps to reproduce the issue

Support Channels​

Technical Support:

  • Email: support@wiil.io
  • Include: Assistant ID, website URL, and issue description

Documentation:

  • Platform guides: Available in documentation section

Emergency Situations​

Critical Issues:

  • Widget causing website crashes
  • Security concerns
  • Urgent production problems

Contact: Priority support available for enterprise customers Response Time: Critical issues addressed within 4 hours

💡 Pro Tip: 90% of integration issues are resolved by completing assistant configuration first, then testing the assistant in the dashboard before implementing on the website. Always verify your assistant works independently before troubleshooting website integration.