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.

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 SDK for custom integrations.

Quick Setup

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

<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="agent_abc123"
  data-theme="light"
  data-position="bottom-right"
  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.

Script Tag Attributes

Attribute	Type	Default	Description
`data-agent-id`	string	Required	Your agent's public ID
`data-theme`	string	`"light"`	Widget theme: `"light"` or `"dark"`
`data-position`	string	`"bottom-right"`	Bubble position: `"bottom-right"` or `"bottom-left"`
`data-primary-color`	string	`"#FF4D00"`	Brand color for the widget
`data-title`	string	Agent name	Chat window title
`data-subtitle`	string	`""`	Chat window subtitle
`data-placeholder`	string	`"Type a message..."`	Input placeholder text
`data-welcome-message`	string	`""`	Initial message from the agent
`data-user-id`	string	Auto-generated	Identify the user for session continuity

Example: Full Configuration

<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="agent_abc123"
  data-theme="dark"
  data-position="bottom-right"
  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?"
  data-user-id="user_12345"
  async
></script>

Publishable Keys

For production deployments, use publishable keys instead of agent IDs for added security:

Create a Publishable 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 Widget Key",
    "allowed_origins": ["https://www.example.com", "https://app.example.com"],
    "config": {
      "max_sessions_per_day": 1000,
      "max_messages_per_session": 100,
      "max_voice_minutes": 0
    }
  }'

Response

{
  "id": 1,
  "publishable_key": "pk_live_abc123xyz",
  "agent_id": "agent_abc123",
  "allowed_origins": ["https://www.example.com"],
  "config": {
    "max_sessions_per_day": 1000,
    "max_messages_per_session": 100,
    "max_voice_minutes": 0
  }
}

Use in Embed

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

Key Security Features

Feature	Description
Origin Restrictions	Only allows embedding from specified domains
Session Quotas	Limit daily sessions to control costs
Message Limits	Cap messages per session
Voice Minutes	Limit voice interaction time

JavaScript SDK

For deeper integration, use the JavaScript SDK directly:

Installation

npm install @thinnestai/embed-sdk

Basic Usage

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

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

// Open the chat widget
agent.open();

// Close the chat widget
agent.close();

// Toggle open/close
agent.toggle();

// Send a message programmatically
agent.sendMessage('Hello, I need help with my order');

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

agent.on('open', () => {
  console.log('Chat opened');
});

agent.on('close', () => {
  console.log('Chat closed');
});

SDK Methods

Method	Description
`open()`	Open the chat widget
`close()`	Close the chat widget
`toggle()`	Toggle the widget open/close state
`sendMessage(text)`	Send a message to the agent
`on(event, callback)`	Subscribe to widget events
`destroy()`	Remove the widget from the page
`setUser(userId)`	Set the 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

Agent API Keys

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

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

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

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",
    "session_id": "sess_789"
  }'

Styling & Customization

CSS Overrides

The widget uses Shadow DOM for isolation, but you can customize key elements via 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 id="my-chat-button" onclick="agent.toggle()">
  Chat with us
</button>

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

Local testing — Use localhost as an allowed origin during development.
Preview in dashboard — Click Test Chat on your agent's page.
Test HTML file — Create a minimal HTML file with the embed script.

<!DOCTYPE html>
<html>
<head><title>Widget Test</title></head>
<body>
  <h1>Testing My Agent</h1>
  <script
    src="https://app.thinnest.ai/embed.js"
    data-agent-id="agent_abc123"
    data-welcome-message="Hi! This is a test."
    async
  ></script>
</body>
</html>

Best Practices

Use publishable keys in production — Don't expose agent IDs directly; use keys with origin restrictions.
Set session and message limits — Prevent abuse and control costs.
Add a welcome message — A greeting message increases engagement.
Match your brand — Customize colors and positioning to blend with your site.
Test on mobile — The widget is responsive, but verify it works well on your specific mobile layout.
Monitor usage — Track widget sessions in your analytics dashboard.