Overview

This SDK lets you embed our chat / conversational interface on any digital property. Unlike traditional chat widgets that force a specific design or position, our SDK follows a headless philosophy: you control where the chat appears, how it looks, and when it opens. We just provide the chat interface itself.

This approach gives you complete flexibility to integrate chat in ways that make sense for your users—whether that's inline in a help page, in a modal dialog, as a slide-out panel, or the traditional floating launcher.

Core Philosophy

You own the UX, we provide the chat.

✅ Embed chat anywhere: inline, modal, sidebar, full page
✅ Style it to match your brand
✅ Control when and how it opens
✅ Integrate with your existing UI patterns
❌ No forced design decisions
❌ No fighting with default styles
❌ No "works everywhere except your use case"

Two Integration Modes

Headless (Recommended) You provide a container, we fill it with chat. Total control over placement and behavior.

Managed (Optional) We create a default floating launcher button for you. Quick setup, standard experience.

Quick Start

Get your chatbot live on your website in under 5 minutes.

1. Get Your API Key

Log in to your dashboard at https://dashboard.yourcompany.com and navigate to Settings → SDK Integration to find your API key.

2. Add a Container

Add an HTML element where you want the chat to appear:

<!-- This can be anywhere: modal, sidebar, inline, full page --> <div id="chat-widget"></div>

3. Initialize the SDK

Add this before the closing </body> tag:

<script>   window.YourChatbotConfig = {     apiKey: 'YOUR_API_KEY_HERE',     container: '#chat-widget'   }; </script> <script src="https://cdn.yourcompany.com/chatbot-sdk.js" async></script>

4. Trigger It Your Way

The SDK loads asynchronously. Wait for it to be ready before calling methods:

<button id="chat-btn">Chat with Support</button>  <script>   // Wait for SDK to be ready   YourChatbot.on('ready', function() {     document.getElementById('chat-btn').onclick = function() {       YourChatbot.open();     };   }); </script>

That's It!

You control where the chat appears, when it opens, and how it looks. We just provide the chat interface.

Note: Only one chatbot instance is supported per page. Multiple instances will cause conflicts.

Installation

Headless Mode (Recommended)

You control where and how the chat appears.

<!-- 1. Create a container where you want chat --> <div id="chat-widget" style="height: 600px;"></div>  <!-- 2. Initialize SDK --> <script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget'   }; </script> <script src="https://cdn.yourcompany.com/chatbot-sdk.js" async></script>  <!-- 3. Trigger it however you want (wait for ready) --> <button id="help-btn">Get Help</button> <script>   YourChatbot.on('ready', function() {     document.getElementById('help-btn').onclick = function() {       YourChatbot.open();     };   }); </script>

Managed Mode (Optional)

We create a default floating launcher for you. Great for quick testing and validation.

<script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     showLauncher: true   }; </script> <script src="https://cdn.yourcompany.com/chatbot-sdk.js" async></script>

Note: This is perfect for quickly validating your integration before building custom UI.

Configuration Options

Option	Type	Default	Description
`apiKey`	string	required	Your public API key
`container`	string	-	CSS selector (e.g., `'#chat-widget'`)
`autoOpen`	boolean	`false`	Render chat immediately
`language`	string	`'en'`	Language code: `'en'`, `'es'`, `'fr'`
`showLauncher`	boolean	`false`	Show default floating launcher

Launcher Options

Only applies if showLauncher: true:

Option	Type	Default	Description
`launcher.position`	string	`'bottom-right'`	Position on screen
`launcher.icon`	string	`'💬'`	Icon or emoji
`launcher.backgroundColor`	string	`'#0066cc'`	Background color (hex)

Positions: 'bottom-right' or 'bottom-left'

Examples

Headless with container:

window.YourChatbotConfig = {   apiKey: 'pub_xxx',   container: '#chat-widget',   autoOpen: true };

With launcher:

window.YourChatbotConfig = {   apiKey: 'pub_xxx',   showLauncher: true,   launcher: {     position: 'bottom-right',     backgroundColor: '#7C3AED'   } };

Common Integration Patterns

Inline Chat

Embed chat directly in your page content.

<div class="help-section">   <h2>Need Help?</h2>   <div id="chat-widget" style="height: 600px; max-width: 800px;"></div> </div>  <script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget',     autoOpen: true   }; </script>

Best for: Help pages, contact pages, support sections

Modal/Popup

Open chat in a modal when user clicks a trigger.

<button id="help-btn">Chat Support</button>  <div id="modal" style="display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.5); z-index: 9999;">   <div style="width: 90%; max-width: 600px; height: 80%; margin: 5% auto; background: white; border-radius: 8px; padding: 20px;">     <button onclick="closeModal()" style="float: right;">&times;</button>     <div id="chat-widget" style="height: calc(100% - 40px);"></div>   </div> </div>  <script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget'   };      YourChatbot.on('ready', function() {     document.getElementById('help-btn').onclick = function() {       document.getElementById('modal').style.display = 'block';       YourChatbot.open();     };   });      function closeModal() {     document.getElementById('modal').style.display = 'none';   } </script>

Best for: Minimal UI impact, mobile-friendly, maintaining page context

Sidebar/Slide-out

Chat slides in from the side.

<button onclick="toggleChat()">Support</button>  <div id="sidebar" style="position: fixed; right: -400px; top: 0; width: 400px; height: 100%; background: white; box-shadow: -2px 0 10px rgba(0,0,0,0.1); transition: right 0.3s; z-index: 9999;">   <button onclick="toggleChat()" style="position: absolute; left: 10px; top: 10px;">Close</button>   <div id="chat-widget" style="height: 100%; padding-top: 50px;"></div> </div>  <script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget'   };      let chatOpened = false;      // Setup ready handler once   YourChatbot.on('ready', function() {     // SDK is ready   });      function toggleChat() {     const sidebar = document.getElementById('sidebar');     const isOpen = sidebar.style.right === '0px';     sidebar.style.right = isOpen ? '-400px' : '0px';          if (!isOpen && !chatOpened) {       YourChatbot.open();       chatOpened = true;     }   } </script>

Best for: Desktop apps, dashboards, keeping chat accessible

Default Floating Launcher

Quick setup with standard bottom-right launcher.

<script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     showLauncher: true,     launcher: {       position: 'bottom-right',       backgroundColor: '#0066cc'     }   }; </script> <script src="https://cdn.yourcompany.com/chatbot-sdk.js" async></script>

Best for: Marketing sites, quick implementation, standard use cases

SPA & Framework Integration

React Example

This example assumes you've added the SDK script tag once in your index.html or root layout.

import React, { useEffect, useRef, useState } from 'react';  function ChatWidget() {   const chatContainerRef = useRef(null);   const [isReady, setIsReady] = useState(false);    useEffect(() => {     // Configure SDK once     window.YourChatbotConfig = {       apiKey: 'pub_1234567890abcdef',       container: '#chat-widget'     };      // Listen for ready event     if (window.YourChatbot) {       window.YourChatbot.on('ready', () => {         setIsReady(true);       });     }   }, []);    const handleOpenChat = () => {     if (isReady) {       window.YourChatbot.open();     }   };    return (     <div>       <button onClick={handleOpenChat} disabled={!isReady}>         Chat Support       </button>       <div          id="chat-widget"          ref={chatContainerRef}         style={{ height: '600px', maxWidth: '800px' }}       />     </div>   ); }  export default ChatWidget;

Key points for SPAs:

Load SDK script once in your HTML (e.g., index.html), not in React
Configure via window.YourChatbotConfig in your component
Use the 'ready' event to know when SDK is initialized
The SDK persists across route changes
Only initialize once per session

User Identification

Anonymous Users (Default)

By default, all visitors chat anonymously. No configuration needed.

Identify Logged-In Users

Pass user information when you know who they are:

<script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget',     user: {       userId: 'user_12345',       email: 'john@example.com',       name: 'John Doe',       customFields: {         plan: 'enterprise',         accountValue: 5000       }     }   }; </script>

Dynamic Identification

If user logs in after page load:

YourChatbot.on('ready', function() {   YourChatbot.identify({     userId: 'user_12345',     email: 'john@example.com',     name: 'John Doe'   }); });

Secure Identification

For verified identity, generate an HMAC hash on your server. Use a stable userId (e.g., your internal user primary key) when creating the hash. When userHash is present, the SDK treats the identity as verified and will not allow untrusted clients to impersonate another userId.

// Server-side (Node.js) const crypto = require('crypto'); const userHash = crypto   .createHmac('sha256', 'YOUR_SECRET_KEY')   .update('user_12345')   .digest('hex');

<!-- Client-side --> <script>   window.YourChatbotConfig = {     apiKey: 'pub_1234567890abcdef',     container: '#chat-widget',     user: {       userId: 'user_12345',       userHash: '8f7a3b2c1d...',       email: 'john@example.com'     }   }; </script>

Programmatic API

Important: Wait for Ready

The SDK loads asynchronously. Always wait for the 'ready' event before calling methods:

YourChatbot.on('ready', function() {   // Now safe to call SDK methods   YourChatbot.open(); });

Methods

// Render chat in container YourChatbot.open();  // Send a message programmatically YourChatbot.sendMessage('Hello!');  // Identify the user YourChatbot.identify({   userId: 'user_123',   email: 'user@example.com' });  // Update user properties YourChatbot.update({   customFields: { plan: 'enterprise' } });  // Clear user session YourChatbot.logout();

Events

// SDK ready (must wait for this before calling methods) YourChatbot.on('ready', function() {   console.log('SDK is ready'); });  // User sent a message YourChatbot.on('message', function(msg) {   console.log('Message sent:', msg); });  // Conversation started YourChatbot.on('conversationStart', function() {   console.log('New conversation'); });  // Agent responded YourChatbot.on('agentResponse', function(response) {   console.log('Agent replied:', response); });

Common Examples

Open chat with pre-filled message:

YourChatbot.on('ready', function() {   document.getElementById('billing-help').onclick = function() {     YourChatbot.open();     YourChatbot.sendMessage('I need help with billing');   }; });

Track engagement in analytics:

YourChatbot.on('conversationStart', function() {   gtag('event', 'chat_started'); });

Pass user context on login:

function onUserLogin(user) {   YourChatbot.on('ready', function() {     YourChatbot.identify({       userId: user.id,       email: user.email,       customFields: { plan: user.plan }     });   }); }

Note: Only one chatbot instance per page is supported. Do not initialize the SDK multiple times.

Domain Whitelisting

For security, your SDK only works on authorized domains.

Adding Domains

Go to your dashboard: https://dashboard.yourcompany.com
Navigate to Settings → SDK Integration
Click Add Domain
Enter your domain (e.g., example.com)
Click Save

Domain Format

✅ example.com - Allows example.com and all subdomains
✅ www.example.com - Allows only www.example.com
❌ https://example.com - Don't include protocol
❌ example.com/path - Don't include paths

Note: localhost is automatically whitelisted for development.

Styling & Layout

Since you control the container, you control the appearance:

<!-- Size and position --> <div id="chat-widget" style="   width: 100%;   height: 600px;   max-width: 800px;   margin: 0 auto;   border-radius: 12px;   box-shadow: 0 4px 20px rgba(0,0,0,0.1); "></div>  <!-- Mobile responsive --> <style>   #chat-widget {     height: 600px;   }      @media (max-width: 768px) {     #chat-widget {       position: fixed;       top: 0;       left: 0;       width: 100%;       height: 100%;       z-index: 9999;     }   } </style>

Custom Triggers

Use any element to open chat (remember to wait for 'ready'):

<button id="help-btn">Get Help</button>  <script>   YourChatbot.on('ready', function() {     document.getElementById('help-btn').onclick = function() {       YourChatbot.open();     };   }); </script>

Customizing Default Launcher

If using showLauncher: true:

window.YourChatbotConfig = {   apiKey: 'pub_xxx',   showLauncher: true,   launcher: {     icon: '💬',     backgroundColor: '#7C3AED',     position: 'bottom-right'   } };

Or override with CSS:

#chatbot-launcher {   background: linear-gradient(135deg, #667eea, #764ba2) !important;   width: 70px !important;   height: 70px !important; }

Troubleshooting

Chat Not Appearing

1. Check if container exists:

<div id="chat-widget"></div>  <!-- Must exist before SDK loads -->

2. Check if script loaded:

Open DevTools (F12) → Network tab
Look for chatbot-sdk.js with status 200

3. Check domain whitelist:

Open Console (F12)
Look for "Domain not authorized" error
Add domain in dashboard settings

4. Verify API key:

Copy fresh from dashboard
Check for typos or extra spaces

Container Issues

Container has zero height:

<div id="chat-widget" style="height: 600px;"></div>

SDK not ready when calling methods:

// ❌ Wrong - may fail if SDK not loaded yet YourChatbot.open();  // ✅ Correct - wait for ready event YourChatbot.on('ready', function() {   YourChatbot.open(); });

Content Security Policy (CSP)

If you have CSP, add these directives:

Content-Security-Policy:   script-src 'self' https://cdn.yourcompany.com;   frame-src https://chat.yourcompany.com;   connect-src https://api.yourcompany.com;

Note: If the chat interface serves assets (images, fonts, styles) from additional domains (e.g., CDN for avatars or fonts), also add those to img-src, style-src, and font-src as needed.

Multiple Instances

Do not include the SDK snippet more than once per page. Only one instance is supported.

Browser Support

The SDK supports all modern browsers:

✅ Chrome 90+
✅ Firefox 88+
✅ Safari 14+
✅ Edge 90+
✅ Mobile browsers (iOS Safari, Chrome Mobile)
⚠️ IE11 not supported

Security

HTTPS Required

The SDK only works on HTTPS websites (or localhost for development).

API Keys

Public keys (pub_xxx) are safe to expose in browser
Secret keys are never used in frontend code
Rotate keys in dashboard if compromised

User Data

All data transmitted over TLS
User identification hashes prevent impersonation
No sensitive data stored in browser localStorage

SDK Documentatie