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. Before embedding, you need to publish your agent:

Go to Agents in the dashboard and select your agent.
Click Deploy and choose Web Widget.
Configure the widget settings (name, theme, welcome message).
Click Publish to generate your embed code.
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:

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

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

npm install @thinnest-ai/embed-sdk

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"
    />
  );
}

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

<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

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

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

Go to Settings > API Keys in the dashboard.
Click Create Widget Key.
Select the agent this key should have access to.
Set an optional expiry date.
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:

In Settings > API Keys, click the key you want to restrict.
Add allowed domains (e.g., yourdomain.com, app.yourdomain.com).
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:

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

<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

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

After configuring your widget, click Preview.
A live preview opens showing exactly how the widget will look.
Send test messages to verify agent behavior.
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 — Build custom chat integrations with the API directly.
Agent Configuration — Customize the agent powering your widget.
Campaigns — Reach out to users proactively.

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Embed Widget

Publishing an Agent as a Widget

Embedding in Your Website

Script Tag (Recommended)

Iframe Embed

React Component

Widget Configuration

Basic Settings

Example with All Options

Theme and Appearance

Built-in Themes

Custom Colors

Custom CSS

Widget Authentication

Creating a Widget API Key

Key Permissions

Domain Restrictions

Channels

Text Chat

Voice

File Attachments

Testing Your Widget

Troubleshooting

Next Steps

​Embed Widget

​Publishing an Agent as a Widget

​Embedding in Your Website

​Script Tag (Recommended)

​Iframe Embed

​React Component

​Widget Configuration

​Basic Settings

​Example with All Options

​Theme and Appearance

​Built-in Themes

​Custom Colors

​Custom CSS

​Widget Authentication

​Creating a Widget API Key

​Key Permissions

​Domain Restrictions

​Channels

​Text Chat

​Voice

​File Attachments

​Testing Your Widget

​Troubleshooting

​Next Steps

Embed Widget

Publishing an Agent as a Widget

Embedding in Your Website

Script Tag (Recommended)

Iframe Embed

React Component

Widget Configuration

Basic Settings

Example with All Options

Theme and Appearance

Built-in Themes

Custom Colors

Custom CSS

Widget Authentication

Creating a Widget API Key

Key Permissions

Domain Restrictions

Channels

Text Chat

Voice

File Attachments

Testing Your Widget

Troubleshooting

Next Steps