Platforms 4 steps

How to Install the Chat Widget on Your Website

Converge Team

• Updated February 3, 2026

Learn how to add the Converge chat widget to your website so visitors can start conversations directly from your pages.

Get your widget embed code

In Converge, go to Settings → Platforms → Widget. 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.

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 — The URL to the widget JavaScript file hosted on unpkg CDN
data-api-key — Your unique workspace API key (found in widget settings)
async type="module" — Loads the script asynchronously as an ES module for best performance

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 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.

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: Go to Online Store → Themes → Edit Code. Open theme.liquid and paste the code before </body>.

Webflow: Go to Project Settings → Custom 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.

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 Settings → Platforms → Widget → Customize to match your brand. This creates a more professional, cohesive experience for visitors.

Features