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

# Embed Widget

> Add a thinnestAI chat widget to your website with a few lines of code. Configure appearance, authentication, and channels.

# Embed Widget

The embed widget lets you add a fully functional AI chat interface to any website. Your visitors can interact with your thinnestAI agent without leaving your site.

## Publishing an Agent as a Widget

Before embedding, you need to publish your agent:

1. Go to **Agents** in the dashboard and select your agent.
2. Click **Deploy** and choose **Web Widget**.
3. Configure the widget settings (name, theme, welcome message).
4. Click **Publish** to generate your embed code.
5. Copy the embed code and add it to your website.

Once published, your agent is accessible via the widget. You can update the agent's behavior at any time without changing the embed code.

## Embedding in Your Website

There are two ways to embed the widget: a **script tag** (recommended) or an **iframe**.

### Script Tag (Recommended)

Add this snippet before the closing `</body>` tag on your website:

```html theme={null}
<script
  src="https://cdn.thinnest.ai/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_WIDGET_API_KEY"
  async
></script>
```

This creates a floating chat bubble in the bottom-right corner of your page. Clicking it opens the chat interface.

### Iframe Embed

For more control over placement, use an iframe:

```html theme={null}
<iframe
  src="https://chat.thinnest.ai/embed/YOUR_AGENT_ID?key=YOUR_WIDGET_API_KEY"
  width="400"
  height="600"
  style="border: none; border-radius: 12px;"
  allow="microphone"
></iframe>
```

The iframe approach is useful when you want to place the chat in a specific area of your page rather than as a floating bubble.

### React Component

If you're using React, install the embed SDK:

```bash theme={null}
npm install @thinnest-ai/embed-sdk
```

```jsx theme={null}
import { ThinnestChat } from '@thinnest-ai/embed-sdk';

function App() {
  return (
    <ThinnestChat
      agentId="YOUR_AGENT_ID"
      apiKey="YOUR_WIDGET_API_KEY"
      theme="light"
      position="bottom-right"
    />
  );
}
```

## Widget Configuration

Configure the widget from the dashboard or via data attributes in the embed code.

### Basic Settings

| Setting         | Data Attribute         | Description                                      |
| --------------- | ---------------------- | ------------------------------------------------ |
| Agent ID        | `data-agent-id`        | The agent powering the widget                    |
| API Key         | `data-api-key`         | Widget authentication key                        |
| Name            | `data-name`            | Display name shown in the widget header          |
| Welcome Message | `data-welcome-message` | First message shown to users                     |
| Placeholder     | `data-placeholder`     | Input field placeholder text                     |
| Position        | `data-position`        | Widget position: `bottom-right` or `bottom-left` |

### Example with All Options

```html theme={null}
<script
  src="https://cdn.thinnest.ai/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_WIDGET_API_KEY"
  data-name="Support Assistant"
  data-welcome-message="Hi! How can I help you today?"
  data-placeholder="Type your message..."
  data-position="bottom-right"
  data-theme="light"
  data-accent-color="#4F46E5"
  async
></script>
```

## Theme and Appearance

### Built-in Themes

| Theme   | Description                               |
| ------- | ----------------------------------------- |
| `light` | Light background with dark text (default) |
| `dark`  | Dark background with light text           |
| `auto`  | Follows the user's system preference      |

```html theme={null}
<script
  src="https://cdn.thinnest.ai/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_WIDGET_API_KEY"
  data-theme="dark"
  async
></script>
```

### Custom Colors

Override the default colors with your brand palette:

| Attribute           | Description                     | Example   |
| ------------------- | ------------------------------- | --------- |
| `data-accent-color` | Primary button and accent color | `#4F46E5` |
| `data-bg-color`     | Widget background color         | `#FFFFFF` |
| `data-text-color`   | Primary text color              | `#1F2937` |
| `data-header-color` | Header background color         | `#4F46E5` |

### Custom CSS

For full control, target the widget's CSS classes:

```css theme={null}
/* Widget container */
.thinnest-widget-container {
  font-family: 'Inter', sans-serif;
}

/* Chat bubble button */
.thinnest-widget-bubble {
  width: 60px;
  height: 60px;
}

/* Message bubbles */
.thinnest-widget-message--agent {
  background: #F3F4F6;
}

.thinnest-widget-message--user {
  background: #4F46E5;
  color: white;
}
```

## Widget Authentication

Widget API keys are separate from your account API keys. They have limited permissions — they can only interact with the specific agent they're assigned to.

### Creating a Widget API Key

1. Go to **Settings > API Keys** in the dashboard.
2. Click **Create Widget Key**.
3. Select the agent this key should have access to.
4. Set an optional expiry date.
5. Copy the key — it won't be shown again.

### Key Permissions

Widget keys can:

* Send messages to the assigned agent
* Create and continue sessions
* Upload attachments (if enabled on the agent)

Widget keys cannot:

* Access other agents
* Modify agent configuration
* Access billing or account settings

### Domain Restrictions

For added security, restrict which domains can use your widget key:

1. In **Settings > API Keys**, click the key you want to restrict.
2. Add allowed domains (e.g., `yourdomain.com`, `app.yourdomain.com`).
3. Requests from other domains will be rejected.

## Channels

The widget supports multiple communication channels beyond text chat.

### Text Chat

The default channel. Users type messages and receive text responses. Supports markdown formatting in responses.

### Voice

Enable voice input so users can speak to your agent:

```html theme={null}
<script
  src="https://cdn.thinnest.ai/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_WIDGET_API_KEY"
  data-enable-voice="true"
  async
></script>
```

When enabled, a microphone icon appears in the input area. Users click to speak, and their speech is transcribed and sent to the agent.

### File Attachments

Allow users to upload files for your agent to process:

```html theme={null}
<script
  src="https://cdn.thinnest.ai/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_WIDGET_API_KEY"
  data-enable-attachments="true"
  data-allowed-file-types=".pdf,.png,.jpg,.csv"
  data-max-file-size="10"
  async
></script>
```

| Attribute                 | Description                                |
| ------------------------- | ------------------------------------------ |
| `data-enable-attachments` | Enable file upload (`true`/`false`)        |
| `data-allowed-file-types` | Comma-separated list of allowed extensions |
| `data-max-file-size`      | Maximum file size in MB                    |

## Testing Your Widget

Use the **Preview** feature in the dashboard to test your widget before deploying:

1. After configuring your widget, click **Preview**.
2. A live preview opens showing exactly how the widget will look.
3. Send test messages to verify agent behavior.
4. Adjust settings and preview again until you're satisfied.

## Troubleshooting

| Issue                          | Solution                                                                  |
| ------------------------------ | ------------------------------------------------------------------------- |
| Widget doesn't appear          | Check that the script tag is before `</body>` and the agent ID is correct |
| "Unauthorized" errors          | Verify the API key and check domain restrictions                          |
| Slow responses                 | Check your agent's model and knowledge base size                          |
| Widget overlaps other elements | Adjust `data-position` or add custom CSS with `z-index`                   |
| Voice not working              | Ensure the page is served over HTTPS (required for microphone access)     |

## Next Steps

* [Chat API](/docs/chat) — Build custom chat integrations with the API directly.
* [Agent Configuration](/docs/agents) — Customize the agent powering your widget.
* [Campaigns](/docs/campaigns) — Reach out to users proactively.