Skip to main content

Initialization

The ChatBox SDK can be initialized in multiple ways depending on your needs.

Constructor​

new ChatBoxSDK(config)

Creates a new ChatBox instance with the specified configuration.

Parameters​

ParameterTypeRequiredDescription
configObjectYesConfiguration object

Configuration Object​

interface ChatBoxConfig {
  // Required
  apiKey: string;

  // Optional - Widget Behavior
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  autoOpen?: boolean;
  flowId?: string;

  // Optional - Theming
  theme?: {
    primaryColor?: string;
    fontFamily?: string;
    borderRadius?: string;
    mode?: 'light' | 'dark' | 'auto';
  };

  // Optional - Context
  context?: Record<string, any>;

  // Optional - Advanced
  debug?: boolean;
  locale?: string;
}

Basic Initialization​

Minimal setup with just an API key:

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

With Custom Position​

Control where the chat widget appears:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    position: 'bottom-left'  // Options: bottom-right, bottom-left, top-right, top-left
});

With Theming​

Customize the widget appearance to match your brand:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    theme: {
        primaryColor: '#0066FF',      // Your brand color
        fontFamily: 'Inter, sans-serif',  // Your font
        borderRadius: '16px',          // Rounded corners
        mode: 'auto'                   // Respects user's system preference
    }
});

With Context Variables​

Pass user data and page context:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    context: {
        // User information
        userId: '12345',
        userName: 'John Doe',
        userEmail: 'john@example.com',

        // Business data
        cartTotal: 149.99,
        cartItems: 3,

        // Page context
        pageUrl: window.location.href,
        referrer: document.referrer
    }
});

With Specific Flow​

Start a specific conversational flow:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    flowId: 'flow_12345'  // Get this from Design Studio
});
tip

If you don't specify a flowId, the SDK will auto-select the best flow based on URL patterns and context rules configured in your Design Studio.

Auto-Open Widget​

Automatically open the chat widget on page load:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    autoOpen: true  // Widget opens immediately
});

Debug Mode​

Enable console logging for troubleshooting:

const chatbox = new ChatBoxSDK({
    apiKey: 'YOUR_API_KEY',
    debug: true  // Logs SDK activity to console
});

Complete Example​

Full configuration with all options:

const chatbox = new ChatBoxSDK({
    // Required
    apiKey: 'YOUR_API_KEY',

    // Widget behavior
    position: 'bottom-right',
    autoOpen: false,
    flowId: 'flow_12345',

    // Theming
    theme: {
        primaryColor: '#0066FF',
        fontFamily: 'Inter, system-ui, sans-serif',
        borderRadius: '12px',
        mode: 'auto'
    },

    // Context
    context: {
        userId: getCurrentUserId(),
        userName: getCurrentUserName(),
        pageType: 'product',
        productId: '12345'
    },

    // Advanced
    debug: process.env.NODE_ENV === 'development',
    locale: 'en-US'
});

Script Tag Initialization​

When using the script tag method, configuration is passed via data attributes:

<script
    src="https://cdn.dialogkit.io/chatbox-sdk.min.js"
    data-api-key="YOUR_API_KEY"
    data-position="bottom-right"
    data-theme="dark"
    data-auto-open="true"
    data-flow-id="flow_12345"
></script>

Getting Your API Key​

  1. Go to Design Studio
  2. Navigate to Settings > API Keys
  3. Click Generate New Key
  4. Copy and use in your integration
Security
  • Never commit API keys to version control
  • Use environment variables in production
  • Rotate keys periodically
  • Each key is tied to one organization

Next Steps​