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

# Chat Widget

> Add Cobi's Data Assistant to your website with a simple iframe

## Overview

The Cobi chat widget can be embedded on any website as an iframe. Visitors interact with your AI assistant directly on your site. Authentication is handled via embed API keys that you create in the Cobi dashboard.

<Note>
  Embed keys are scoped to a single data source and can be restricted to
  specific domains for production use.
</Note>

## Getting Started

<Steps>
  <Step title="Create an Embed Key">
    Navigate to **Developer** > **Channels** in the Cobi dashboard. Click **Create Embed Key** and fill in:

    | Field                            | Description                                                                                                                |
    | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | **Name**                         | A label for this key (e.g. "Production website")                                                                           |
    | **Data Source**                  | The data source the embed will query against                                                                               |
    | **Data Scope** *(optional)*      | Restrict which tables the key can query and enforce row-level isolation. See [Data Scopes](/platform/channels/data-scopes) |
    | **Allowed Origins** *(optional)* | Domains permitted to load the widget (e.g. `https://yoursite.com`)                                                         |
    | **Expiry Date** *(optional)*     | When the key should expire. Leave blank for no expiry                                                                      |
    | **Chat History** *(optional)*    | Allow this key to access conversation history. Must be enabled here before the `chatHistory` URL parameter has any effect  |

    <Warning>
      The full API key is only shown once at creation time. Copy the embed snippet immediately. You won't be able to retrieve the full key later.
    </Warning>
  </Step>

  <Step title="Add the Iframe to Your Site">
    After creating the key, you'll see an embed snippet. Copy and paste it into your website's HTML:

    ```html theme={null}
    <iframe
      src="https://app.hellocobi.com/embed/chat?key=cobi_embed_your_key_here"
      style="width: 100%; height: 600px; border: none; border-radius: 8px;"
      allow="clipboard-write"
      title="Cobi Chat"
    ></iframe>
    ```
  </Step>

  <Step title="Verify It Works">
    Load your page in a browser. The chat widget should appear and respond to messages using your configured data source.
  </Step>
</Steps>

## Configuration

### URL Parameters

The embed URL supports the following query parameters:

| Parameter     | Required    | Description                                                                                                                                                                             |
| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | Yes         | Your embed API key                                                                                                                                                                      |
| `scopeId`     | Conditional | The tenant or entity identifier used for row-level filtering. Required when the embed key has a [data scope](/platform/channels/data-scopes) assigned. Requests without it return `403` |
| `theme`       | No          | `light`, `dark`, or `system` (default). Matches the widget's appearance to your site                                                                                                    |
| `chatHistory` | No          | `true` to show the chat history panel. Only takes effect if history was enabled when the embed key was created                                                                          |
| `userId`      | No          | An identifier for the current user. See [User Identity](#user-identity) below                                                                                                           |

```
https://app.hellocobi.com/embed/chat?key=cobi_embed_...&scopeId=outlet_42&theme=dark&chatHistory=true&userId=user_123
```

### Allowed Origins

When you specify allowed origins during key creation, only those domains can load the widget. Requests from other origins are rejected with a `403` error.

* Leave empty during development to allow any origin
* For production, always specify your exact domains (e.g. `https://yoursite.com`)
* The `Origin` header is required when allowed origins are configured

<Tip>
  You can add multiple allowed origins to a single key, for example if your site
  is accessible on both `https://example.com` and `https://www.example.com`.
</Tip>

### Theming

The widget respects light and dark mode via the `theme` parameter:

| Value    | Behavior                                   |
| -------- | ------------------------------------------ |
| `system` | Matches the user's OS preference (default) |
| `light`  | Forces light mode                          |
| `dark`   | Forces dark mode                           |

### Chat History

Chat history lets users return to previous conversations in the widget. It is controlled by two things:

1. **Key setting:** History must be enabled when creating the embed key in the dashboard. If it wasn't, passing `chatHistory=true` in the URL has no effect.
2. **URL parameter:** Even if the key supports history, you must pass `chatHistory=true` to make the history panel visible in the iframe.

This two-layer control lets you enable history on a key but selectively show it only on certain pages.

### User Identity

By default, the widget generates a unique user ID per browser and stores it in `localStorage`. A returning visitor on the same browser is recognised as the same user and can see their previous chats, but the same user on a different device starts fresh.

To share chat history across browsers, pass your own `userId`:

```html theme={null}
<iframe
  src="https://app.hellocobi.com/embed/chat?key=cobi_embed_...&userId=user_abc123"
  style="width: 100%; height: 600px; border: none; border-radius: 8px;"
  allow="clipboard-write"
  title="Cobi Chat"
></iframe>
```

<Note>
  Pass a stable, per-user identifier from your own auth system (e.g. a database
  user ID). Do not use personally identifiable information such as email
  addresses as the `userId`.
</Note>

### Data Scoping

Data scopes let you restrict an embed key to a specific subset of tables and enforce row-level isolation so each caller only sees their own data. This is the recommended security model for any multi-tenant deployment.

When a scope is assigned to an embed key, you must pass a `scopeId` in every iframe URL. The value is the primary key of the tenant or entity whose data the current user should see:

```html theme={null}
<iframe
  src="https://app.hellocobi.com/embed/chat?key=cobi_embed_your_key_here&scopeId=outlet_42"
  style="width: 100%; height: 600px; border: none; border-radius: 8px;"
  allow="clipboard-write"
  title="Cobi Chat"
></iframe>
```

<Warning>
  Always render `scopeId` server-side from your own authentication system.
  Never derive it from user input or client-side storage, as this would allow a
  user to access another tenant's data.
</Warning>

See [Data Scopes](/platform/channels/data-scopes) for a full walkthrough on creating scopes and configuring row-level access.

## Available Connections

The embed widget queries whichever data source you select when creating the embed key. All data source types supported by Cobi are available:

| Type           | Notes                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| **PostgreSQL** | PostgreSQL 12+                                                                                                   |
| **MySQL**      | MySQL 8.0+                                                                                                       |
| **MongoDB**    | MongoDB Atlas and self-hosted instances. See [MongoDB](/platform/data-connectors/mongodb) for schema conventions |

The data source is locked to the key at creation time and cannot be changed by the client.

## Rate Limiting

Each embed key is rate-limited to **1,000 requests per hour**. When the limit is exceeded:

* The API returns `429 Too Many Requests` with a `Retry-After` header
* The widget displays a user-friendly message asking the visitor to wait

If you need higher limits, contact the Cobi team at [support@hellocobi.com](mailto:support@hellocobi.com).

## Security

Keys are hashed at rest and only the first 18 characters are stored for display. When allowed origins are configured, requests from any other domain are rejected outright. The data source is locked to the key at creation time and cannot be changed by the client. Embed requests have restricted access and cannot view internal documents. The widget does not use cookies or require user authentication.

When a [data scope](/platform/channels/data-scopes) is assigned to a key, table access and row-level filtering are enforced server-side and cannot be bypassed by modifying the iframe URL. The `scopeId` parameter identifies the caller's tenant but does not authenticate the request — authentication is always handled by the embed key itself.

## Managing Keys

From **Developer > Channels** you can view all active embed keys along with their allowed origins and status, and permanently revoke any key. When a key is deleted it takes effect on the next request with no delay or grace period.

## Troubleshooting

| Issue                          | Cause                                                                     | Solution                                                                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Widget shows "Missing API Key" | No `key` parameter in the URL                                             | Check the iframe `src` includes `?key=cobi_embed_...`                                                                                           |
| `403` error — access denied    | Origin not in allowed list, or `scopeId` missing/invalid for a scoped key | Add your domain to the key's allowed origins; if the key has a data scope, ensure `scopeId` is present in the URL and matches a valid tenant ID |
| `401` error                    | Key is invalid, expired, or deleted                                       | Create a new embed key in Developer > Channels                                                                                                  |
| `429` error                    | Rate limit exceeded                                                       | Wait for the rate limit window to reset (1 hour)                                                                                                |
| Widget crashes / white screen  | JavaScript error                                                          | The widget includes an error boundary. Try refreshing. If it persists, check the browser console                                                |