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:

<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 @thinnestai/embed-sdk

import { ThinnestChat } from '@thinnestai/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

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

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

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

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

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

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.