Platforms 5 steps

How to Install the Chat Widget on Your Website

Install the Converge chat widget on any site — script tag, Google Tag Manager, Shopify, Webflow, or WordPress via the WPCode plugin.

Converge Converge Team
•
1

Get your widget embed code

In Converge, go to SettingsPlatformsWidget. You'll see your unique embed code — a small JavaScript snippet that loads the Converge widget on your website.

What the embed code does: The script asynchronously loads the widget from Converge's CDN, initializes it with your workspace settings, and displays the chat bubble on your page. It's optimized for performance — it loads in the background and doesn't block your page rendering.

One code, all pages: The same embed code works on every page of your website. You don't need different codes for different pages. The widget automatically inherits the customization settings (colors, welcome message, etc.) from your Converge workspace.

Security note: The data-api-key attribute in your embed code is a public identifier for your workspace. It's not a secret — it's safe to include in public HTML. However, don't share your workspace credentials or other API keys.

2

Copy the embed snippet

Click the Copy Code button next to the embed code. This copies the entire script tag to your clipboard.

Your embed code looks like this:

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

Code breakdown:

  • src — URL to the widget JavaScript file hosted on the unpkg CDN
  • data-api-key — Your unique workspace API key (found in widget settings)
  • async — Loads the script in the background so it never blocks page rendering
  • type="module" — Optional. The Converge widget ships as an IIFE bundle, so it works fine without this attribute. Leave it in if you copied the snippet as-is, or remove it if your CMS plugin (e.g. WPCode) asks you to pick a script type and won't accept "module".

Keep the code accessible: Save this code somewhere secure in case you need to reinstall the widget later. You can always find it again in Converge's widget settings, but it's helpful to have it documented.

Using Google Tag Manager? GTM strips data attributes, so use the URL parameter method instead:

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

In Converge, select "Google Tag Manager (simple)" as the embed method to get this format with your API key pre-filled.

Using a cookie consent plugin? If your site uses Cookiebot, CookieYes, or another consent management tool, select it in the widget settings dropdown to get a script tag with the correct attributes. This ensures the widget loads immediately as an "essential" script without being blocked by consent plugins.

3

Add the widget to your website

Paste the embed code into your website's HTML. The recommended placement is just before the closing </body> tag, but it works anywhere in the <body> section.

Where to add it depends on your setup:

HTML/CSS/JS websites: Add the code to your main template file (e.g., index.html, _layout.html, or footer.html) so it loads on all pages.

WordPress: Install a plugin like "WPCode" or "Insert Headers and Footers", then paste the code in the footer section. Alternatively, add it to your theme's footer.php file (child theme recommended).

Shopify: Install the Converge Chat Widget from the Shopify App Store (search "Converge Chat") for one-click setup — no code editing needed. In the Theme Editor, go to App embeds, toggle on Converge Chat, and enter your API Key. Alternatively, go to Online StoreThemesEdit Code, open theme.liquid, and paste the embed code before </body>.

Webflow: Go to Project SettingsCustom Code. Paste the code in the "Footer Code" section.

Next.js/Nuxt/Gatsby: Add the script to your layout component or use the Script component with strategy="afterInteractive".

Single-page apps (React, Vue, Angular): Add the script to your main index.html or use a helmet/head component to inject it.

Important: Only add the widget code once per page. Adding it multiple times can cause conflicts.

4

How do I install the Converge widget in WordPress with the WPCode plugin (JavaScript Snippet)?

Use WPCode's "JavaScript Snippet" type, paste the Converge embed code as-is, set Auto InsertSite Wide Footer, and activate. You do not need to set type="module" — the Converge widget is an IIFE bundle, not an ES module, so leave the module checkbox unchecked or paste the full <script> tag and let WPCode treat it as plain HTML/JS.

WPCode (formerly "Insert Headers and Footers") is the most-used code-injection plugin on WordPress.org, active on over 2 million sites per the WordPress.org plugin directory. It's the cleanest way to install the Converge widget on WordPress without editing footer.php or a child theme.

Step-by-step in the WordPress admin:

  1. Install and activate the WPCode – Insert Headers and Footers plugin from PluginsAdd New.
  2. Go to Code Snippets+ Add Snippet, then choose Add Your Custom Code (New Snippet).
  3. Give the snippet a name like Converge Chat Widget.
  4. Under Code Type, pick the option that matches how you want to paste the code:
    • HTML Snippet — recommended. Paste the full <script async src="https://unpkg.com/@convergeapp/chat-widget/dist/widget.js" data-api-key="YOUR_API_KEY"></script> tag exactly as Converge shows it. WPCode injects it verbatim.
    • JavaScript Snippet — works too, but WPCode will wrap your code in its own <script> tag. In that case paste only the loader logic (e.g. the dynamic-loader variant from Converge's "Manual" embed option), not the full <script>...</script> tag.
  5. Under Insertion, choose Auto Insert and set the location to Site Wide Footer. This loads the widget on every page once, just before </body>.
  6. Toggle the snippet to Active (top-right of the editor) and click Save Snippet.

About type="module" in WPCode: Some WPCode versions show a "Module" checkbox under JavaScript SnippetFile-Based options. Do not enable it. The Converge widget is bundled as a classic IIFE script — it attaches to the page via a regular script tag and does not use import/export syntax. Marking it as a module either does nothing or, on stricter setups, causes the script to fail to execute because the browser applies strict-mode and deferred-execution rules the bundle doesn't need.

Verify in the WordPress front-end: open any public page on your site (signed out, or in an incognito window so you bypass admin-bar HTML), view source, and search for widget.js. The Converge script tag should appear once, near the bottom of the page. The chat bubble should appear in the bottom-right corner within 1–2 seconds.

If you're using a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache), purge the cache after activating the snippet — cached HTML won't include the new script tag until it's rebuilt.

5

Verify the widget is working

After adding the code, open your website in a browser. You should see the chat bubble in the bottom-right corner of the page.

Test the widget: Click the chat bubble to open the widget. You'll see your custom welcome message (if you've set one) and a message input field. Send a test message — it should appear in your Converge inbox within seconds.

What you should see:

  • The chat bubble appears in the corner (if enabled in settings)
  • The widget displays your brand color and header image (if customized)
  • Clicking the bubble opens the chat window
  • Sending a message delivers it to your Converge inbox
  • The customer can receive replies in the widget without refreshing the page

If the widget doesn't appear:

  • Check browser console: Press F12 and look for errors. Common issues include CSP (Content Security Policy) blocking the script, or ad blockers.
  • Clear cache: Browser caching can sometimes prevent the widget from loading. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R) to bypass cache.
  • Verify the code: Make sure you copied the entire embed code and it's placed correctly in your HTML.
  • Check CSP headers: If your site has strict CSP, add unpkg.com to your script-src whitelist.

Success indicator: When a visitor opens the widget on your site and sends a message — and that message appears in your Converge inbox where you can reply — the widget is fully working.

Pro tip: Customize the widget appearance (brand color, header image, welcome message) from SettingsPlatformsWidgetCustomize to match your brand. This creates a more professional, cohesive experience for visitors.

Frequently Asked Questions

No. The Converge widget is built as a classic IIFE script bundle, not an ES module. The default snippet shown in your workspace includes type="module" only because it's harmless on modern browsers — the script executes the same way either way. If your installer (WPCode, GTM, a CSP rule, or a CMS that validates script types) rejects or strips type="module", remove it. The widget will still load and run correctly with a plain <script async src="..." data-api-key="..."></script> tag.

Install WPCode from PluginsAdd New, then open Code Snippets+ Add SnippetAdd Your Custom Code. Set Code Type to HTML Snippet and paste the Converge embed code (<script async src="https://unpkg.com/@convergeapp/chat-widget/dist/widget.js" data-api-key="YOUR_API_KEY"></script>) exactly as shown in your Converge widget settings. Under Insertion, pick Auto InsertSite Wide Footer, then toggle the snippet to Active and save. Purge any caching plugin afterward. Do not enable WPCode's "Module" option — the widget is not an ES module.

Yes, but with a small change. WPCode's JavaScript Snippet type wraps your code in its own <script> tag, so you should paste only the loader body — not the full <script>...</script> wrapper. In Converge's widget settings, switch the install method to Manual to get a JavaScript loader variant (one that creates a document.createElement('script') and sets .src and .setAttribute('data-api-key', ...)). Paste that body into the JavaScript Snippet editor. For most users the HTML Snippet path is simpler.

Related Articles

Ready to try Converge?

$49/month flat. Up to 15 agents. 7-day free trial, no credit card required.

Start Free Trial