Skip to main content

Installation

Get the DialogKit ChatBox SDK running on your website in just a few minutes.

Prerequisites​

Before you begin, you'll need:

  • A DialogKit account (sign up at app.dialogkit.io)
  • An API key from your Design Studio
  • A published conversational flow

The simplest way to add ChatBox SDK to your site is with a single script tag:

<script
    src="https://cdn.dialogkit.io/chatbox-sdk.min.js"
    data-api-key="YOUR_API_KEY"
></script>

Place this script tag just before the closing </body> tag in your HTML.

Script Tag Attributes​

Customize the widget behavior using data attributes:

AttributeRequiredDescriptionDefault
data-api-keyYesYour API key from Design Studio-
data-positionNoWidget position on screenbottom-right
data-themeNoColor themelight
data-flow-idNoSpecific flow to startAuto-selected

Example with Customization​

<script
    src="https://cdn.dialogkit.io/chatbox-sdk.min.js"
    data-api-key="YOUR_API_KEY"
    data-position="bottom-left"
    data-theme="dark"
></script>

JavaScript Method​

For more control, initialize the SDK programmatically:

// Load the SDK script
const script = document.createElement('script');
script.src = 'https://cdn.dialogkit.io/chatbox-sdk.min.js';
document.head.appendChild(script);

// Wait for SDK to load, then initialize
script.onload = () => {
    const chatbox = new ChatBoxSDK({
        apiKey: 'YOUR_API_KEY',
        position: 'bottom-right',
        theme: {
            primaryColor: '#0066FF',
            fontFamily: 'Inter, sans-serif'
        },
        context: {
            userId: '12345',
            userName: 'John Doe'
        }
    });

    // Optional: Listen to events
    chatbox.on('ready', () => {
        console.log('ChatBox is ready');
    });

    chatbox.on('message', (data) => {
        console.log('Message sent:', data);
    });
};

NPM Method​

If you're using a build tool like Webpack or Vite:

npm install @dialogkit/chatbox-sdk
import ChatBoxSDK from '@dialogkit/chatbox-sdk';
import '@dialogkit/chatbox-sdk/dist/styles.css';

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY'
});
note

The NPM package is coming soon. For now, use the CDN method.

Getting Your API Key​

  1. Log in to Design Studio
  2. Navigate to Settings > API Keys
  3. Click Generate New Key
  4. Copy your API key
Security

Never commit API keys to version control. Use environment variables in production:

apiKey: process.env.DIALOGKIT_API_KEY

Verifying Installation​

After adding the script, you should see:

  1. A chat bubble appearing in the bottom-right (or your specified position)
  2. Clicking the bubble opens your conversational flow
  3. The widget is responsive and works on mobile devices

Troubleshooting​

Widget Not Appearing​

Check browser console for errors:

  • API key invalid → Verify key in Design Studio
  • Flow not published → Publish at least one flow
  • CORS errors → Contact support

Performance Issues​

Optimize loading:

  • Place script tag at end of <body>
  • Use async attribute for non-blocking load
  • Ensure your flow is optimized (avoid large images)

Browser Compatibility​

The ChatBox SDK supports:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Next Steps​