Troubleshooting
The widget doesn’t appear
- Check the snippet is on the page and before
</body>. View source and confirm the<script src=".../widget/zuhile-widget.js">is present. - Check the domain is allowlisted. The widget only runs on domains you’ve added under Settings → Widget. Add your exact domain (and any staging domains).
- Check
data-api. It must be your gateway’s base URL and reachable from the browser over HTTPS. - Look in the browser console for network errors loading the bundle or calling the gateway.
”Failed to load” or CORS errors
- Make sure
data-apipoints at the gateway, not the dashboard. - Confirm the gateway is reachable over HTTPS from the visitor’s browser.
- The widget’s API accepts any origin (it authenticates with your public key), so a CORS failure usually means the URL is wrong or the gateway is unreachable.
The key stopped working
If you regenerated your widget key in the dashboard, the old snippet stops working immediately. Copy the new snippet from Settings → Embed and replace the old one on your site.
Replies aren’t live / no realtime
The widget uses WebSockets for live agent replies and presence. If your infrastructure sits behind a proxy, ensure it forwards WebSocket upgrades to the gateway. (If you self-host with our Docker setup, the included Caddy edge does this automatically.)
Styles look wrong on my site
They shouldn’t clash — the widget renders in a shadow DOM, isolated from your
CSS. If something still looks off, check for global rules that force styles with
!important on * selectors, or aggressive z-index stacking on your page.
Still stuck?
Contact us at support@usezuhile.com with your domain and a screenshot of any console errors.