Skip to main content
The ClientX widget is a self-contained IIFE bundle — a single JavaScript file that you load with a <script> tag. It mounts into an isolated Shadow DOM element so its styles never conflict with your site’s CSS, and it works on any page that can render HTML: static sites, server-rendered apps, single-page applications, Webflow projects, Framer sites, and WordPress installs alike.

​
Basic embed snippet

Copy the snippet below and paste it before the closing </body> tag of any page where you want the widget to appear: 
<script
  src="https://clientxserver-production.up.railway.app/widget/clientx-widget.iife.js"
  data-workspace-id="your-workspace-slug"
  data-server-url="https://clientxserver-production.up.railway.app"
  defer
></script>
Replace your-workspace-slug with your workspace slug or UUID from the dashboard. Everything else can stay as-is.

​
Script attributes

The embed script reads its configuration from two data-* attributes on the script tag itself:
​
data-workspace-id
string
required
Your workspace slug or UUID. The widget uses this value to fetch your agent’s configuration (name, colors, knowledge base, CTAs) from the server and to route all chat messages to the correct workspace.You can find your workspace ID in the dashboard under Settings → General.
​
data-server-url
string
The base URL of the ClientX server. Defaults to https://clientxserver-production.up.railway.app when omitted.You only need to set this attribute if you are running a self-hosted ClientX instance or are developing locally (for example, http://localhost:3001).

​
Platform-specific installation

Paste the embed snippet directly before the closing </body> tag of your HTML file:
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Site</title>
  </head>
  <body>
    <!-- your page content -->

    <script
      src="https://clientxserver-production.up.railway.app/widget/clientx-widget.iife.js"
      data-workspace-id="your-workspace-slug"
      data-server-url="https://clientxserver-production.up.railway.app"
      defer
    ></script>
  </body>
</html>
The defer attribute ensures the script loads after the rest of your page content without blocking rendering.

​
Verify installation

After publishing your changes, open your website in a browser. Within a few seconds you should see the ClientX launcher bar — a floating white pill at the bottom-center of the page with your primary color accent and a ✦ spark icon. Click the launcher to open the chat panel and send a test message. If the agent responds with information from your knowledge base, your installation is working correctly.
Use the Widget Preview panel in your dashboard (Settings → Widget → Preview) to test changes to your agent’s name, colors, welcome message, and CTAs before publishing them live. The preview lets you chat with your agent in a sandboxed environment that mirrors exactly what visitors will see.
If the launcher bar does not appear, check your browser console for errors. The most common causes are a missing or misspelled data-workspace-id, a Content Security Policy (CSP) header on your site that blocks external scripts, or an ad blocker preventing the script from loading.