Troubleshooting

Troubleshooting

Having issues with your widget? This guide covers common problems and their solutions.

Widget Not Appearing

If the widget doesn’t appear on your website, check the following:

1. Verify Widget Key

  • Ensure your widget key is correct (found in your project dashboard)
  • Check for typos or extra spaces in the data-widget-key attribute
  • Verify the widget key matches the active project

2. Check Domain Configuration

  • Verify your domain is added to the allowed domains list in your dashboard
  • For development, localhost domains are allowed by default
  • Ensure you’re using the exact domain (including www if applicable)

[Image: Dashboard showing domain configuration settings]

3. Browser Console Errors

Open your browser’s developer console (F12) and check for JavaScript errors. Common errors include:

  • Widget key not found: Verify the data-widget-key attribute is present
  • CORS errors: Check that your domain is allowed in the dashboard
  • Network errors: Verify the API URL is correct and accessible

Widget Not Responding

If the widget appears but doesn’t respond to clicks or messages:

  • Check Subscription Status: Ensure your subscription is active (free trial or paid plan)
  • Verify API URL: Confirm the data-api-url attribute is correct
  • Check Network Tab: Look for failed API requests in the browser’s Network tab
  • Test API Access: Ensure the API endpoint is accessible from your domain

No Answers or Incorrect Answers

If the widget isn’t providing helpful answers:

  • Check Document Uploads: Ensure you’ve uploaded relevant documents to your project
  • Verify Document Processing: Wait a few minutes after uploading for documents to be processed
  • Review Question Format: Try rephrasing questions in different ways
  • Check Document Content: Ensure your documents contain relevant information

[Image: Dashboard showing uploaded documents and processing status]

Styling Issues

If the widget doesn’t match your customizations:

  • Clear Browser Cache: Hard refresh (Ctrl+F5 or Cmd+Shift+R) to load updated styles
  • Verify Settings: Check that your customization settings are saved in the dashboard
  • Check for CSS Conflicts: Your site’s CSS might be overriding widget styles

Performance Issues

If the widget is affecting your site’s performance:

  • Check Loading Time: The widget should load asynchronously and not block rendering
  • Review Network Requests: Ensure API calls are not causing delays
  • Verify Script Placement: Widget script should be in the footer, not the header

Mobile-Specific Issues

  • Test the widget on actual mobile devices, not just desktop browser responsive mode
  • Check touch interactions – ensure the widget button is large enough for mobile taps
  • Verify the chat interface displays correctly on small screens

Getting Additional Help

If you’ve tried the solutions above and are still experiencing issues:

  • Check Documentation: Review other documentation sections for detailed information
  • Contact Support: Reach out through our contact form with details about your issue
  • Include Details: When contacting support, include:
    • Your widget key (first 8 characters)
    • Your domain
    • Browser and version
    • Console error messages (if any)
    • Steps to reproduce the issue

Common Error Messages

  • “Widget key is required”: Add the data-widget-key attribute to your script tag
  • “Invalid widget key”: Check that your widget key is correct
  • “Domain not allowed”: Add your domain to the allowed domains list in your dashboard
  • “Subscription expired”: Renew your subscription or start a free trial