> For the complete documentation index, see [llms.txt](https://docs.hexabot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hexabot.ai/faq/how-can-i-add-the-hexabot-chat-widget-to-my-website.md).

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

<figure><img src="/files/MH5JlnwevqzK0Lk1t0d3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**WordPress site?** Use the [Hexabot WordPress Chat Widget plugin](https://wordpress.org/plugins/hexabot-wordpress-live-chat-widget/) instead of editing theme files manually. You can also review the [GitHub repository](https://github.com/hexastack/hexabot-wordpress-live-chat-widget).
{% endhint %}

### 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](/integrations/channels-and-sources.md) and [Web Source](broken://spaces/12ok30OlFEEb6WoWfH8l/pages/H2a8RRCJL4bdDrEaN4Ll).

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

{% tabs %}
{% tab title="Simple website" %}
Use the CDN build when you want the fastest setup.

```html
<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.
{% endtab %}

{% tab title="React or Next.js" %}
Install the package:

```bash
npm install @hexabot-ai/widget
```

Render the widget in your app:

```tsx
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.
{% endtab %}
{% endtabs %}

### 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](/integrations/channels-and-sources.md)
* [Web Source](broken://spaces/12ok30OlFEEb6WoWfH8l/pages/H2a8RRCJL4bdDrEaN4Ll)
* [Live chat widget](broken://spaces/12ok30OlFEEb6WoWfH8l/pages/Vs0nElpJi4yD7BXuOIdf)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hexabot.ai/faq/how-can-i-add-the-hexabot-chat-widget-to-my-website.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.