Web Widget

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://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 chat bubble to the bottom-right corner of your page.

Finding Your Agent ID & Key

Open your agent in the thinnestAI dashboard
Go to the Deploy tab
Select Web Widget and switch to the Embed Code tab
Copy the generated snippet containing your data-publishable-key and data-agent-id

Configuration Options

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

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.

Full Example

<script
  src="https://api.thinnest.ai/embed/widget.js"
  data-publishable-key="pk_live_abc123xyz"
  data-agent-id="ag_pub_xyz789"
  data-widget-type="chat"
  data-api-url="https://api.thinnest.ai"
  async
></script>

Publishable Keys (Production)

For production deployments, you must use publishable keys. Keys add origin restrictions to prevent others from using your widget on unauthorized websites.

Create a Key

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

Key Security Features

Feature	Description
Origin Restrictions	Widget only loads on specified domains

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

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

JavaScript SDK

For deeper integration, use the SDK programmatically:

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();

// 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 programmatically
`startVoice()`	Starts a voice session (if voice is enabled)
`newChat()`	Starts a new chat session
`destroy()`	Remove the widget from the DOM

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

Styling and Customization

Widget customization is done entirely through the Agent Studio Deploy Panel → Design tab, not CSS variables or script tags. This leverages an isolated Shadow DOM. Options you can configure in the dashboard include:

Colors (primary, background, text, header, bubbles, input)
Font family and Border radius
Dark/light mode
Avatar URL
Glassmorphism effect
Custom launcher icons and popover messages

Testing

Locally — Add localhost to your widget key’s allowed origins.
Dashboard — Use the Test Chat feature on your agent page.
Test file — Create a minimal HTML page with the embed script pointing to your agent.

Best Practices

Restrict origins — Only add trusted domains to your publishable key’s allowed_origins.
Add a welcome message to increase engagement (configurable in the dashboard).
Match your brand colors and position using the Design tab.
Test on mobile to verify the widget’s responsive behavior fits your site.

Overview

Chat Channels

Voice Channels

Web Widget

Quick Setup

Finding Your Agent ID & Key

Configuration Options

Full Example

Publishable Keys (Production)

Create a Key

Key Security Features

Lead Capture

Enable Lead Capture

JavaScript SDK

SDK Methods

SDK Events

Styling and Customization

Testing

Best Practices

​Web Widget

​Quick Setup

​Finding Your Agent ID & Key

​Configuration Options

​Full Example

​Publishable Keys (Production)

​Create a Key

​Key Security Features

​Lead Capture

​Enable Lead Capture

​JavaScript SDK

​SDK Methods

​SDK Events

​Styling and Customization

​Testing

​Best Practices

Web Widget

Quick Setup

Finding Your Agent ID & Key

Configuration Options

Full Example

Publishable Keys (Production)

Create a Key

Key Security Features

Lead Capture

Enable Lead Capture

JavaScript SDK

SDK Methods

SDK Events

Styling and Customization

Testing

Best Practices