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

# Web Widget

> Embed your AI agent as a chat widget on any website with a single script tag or the JavaScript SDK.

# Web Widget

Deploy your agent as a floating chat widget on any website. Users click the bubble to open a conversation — no backend required on your side.

## Quick Setup

Add one line to your HTML:

```html theme={null}
<script
  src="https://api.thinnest.ai/embed/widget.js"
  data-publishable-key="pk_live_..."
  data-agent-id="YOUR_AGENT_PUBLIC_ID"
  data-widget-type="chat"
  async
></script>
```

This adds a chat bubble to the bottom-right corner of your page.

## Finding Your Agent ID & Key

1. Open your agent in the thinnestAI dashboard
2. Go to the **Deploy** tab
3. Select **Web Widget** and switch to the **Embed Code** tab
4. Copy the generated snippet containing your `data-publishable-key` and `data-agent-id`

## Configuration Options

Customize the widget with `data-` attributes on the script tag:

| Attribute              | Type   | Default      | Description                                         |
| ---------------------- | ------ | ------------ | --------------------------------------------------- |
| `data-publishable-key` | string | **Required** | Your publishable widget key                         |
| `data-agent-id`        | string | **Required** | Your agent's public ID                              |
| `data-widget-type`     | string | `"chat"`     | Widget type: `"chat"`, `"voice"`, or `"combined"`   |
| `data-api-url`         | string | —            | Target API URL (default handles this automatically) |

> \[!NOTE]
> The appearance (theme, colors, welcome message) is managed securely via your **Agent Studio → Deploy** settings, preventing unauthorized customization.

### Full Example

```html theme={null}
<script
  src="https://api.thinnest.ai/embed/widget.js"
  data-publishable-key="pk_live_abc123xyz"
  data-agent-id="ag_pub_xyz789"
  data-widget-type="chat"
  data-api-url="https://api.thinnest.ai"
  async
></script>
```

## Publishable Keys (Production)

For production deployments, you must use **publishable keys**. Keys add origin restrictions to prevent others from using your widget on unauthorized websites.

### Create a Key

```bash theme={null}
curl -X POST https://api.thinnest.ai/widget-keys \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "allowed_origins": ["https://www.example.com", "https://app.example.com"]
  }'
```

### Key Security Features

| Feature                 | Description                            |
| ----------------------- | -------------------------------------- |
| **Origin Restrictions** | Widget only loads on specified domains |

## Lead Capture

Collect user information before they start chatting.

### Enable Lead Capture

1. Go to your agent's **Deploy** tab
2. Open **Web Embed** settings
3. Enable **Lead Collection**
4. Add fields: email, phone, name, company, or custom fields
5. Mark fields as required or optional

Users must complete the form before chatting. All captured data appears in your **Leads** dashboard.

## JavaScript SDK

For deeper integration, use the SDK programmatically:

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

Access the widget programmatically via `window.ThinnestAI`:

```javascript theme={null}
// Send a message
window.ThinnestAI.sendMessage("Hello! I need help with my order.");

// Open the chat widget
window.ThinnestAI.open();

// Close the chat widget
window.ThinnestAI.close();

// Start a new chat session
window.ThinnestAI.newChat();

// Destroy the widget
window.ThinnestAI.destroy();
```

### SDK Methods

| Method              | Description                                  |
| ------------------- | -------------------------------------------- |
| `open()`            | Open the chat widget                         |
| `close()`           | Close the chat widget                        |
| `sendMessage(text)` | Send a message programmatically              |
| `startVoice()`      | Starts a voice session (if voice is enabled) |
| `newChat()`         | Starts a new chat session                    |
| `destroy()`         | Remove the widget from the DOM               |

### SDK Events

Listen for widget events on the global `window` object:

```javascript theme={null}
window.addEventListener('thinnestai.message.received', (e) => {
  console.log('Agent replied:', e.detail);
});
```

| Event                         | Description             |
| ----------------------------- | ----------------------- |
| `thinnestai.session.started`  | New session initialized |
| `thinnestai.message.sent`     | User sent a message     |
| `thinnestai.message.received` | Agent response received |
| `thinnestai.call.started`     | Voice call started      |
| `thinnestai.call.ended`       | Voice call ended        |
| `thinnestai.error`            | Error occurred          |
| `thinnestai.opened`           | Widget opened           |
| `thinnestai.closed`           | Widget closed           |
| `thinnestai.lead.captured`    | Lead form submitted     |

## Styling and Customization

Widget customization is done entirely through the **Agent Studio Deploy Panel → Design tab**, not CSS variables or script tags. This leverages an isolated Shadow DOM.

Options you can configure in the dashboard include:

* Colors (primary, background, text, header, bubbles, input)
* Font family and Border radius
* Dark/light mode
* Avatar URL
* Glassmorphism effect
* Custom launcher icons and popover messages

## Testing

1. **Locally** — Add `localhost` to your widget key's allowed origins.
2. **Dashboard** — Use the **Test Chat** feature on your agent page.
3. **Test file** — Create a minimal HTML page with the embed script pointing to your agent.

## Best Practices

* **Restrict origins** — Only add trusted domains to your publishable key's `allowed_origins`.
* **Add a welcome message** to increase engagement (configurable in the dashboard).
* **Match your brand** colors and position using the Design tab.
* **Test on mobile** to verify the widget's responsive behavior fits your site.