Widget Issues

This page covers the most common widget problems. For the full installation guide, see the Installing the Widget collection.

The widget doesn’t appear on my site

1. Check the snippet - open your browser’s developer console on the page where the widget should appear. Look for any JavaScript errors mentioning convot or widget-loader.
2. Check the app_id - make sure the window.Convot.app_id in your snippet matches the key shown in Settings → Apps → [app] → Setup. It starts with app_.
3. Check load order - the Convot snippet should be placed just before the closing </body> tag. If you’re loading it conditionally (behind a feature flag or only for logged-in users), confirm that condition is met.
4. Check Content Security Policy (CSP) - if your site has a CSP header, it may be blocking app.convot.com from loading. Add app.convot.com to your script-src and connect-src directives.
5. Check ad blockers - browser extensions (ad blockers, privacy shields) sometimes block chat widgets. Test in an incognito window with extensions disabled.

Messages from the widget aren’t arriving in my inbox

1. Open a conversation in Chat and check whether the message is there but assigned to no one. The conversation might be there but not assigned to you.
2. Check that the app the widget uses is the same app you’re looking at in the inbox. Each app has its own inbox.
3. Open your browser console on the page with the widget and check for failed network requests to app.convot.com.

Visitors are showing as anonymous after calling Convot.identify()

See the Identity verification troubleshooting section for the full checklist. Common causes:

• The user_hash is computed from the wrong value (must be external_id if you pass one, otherwise email).
• The identity secret in your server code is stale (it was rotated in Convot but not updated on the server).
• Convot.identify() is being called before the widget script has loaded. Call it after the widget’s onLoaded event.

The widget appears but the bot doesn’t reply

See My bot isn’t answering.

The widget shows on desktop but not on mobile

Some mobile browsers restrict third-party scripts. Check:

• The snippet is present in the HTML sent to mobile visitors (not stripped by a mobile-specific template).
• No mobile-specific CSP rules are blocking the widget.

Real-time messages are delayed

The widget uses a WebSocket connection for real-time messaging. If WebSocket connections are blocked by a firewall or proxy:

• Messages will fall back to HTTP polling, which introduces a small delay.
• Check whether your infrastructure (CDN, proxy, load balancer) supports WebSocket upgrades.

Still stuck?

Contact [email protected] with:

• Your app key (starts with app_).
• The URL where the widget should appear.
• A description of what you see (or don’t see) in the browser console.