Troubleshooting 6 steps

Troubleshooting: Widget Not Showing on Website

Converge Team

• Updated February 3, 2026

What to do when the Converge chat widget doesn't appear on your website.

Verify the embed code is installed

The widget won't show if the embed code isn't correctly installed on your website.

Check the embed code placement: The embed script should be in the <body> section of your HTML, ideally just before </body>.

View page source: Right-click your webpage and select "View Page Source" (or press Ctrl+U / Cmd+U). Search for "converge" or "widget" to verify the script is present.

What to look for:

<script async src="https://unpkg.com/@convergeapp/chat-widget/dist/widget.js" data-api-key="YOUR_API_KEY"></script>

Common installation issues:

Code not on all pages: The widget only appears on pages where the code is installed. Add it to your site-wide template or footer.
Code added to <head>: While this works, placing it before </body> is recommended for better page load performance.
Code modified: Don't modify the embed code. Even a small change can break it.
Multiple instances: Don't add the code multiple times — one instance per page is correct.

Check browser console for errors

Open your browser's developer tools to check for JavaScript errors preventing the widget from loading.

How to open dev tools:

Chrome/Edge: Press F12 or right-click → Inspect
Firefox: Press F12 or right-click → Inspect
Safari: Cmd+Option+I (enable Developer menu in Safari Preferences first)

Check the Console tab: Look for red error messages. Common errors include:

CSP violations: "Content Security Policy" errors indicate your site's security policy is blocking the widget
Network errors: "Failed to load resource" means the widget script couldn't be downloaded
JavaScript errors: Other scripts on your page might be conflicting

CSP (Content Security Policy) issues: If you see CSP errors, add this to your CSP header:

script-src: 'self' https://unpkg.com;
connect-src: 'self' https://useconverge.app;

Check cookie consent plugins

Cookie consent management plugins (like Cookiebot, CookieYes, or WPConsent) can block the widget from loading until users accept cookies.

The Converge widget is strictly necessary: The widget only uses essential cookies required for chat functionality (session authentication and visitor identification). It respects the browser's Do Not Track setting and doesn't track users who have DNT enabled. Under GDPR, these cookies are "strictly necessary" and don't require consent.

Try the Inline Loader method first: If the widget shows "Loading platforms..." forever with no network requests, use the Inline Loader embed method in Settings → Platforms → Widget. This bypasses consent plugin blocking entirely.

How to fix for common plugins (standard method):

Cookiebot: Add data-cookieconsent="ignore" to the script tag:

<script async src="..." data-api-key="..." data-cookieconsent="ignore"></script>

CookieYes: Add data-cookieyes="cookieyes-necessary":

<script async src="..." data-api-key="..." data-cookieyes="cookieyes-necessary"></script>

CookieScript: Add data-cookiescript="accepted" data-cookiecategory="strict"

WPConsent / Other: Add data-category="necessary"

WordPress cookie plugins: Some WordPress cookie plugins have settings to whitelist specific scripts. Add the widget URL (unpkg.com/@convergeapp/chat-widget) to your plugin's whitelist or "necessary scripts" list.

Easier method: In Converge, go to Settings → Platforms → Widget and select your cookie consent plugin from the dropdown. The generated script tag will include the correct attributes automatically.

Using Google Tag Manager (GTM)

If you're loading the widget through Google Tag Manager, the standard embed code won't work because GTM doesn't pass data attributes to scripts.

GTM installation requires two tags:

Tag 1 - Configuration (Custom HTML):

<script>
  window.__CONVERGE_CONFIG__ = {
    apiKey: "YOUR_API_KEY"
  };
</script>

Tag 2 - Widget Script (Custom HTML):

<script src="https://unpkg.com/@convergeapp/chat-widget/dist/widget.js"></script>

Critical: Tag firing order

Tag 1 must fire before Tag 2. In GTM, use Tag Sequencing:

Open Tag 2 settings
Click "Advanced Settings" → "Tag Sequencing"
Check "Fire a tag before..."
Select Tag 1 (the configuration tag)

Easier method: In Converge, go to Settings → Platforms → Widget and select "Google Tag Manager" as the embed method. Copy both tags and follow the sequencing instructions.

Disable ad blockers and extensions

Browser extensions, especially ad blockers, can prevent the widget from loading.

Common blockers:

Ad blockers: uBlock Origin, AdBlock Plus, Brave Shields
Privacy extensions: Privacy Badger, Ghostery
Script blockers: NoScript, ScriptSafe

Test in incognito/private mode: Open your website in an incognito window (Ctrl+Shift+N / Cmd+Shift+N). Incognito mode disables most extensions. If the widget appears in incognito but not normally, an extension is blocking it.

Whitelist Converge: To fix this without disabling extensions, whitelist Converge's domains:

unpkg.com (widget script)
useconverge.app (API connections)

Brave browser: Brave has built-in ad blocking. Click the shield icon in the address bar and disable it for your site to test.

Check widget visibility settings

The widget might be loaded but hidden due to Converge settings or CSS conflicts.

Widget settings in Converge: Go to Settings → Platforms → Widget and check that the widget is connected and active. If the widget platform is disconnected, reconnect it with your API key.

CSS conflicts: Your website's CSS might be hiding the widget. The widget uses the fixed position at bottom-right. Check for CSS like:

/* Conflicts to avoid */
#converge-widget { display: none; }
* { z-index: 9999; } /* Widget can't appear on top */

Test with the widget alone: Create a blank HTML page with only the widget code and no other CSS/JS. If it works there but not on your main site, your site's code is causing conflicts.

Force reload: Sometimes browser caching issues cause problems. Hard refresh (Ctrl+Shift+R / Cmd+Shift+R) to bypass cache.

Success indicator: When you open your website and see the chat bubble in the corner — and clicking it opens a functional widget — the issue is resolved.

Platforms