How can I add the Hexabot Chat Widget to my website?

Hexabot is a self-hosted, fair-core AI workflow automation platform. Use it to build AI chatbots, conversational AI, and workflow-driven automations across channels.

The Hexabot Chat Widget adds a website chat widget to any website or web app. It connects your site to a Web Source in Hexabot v3.

Use this guide when you manage the site code directly. If you use WordPress, install the plugin instead.

WordPress site? Use the Hexabot WordPress Chat Widget plugin instead of editing theme files manually. You can also review the GitHub repository.

Before you start

• Running Hexabot v3 instance

• Public Hexabot API URL, such as https://example.com/api

• One enabled Web Source in Admin → Integrations → Channels

• Your website origin added to Allowed domains

• Source Ref copied from the Web Source form

• Optional workflowId if this site should start a specific workflow

Pass the Source Ref as the widget sourceId.

How setup works

1. Create a Web Source for the site.

2. Add the Hexabot Chat Widget with your API URL and sourceId.

3. Pass workflowId only when you want to override the source default workflow.

Create a separate Web Source for each website when domains, branding, or workflows differ.

Learn more in Channels and Sources and Web Source.

Step 1: Create a Web Source

1. Open Admin → Integrations → Channels.

2. Click Add.

3. Choose web.

4. Enter a clear source name.

5. Add the exact website origin to Allowed domains.

6. Set a Default workflow if this website should always start one workflow.

7. Copy Source Ref.

8. Save the source.

Use the copied Source Ref as the widget sourceId.

Step 2: Add the widget

Imperative API (>= v3.5)

The imperative Embed API is available starting with version 3.5.0

Use the CDN build for the quickest and most streamlined setup along with React 18 or 19.

<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/umd-react@19/dist/react.production.min.js"
></script>
<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/umd-react@19/dist/react-dom.production.min.js"
></script>
<link rel="stylesheet" href="<<WIDGET URL>>/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@hexabot-ai/widget@latest/dist/hexabot-widget.umd.js"></script>

<div id="hexabot-chat-widget"></div>
<script>
  const embed = HexabotWidget.config({
    id: "hexabot-chat-widget",
    css: "https://cdn.jsdelivr.net/npm/@hexabot-ai/widget@latest/dist/style.css",
    apiUrl: "<<WIDGET URL>>",
    channel: "web",
    sourceId: "replace-with-source-id",
    primaryColor: "#29998e",
    language: "en",
    transport: "ws",
  });

  embed.show();
</script>

Simple website

Use the CDN build when you want the fastest setup.

<div id="hexabot-chat-widget"></div>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@hexabot-ai/widget@latest/dist/style.css">
<script crossorigin src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@hexabot-ai/widget@latest/dist/hexabot-widget.umd.js"></script>
<script>
  ReactDOM.render(
    React.createElement(HexabotWidget, {
      apiUrl: "https://example.com/api",
      channel: "web",
      sourceId: "YOUR_SOURCE_REF",
      workflowId: "OPTIONAL_WORKFLOW_ID",
      language: "en",
      transport: "ws"
    }),
    document.getElementById("hexabot-chat-widget")
  );
</script>

Remove workflowId to use the Web Source default workflow.

Replace @latest with a fixed version when you want reproducible deploys.

React or Next.js

Install the package:

npm install @hexabot-ai/widget

Render the widget in your app:

import { ChatWidget } from '@hexabot-ai/widget';
import '@hexabot-ai/widget/dist/style.css';

export function SupportWidget() {
  return (
    <ChatWidget
      apiUrl="https://your-hexabot.example.com/api"
      channel="web"
      sourceId="YOUR_SOURCE_REF"
      workflowId="OPTIONAL_WORKFLOW_ID"
      language="en"
      transport="ws"
    />
  );
}

Remove workflowId to use the Web Source default workflow.

Step 3: Verify the connection

Open the website and confirm the widget loads.

Then check these basics:

• The Web Source is enabled.

• The website origin matches Allowed domains exactly.

• apiUrl points to your public Hexabot API.

• sourceId matches the copied Source Ref.

How workflow routing works

Hexabot resolves the workflow in this order:

1. Widget workflowId

2. Web Source Default workflow

3. Channel or workflow trigger behavior

Use workflowId only when the page should force a specific flow.

Web Source settings that affect the widget

Manage website behavior in the Web Source form.

Common settings include:

• Allowed domains for website access control

• Greeting message, window title, and avatar URL

• Show emoji, show file, and show location

• Persistent menu, disable input, and allowed upload MIME types

Maximum upload size is not a Web Source setting. Set it in the widget client with maxUploadSize and enforce it on the server.

Troubleshooting

Widget does not appear

Check that the widget script and stylesheet load. Then confirm the Web Source is enabled and sourceId matches the copied Source Ref.

Invalid API URL

Use the public Hexabot API URL. Include the API base path, such as https://example.com/api.

Invalid Source Ref

Copy the Source Ref from the Web Source form. Pass that value as sourceId.

Domain not allowed

Add the exact site origin to Allowed domains. Include the scheme, subdomain, and port when needed.

WebSocket blocked

The widget uses Socket.IO transport. If a proxy blocks WebSocket upgrades, allow them or set transport="polling".

Uploads not working

Confirm the Web Source allows the file MIME type. Then check server upload limits and the widget maxUploadSize value.

Styling conflicts

Load the widget stylesheet. If your site CSS still leaks into the widget, mount it inside a shadow root.

Related pages

• Channels and Sources