Skip to main content

​
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

  1. Open your agent in the thinnestAI dashboard
  2. Go to the Deploy tab
  3. Select Web Widget and switch to the Embed Code tab
  4. 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:
AttributeTypeDefaultDescription
data-publishable-keystringRequiredYour publishable widget key
data-agent-idstringRequiredYour agent’s public ID
data-widget-typestring"chat"Widget type: "chat", "voice", or "combined"
data-api-urlstring—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

FeatureDescription
Origin RestrictionsWidget only loads on specified domains

​
Lead Capture

Collect user information before they start chatting.

​
Enable Lead Capture

  1. Go to your agent’s Deploy tab
  2. Open Web Embed settings
  3. Enable Lead Collection
  4. Add fields: email, phone, name, company, or custom fields
  5. 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

MethodDescription
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);
});
EventDescription
thinnestai.session.startedNew session initialized
thinnestai.message.sentUser sent a message
thinnestai.message.receivedAgent response received
thinnestai.call.startedVoice call started
thinnestai.call.endedVoice call ended
thinnestai.errorError occurred
thinnestai.openedWidget opened
thinnestai.closedWidget closed
thinnestai.lead.capturedLead 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

  1. Locally — Add localhost to your widget key’s allowed origins.
  2. Dashboard — Use the Test Chat feature on your agent page.
  3. 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.