Skip to main content

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

​
Widget Configuration

​
Script Tag Attributes

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.

​
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

FeatureDescription
Origin RestrictionsOnly 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

MethodDescription
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);
});
EventDescription
thinnestai.session.startedNew session initialized
thinnestai.session.restoredExisting session restored
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

​
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

​
Testing Your Widget

  1. Local testing — Add localhost as an allowed origin for your widget key.
  2. Preview in dashboard — Click Test Chat on your agent’s page.
  3. 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.