Web Widget

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

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:

<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="YOUR_AGENT_ID"
  async
></script>

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

Finding Your Agent ID

Open your agent in the thinnestAI dashboard
Go to the Deploy tab
Copy the Agent ID or Publish ID shown in the embed code

Configuration Options

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

Attribute	Type	Default	Description
`data-agent-id`	string	Required	Your agent's public ID
`data-key`	string	—	Publishable key (recommended for production)
`data-theme`	string	`"light"`	`"light"` or `"dark"`
`data-position`	string	`"bottom-right"`	`"bottom-right"` or `"bottom-left"`
`data-primary-color`	string	`"#FF4D00"`	Brand color (hex)
`data-title`	string	Agent name	Chat window title
`data-subtitle`	string	—	Subtitle below the title
`data-placeholder`	string	`"Type a message..."`	Input placeholder
`data-welcome-message`	string	—	First message shown to users
`data-user-id`	string	Auto-generated	Identify users for session continuity

Full Example

<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="agent_abc123"
  data-theme="dark"
  data-primary-color="#6366F1"
  data-title="Acme Support"
  data-subtitle="We typically reply in seconds"
  data-placeholder="Ask us anything..."
  data-welcome-message="Hi! How can I help you today?"
  async
></script>

Publishable Keys (Production)

For production deployments, use publishable keys instead of raw agent IDs. Keys add origin restrictions and usage limits.

Create a Key

curl -X POST https://api.thinnest.ai/widget-keys \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "name": "Production Key",
    "allowed_origins": ["https://www.example.com"],
    "config": {
      "max_sessions_per_day": 1000,
      "max_messages_per_session": 100
    }
  }'

Use the Key

<script
  src="https://app.thinnest.ai/embed.js"
  data-key="pk_live_abc123xyz"
  async
></script>

Key Features

Feature	Description
Origin Restrictions	Widget only loads on specified domains
Session Quotas	Limit daily sessions to control costs
Message Limits	Cap messages per session
Voice Minutes	Limit voice interaction time

Lead Capture

Collect user information before they start chatting.

Enable Lead Capture

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

Supported Field Types

Type	Description
`text`	Single-line text input
`email`	Email with validation
`phone`	Phone number input
`textarea`	Multi-line text
`select`	Dropdown with predefined options

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

JavaScript SDK

For deeper integration, use the SDK directly:

npm install @thinnestai/embed-sdk

import { ThinnestAI } from '@thinnestai/embed-sdk';

const agent = new ThinnestAI({
  agentId: 'agent_abc123',
  theme: 'light',
  position: 'bottom-right',
});

agent.open();
agent.sendMessage('Hello!');

agent.on('message', (msg) => {
  console.log('Agent replied:', msg.content);
});

SDK Methods

Method	Description
`open()`	Open the chat widget
`close()`	Close the chat widget
`toggle()`	Toggle open/close
`sendMessage(text)`	Send a message programmatically
`on(event, callback)`	Subscribe to events
`destroy()`	Remove the widget
`setUser(userId)`	Set user identifier

SDK Events

Event	Payload	Description
`message`	`{ role, content }`	New message received
`open`	—	Widget opened
`close`	—	Widget closed
`error`	`{ code, message }`	Error occurred
`session_start`	`{ sessionId }`	New session started

Styling

Override default styles with CSS variables:

:root {
  --thinnestai-primary: #6366F1;
  --thinnestai-bg: #ffffff;
  --thinnestai-text: #1a1a1a;
  --thinnestai-border-radius: 12px;
  --thinnestai-font-family: 'Inter', sans-serif;
}

Custom Launcher

Replace the default bubble with your own button:

<button onclick="agent.toggle()">Chat with us</button>

<script>
  const agent = new ThinnestAI({
    agentId: 'agent_abc123',
    showLauncher: false,
  });
</script>

Testing

Locally — Use localhost as an allowed origin
Dashboard — Click Test Chat on your agent page
Test file — Create a minimal HTML page with the embed script

Best Practices

Use publishable keys in production with origin restrictions
Set session and message limits to control costs
Add a welcome message to increase engagement
Match your brand colors and position
Test on mobile to verify responsive layout

On this page