Skip to main content
Solutions for common web widget issues.

​
Widget Not Appearing

Check these:
  • Embed code placed before closing </body> tag
  • Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
  • Test in incognito window
  • Verify plan includes web widget access
  • Check browser console (F12) for JavaScript errors
  • Re-copy embed code from widget configuration

​
Voice Not Working

HTTPS Required: Voice functionality requires HTTPS. HTTP sites can only use chat mode. Check these:
  • Website uses HTTPS (SSL certificate)
  • Browser has microphone permission
  • Microphone works in other applications
  • Using modern browser (Chrome, Firefox, Safari, Edge)
  • No VPN or firewall blocking WebRTC

​
Chat Not Working

Check these:
  • Browser console (F12) for errors
  • Assistant is properly configured
  • Test assistant with Test Chat
  • Review conversation in Conversations page
  • Reload page to reset widget state

​
Chat history resets on refresh

Chat history should persist across page reloads in the same browser. If it does not:
  • Confirm the widget is in Chat or Voice & Chat mode (voice-only sessions do not persist)
  • Check that the browser allows localStorage for the widget origin
  • If you pass data-customer-identifier / data-variables, a page refresh should still reopen the same chat — identity injection does not start a new conversation by itself
  • To start a fresh chat on purpose, use the widget refresh button or call window.AIChatWidget.reset('your-assistant-id')

​
Pre-Chat Form Issues

Check these:
  • Form fields configured in widget settings
  • Form fields have both name and label
  • The assistant was saved after you changed the form fields
  • Field names match assistant variables exactly
  • Clear browser cache and test in incognito
  • If you inject data-variables, the form is skipped only when every required field already has a value. Missing required keys still show the form, pre-filled with the values you passed
  • After logout, call window.AIChatWidget.reset('your-assistant-id') and stop injecting identity attributes, otherwise the previous visitor’s form data stays in the browser

​
Display & Styling Issues

Check these:
  • Widget position setting in configuration
  • Website CSS might override widget styles
  • Change primary color for better visibility
  • Check if page elements cover the widget (z-index)
  • Test on actual mobile devices

​
Configuration Not Updating

Check these:
  • Save the assistant: in the full builder the widget saves with Save assistant at the bottom, in the guided overview the Web Widget Configuration panel has its own save
  • Copy fresh embed code after saving
  • Replace old embed code on your website
  • Clear browser cache (Ctrl+Shift+R)
  • Test in incognito window

​
WordPress/CMS Issues

Check these:
  • Use Custom HTML block/widget (not visual editor)
  • Add embed code before closing </body> tag
  • Clear caching plugin cache
  • Temporarily disable security plugins if needed

​
Still Having Issues?

  1. Check browser console (F12) for errors
  2. Test in incognito mode
  3. Try different browser
  4. Test assistant with Test Chat
  5. Contact support with browser console screenshot