> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Website Widget

> Deploy the Onyx chat widget on your website

The Onyx Website Widget allows you to embed AI-powered chat directly on any website.

Features include:

* Lightweight \~100-150kb gzipped bundle
* Fully customizable colors and branding
* Responsive design (desktop popup, mobile fullscreen)
* Real-time streaming responses via SSE
* Session persistence across page reloads

## Deployment Options

### Cloud Deployment (Recommended)

For Onyx Cloud users, the widget is served from Onyx's CDN. Simply add the following to your website:

```html theme={null}
<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.1/dist/onyx-widget.js"></script>

<!-- Configure and display -->
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</onyx-chat-widget>
```

### Self-Hosted Deployment

For self-hosted Onyx instances, you'll need to build and host the widget yourself.

<Steps>
  <Step title="Clone the repository">
    Clone the [Onyx repository](https://github.com/onyx-dot-app/onyx) from GitHub.
  </Step>

  <Step title="Navigate to widget directory">
    ```bash theme={null}
    cd widget/
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Obtain a widget API key">
    Navigate to your Onyx admin panel and create a new API key specifically for the widget.

    <img className="rounded-image" src="https://mintcdn.com/danswer/glaei3niibtHdYyZ/assets/deployment/widget_api_key.png?fit=max&auto=format&n=glaei3niibtHdYyZ&q=85&s=6cd65dd19fd4d86a502e32b9380bc735" alt="Creating a widget API key in the Onyx admin panel" width="1020" height="836" data-path="assets/deployment/widget_api_key.png" />

    <Warning>
      Create a **limited-scope API key** with only chat permissions.
      Never use admin or full-access keys since the API key will be visible in client-side code.
    </Warning>
  </Step>

  <Step title="Configure environment (optional)">
    For builds with baked-in configuration, create a `.env` file:

    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` and set your backend URL and API key:

    ```
    VITE_WIDGET_BACKEND_URL=https://your-backend.com
    VITE_WIDGET_API_KEY=your_api_key
    ```
  </Step>

  <Step title="Build the widget">
    For **cloud-style deployment** (config via HTML attributes):

    ```bash theme={null}
    npm run build:cloud
    ```

    For **self-hosted deployment** (config baked into bundle):

    ```bash theme={null}
    npm run build:self-hosted
    ```
  </Step>

  <Step title="Deploy the bundle">
    Upload `dist/onyx-widget.js` to your CDN or web server.
  </Step>
</Steps>

### Customer Embed Code

After deployment, provide customers with the embed code:

**Cloud-style (attributes required):**

```html theme={null}
<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
  backend-url="https://your-backend.com"
  api-key="customer_api_key"
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</onyx-chat-widget>
```

**Self-hosted (config baked in):**

```html theme={null}
<script type="module" src="https://your-cdn.com/onyx-widget.js"></script>
<onyx-chat-widget
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</onyx-chat-widget>
```

## Configuration Reference

### Required Attributes

| Attribute     | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `backend-url` | string | Your Onyx backend API URL  |
| `api-key`     | string | API key for authentication |

#### `backend-url`

The URL of your Onyx backend API. This is where the widget sends chat requests.

* **Onyx Cloud**: Use `https://cloud.onyx.app` or your tenant-specific URL
* **Self-hosted**: Use your Onyx instance URL (e.g., `https://onyx.yourcompany.com`)

```html theme={null}
<!-- Onyx Cloud -->
<onyx-chat-widget backend-url="https://cloud.onyx.app/api" ...></onyx-chat-widget>

<!-- Self-hosted -->
<onyx-chat-widget backend-url="https://onyx.yourcompany.com" ...></onyx-chat-widget>
```

#### `api-key`

A valid Onyx API key for authenticating widget requests. **This key is visible in client-side code**,
so always use a limited-scope key.

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123xyz789"
  ...
></onyx-chat-widget>
```

<Note>
  For self-hosted builds with baked-in config,
  `backend-url` and `api-key` can be set via environment variables during build instead of HTML attributes.
</Note>

### Optional Attributes

| Attribute           | Type    | Default       | Description                                      |
| ------------------- | ------- | ------------- | ------------------------------------------------ |
| `agent-id`          | number  | `undefined`   | Specific agent/persona to use                    |
| `agent-name`        | string  | `"Assistant"` | Display name in header                           |
| `logo`              | string  | Onyx logo     | URL to custom logo image                         |
| `primary-color`     | string  | `#1c1c1c`     | Primary brand color (buttons, accents)           |
| `background-color`  | string  | `#e9e9e9`     | Widget background color                          |
| `text-color`        | string  | `#000000bf`   | Text color (75% opacity black)                   |
| `mode`              | string  | `"launcher"`  | Display mode: `"launcher"` or `"inline"`         |
| `include-citations` | boolean | `false`       | Show citation badges linking to source documents |

#### `include-citations`

When enabled, assistant messages display clickable citation badges below the response text.
Each badge shows a sequential number and the source document title, linking directly to the original document.

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123"
  include-citations="true"
>
</onyx-chat-widget>
```

<Warning>
  **Be mindful of document access when enabling citations.** The widget will cite any documents accessible to the
  configured agent or API key. If the agent has access to private or internal documents,
  citation links may point to resources that end users do not have permission to view.

  To avoid exposing private document links, either scope the agent's document access to only public-facing sources,
  or disable citations for public-facing widget deployments.
</Warning>

## API Key Security

<Warning>
  The widget's API key is exposed in client-side code. Always create a dedicated API key with:

  * **Limited permissions** - Only chat access, no admin features
  * **Rate limiting** - Prevent abuse from malicious actors
  * **Monitoring** - Track usage and detect anomalies
</Warning>

<Steps>
  <Step title="Create a widget-specific API key">
    In your Onyx admin panel, create a new API key with minimal permissions.
  </Step>

  <Step title="Enable rate limiting">
    Configure rate limits appropriate for your expected usage.
  </Step>

  <Step title="Monitor usage">
    Regularly review API key usage for unusual patterns.
  </Step>
</Steps>

## Browser Support

* Chrome/Edge 90+ (Chromium)
* Firefox 90+
* Safari 15+
* Mobile Safari (iOS 15+)
* Mobile Chrome (Android)

<Info>
  **Need help with setup?** Contact your Onyx administrator for API key configuration or deployment assistance.
</Info>