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

> Deploy your AI agent as a chat widget on any website — embed with a single script tag or use the JavaScript SDK for custom integrations.

# Embed Widget & SDK

Deploy your AI agent as a **chat widget** on any website. The embed system provides a drop-in script tag for quick setup and a JavaScript API for programmatic integrations.

## Quick Setup

Add a single line of code to embed the chat widget:

```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 floating chat bubble to the bottom-right corner of your page. Users click it to open a conversation with your agent.

## Widget Configuration

### Script Tag Attributes

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

### Example: Full Configuration

```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="combined"
  data-api-url="https://api.thinnest.ai"
  async
></script>
```

## Publishable Keys

For production deployments, you must use **publishable keys** to authenticate your widget.

### Create a Publishable 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 Widget Key",
    "allowed_origins": ["https://www.example.com", "https://app.example.com"]
  }'
```

### Response

```json theme={null}
{
  "id": 1,
  "key_prefix": "pk_live",
  "publishable_key": "pk_live_abc123xyz",
  "allowed_origins": ["https://www.example.com"]
}
```

### Key Security Features

| Feature                 | Description                                  |
| ----------------------- | -------------------------------------------- |
| **Origin Restrictions** | Only allows embedding from specified domains |

## JavaScript SDK

For deeper integration, include the widget package:

### Installation

```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();

// Start a voice session
window.ThinnestAI.startVoice();

// 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 to the agent          |
| `startVoice()`      | Open the widget and start voice call |
| `newChat()`         | Start a fresh chat session           |
| `destroy()`         | Remove the widget from the page      |

### 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.session.restored` | Existing session restored |
| `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       |

## Agent API Keys

For server-to-server integrations (not browser-based), use **Agent API Keys**:

```bash theme={null}
# Create an agent API key
curl -X POST https://api.thinnest.ai/agents/{agent_id}/api-keys \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Integration Key"
  }'
```

Use the key to chat with your agent from any backend:

```bash theme={null}
curl -X POST https://api.thinnest.ai/v1/agents/{agent_id}/chat \
  -H "Authorization: Bearer ak_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "user_id": "customer_456"
  }'
```

## Styling & Customization

Widget customization is done entirely through the **Agent Studio Deploy Panel → Design tab**. This leverages an isolated Shadow DOM framework ensuring consistent rendering across environments.

You can customize:

* General look and feel (Colors, Typography)
* Launcher style and icons
* Popover messages and branding removal

## Testing Your Widget

1. **Local testing** — Add `localhost` as an allowed origin for your widget key.
2. **Preview in dashboard** — Click **Test Chat** on your agent's page.
3. **Test HTML file** — Create a minimal HTML file with the embed script.

```html theme={null}
<!DOCTYPE html>
<html>
<head><title>Widget Test</title></head>
<body>
  <h1>Testing My Agent</h1>
  <script
    src="https://api.thinnest.ai/embed/widget.js"
    data-publishable-key="pk_live_abc123xyz"
    data-agent-id="ag_pub_xyz789"
    async
  ></script>
</body>
</html>
```

## Best Practices

* **Use publishable keys in production** with correct origin restrictions.
* **Add a welcome message** to guide users.
* **Match your brand** using the Design settings.
* **Test on mobile** to verify the widget's layout on your site.