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:

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

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

<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

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

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

npm install @thinnest-ai/widget-sdk

Access the widget programmatically via window.ThinnestAI:

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

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:

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

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

Local testing — Add localhost as an allowed origin for your widget key.
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://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.

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Embed Widget & SDK

Quick Setup

Widget Configuration

Script Tag Attributes

Example: Full Configuration

Publishable Keys

Create a Publishable Key

Response

Key Security Features

JavaScript SDK

Installation

SDK Methods

SDK Events

Agent API Keys

Styling & Customization

Testing Your Widget

Best Practices

​Embed Widget & SDK

​Quick Setup

​Widget Configuration

​Script Tag Attributes

​Example: Full Configuration

​Publishable Keys

​Create a Publishable Key

​Response

​Key Security Features

​JavaScript SDK

​Installation

​SDK Methods

​SDK Events

​Agent API Keys

​Styling & Customization

​Testing Your Widget

​Best Practices

Embed Widget & SDK

Quick Setup

Widget Configuration

Script Tag Attributes

Example: Full Configuration

Publishable Keys

Create a Publishable Key

Response

Key Security Features

JavaScript SDK

Installation

SDK Methods

SDK Events

Agent API Keys

Styling & Customization

Testing Your Widget

Best Practices