Configuration

Learn how to configure the Chatoshi SDK with all available options and customization settings.

Configuration

The Chatoshi SDK offers extensive configuration options to customize the crypto assistant chat experience for your specific needs.

Basic Configuration

The minimal configuration requires only partnerKey:

const chat = new Chatoshi({
  partnerKey: 'your-partner-key'
});

Complete Configuration Options

Core Options

interface ChatoshiInitOptions {
  // Required
  partnerKey: string;
  
  // Optional
  container?: HTMLElement | string;
  containerStyle?: Record<string, string | number>;
  containerClass?: string | string[];
  mode?: 'default' | 'full' | 'popup' | 'drawer';
  theme?: 'light' | 'dark' | 'system';
  popupOptions?: PopupOptions;
  drawerOptions?: DrawerOptions;
  splashScreen?: boolean | { customHTML?: string | HTMLElement; };
  colors?: IColorOptions | { default?: IColorOptions; dark?: IColorOptions; };
  customLogo?: string | { dark: string; light: string };
}

Display Modes

Default Mode

Embeds the chat directly into a container element.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  container: '#chat-container',
  mode: 'default'
});

Shows chat in a floating popup with a toggle button.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'popup',
  popupOptions: {
    width: '400px',
    height: '600px',
    position: 'bottom-right',
    customToggleButton: '#my-custom-button'
  }
});

Drawer Mode

Displays chat as a slide-in panel from the side.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'drawer',
  drawerOptions: {
    width: '350px',
    position: 'right'
  }
});

Full Mode

Takes over the entire screen for an immersive experience.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'full'
});

interface PopupOptions {
  width?: string;           // Default: '400px'
  height?: string;          // Default: '600px'
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  customToggleButton?: string | HTMLElement;
  containerClass?: string | string[];
}

Custom size and position:

popupOptions: {
  width: '500px',
  height: '700px',
  position: 'bottom-left'
}

Custom toggle button:

popupOptions: {
  customToggleButton: document.getElementById('help-button')
  // or
  customToggleButton: '#help-button'
}

Drawer Options

interface DrawerOptions {
  width?: string;           // Default: '400px'
  position?: 'left' | 'right';  // Default: 'right'
  closeButtonDisabled?: boolean; // NEW: disables the close button if true
  containerClass?: string | string[];
}

New Option:

  • closeButtonDisabled?: boolean — Set to true to hide/disable the close button in the drawer UI. Default is false (close button is shown).

Drawer Examples

Left-side drawer:

drawerOptions: {
  width: '300px',
  position: 'left'
}

Drawer with close button disabled:

drawerOptions: {
  width: '350px',
  position: 'right',
  closeButtonDisabled: true
}

Styling and Theming

Theme Options

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  theme: 'dark' // 'light', 'dark', or 'system'
});

Custom Colors

You can customize colors in two ways:

Single Color Scheme

Apply the same colors to both light and dark modes:

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  colors: {
    primary: '#3b82f6',
    secondary: '#64748b',
    background: '#ffffff',
    border: '#e2e8f0',
    text: '#1e293b',
    ring: '#3b82f6'
  }
});

Separate Light and Dark Color Schemes

Define different colors for light and dark modes:

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  colors: {
    default: {
      primary: '#3b82f6',
      secondary: '#64748b',
      background: '#ffffff',
      border: '#e2e8f0',
      text: '#1e293b',
      ring: '#3b82f6'
    },
    dark: {
      primary: '#60a5fa',
      secondary: '#94a3b8',
      background: '#0f172a',
      border: '#334155',
      text: '#f1f5f9',
      ring: '#60a5fa'
    }
  }
});

Add your own logo that will appear in the chat interface:

Use the same logo for both light and dark themes:

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  customLogo: 'https://example.com/logo.png' // PNG, SVG, or JPG
});

Theme-Specific Logos

Use different logos for light and dark themes:

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  customLogo: {
    light: 'https://example.com/logo-light.png',
    dark: 'https://example.com/logo-dark.png'
  }
});

Splash Screen

Control the splash screen behavior:

// Disable splash screen
const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  splashScreen: false
});

// Enable with custom HTML
const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  splashScreen: {
    customHTML: '<div class="custom-splash">Loading Crypto Assistant...</div>'
  }
});

Custom Container Styling

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  container: '#chat-container',
  containerStyle: {
    borderRadius: '12px',
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
    border: '1px solid #e1e5e9'
  },
  containerClass: ['custom-chat', 'rounded-lg']
});

Advanced Configuration Examples

Crypto Trading Platform Integration

const cryptoChat = new Chatoshi({
  partnerKey: 'crypto-platform-key',
  mode: 'popup',
  theme: 'dark',
  popupOptions: {
    width: '450px',
    height: '650px',
    position: 'bottom-right'
  },
  colors: {
    default: {
      primary: '#f59e0b',
      secondary: '#6b7280',
      background: '#ffffff',
      border: '#e5e7eb',
      text: '#111827'
    },
    dark: {
      primary: '#fbbf24',
      secondary: '#9ca3af',
      background: '#1f2937',
      border: '#374151',
      text: '#f9fafb'
    }
  },
  customLogo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png'
  }
});

Mobile-First Crypto Assistant

const mobileChat = new Chatoshi({
  partnerKey: 'mobile-crypto-key',
  mode: 'drawer',
  theme: 'system',
  drawerOptions: {
    width: '100%',
    position: 'right'
  },
  colors: {
    primary: '#10b981',
    secondary: '#6b7280',
    background: '#f9fafb',
    text: '#111827'
  }
});

Full-Screen Crypto Analysis Experience

const analysisChat = new Chatoshi({
  partnerKey: 'analysis-platform-key',
  mode: 'full',
  theme: 'dark',
  colors: {
    primary: '#8b5cf6',
    secondary: '#6b7280',
    background: '#0f172a',
    border: '#1e293b',
    text: '#f1f5f9'
  },
  customLogo: 'https://example.com/analysis-logo.svg',
  splashScreen: {
    customHTML: '<div class="loading-spinner">Initializing AI Crypto Assistant...</div>'
  }
});

Configuration Validation

The SDK automatically validates your configuration and will throw helpful errors:

// ❌ This will throw an error
const chat = new Chatoshi({
  // Missing partnerKey
  container: '#chat'
});
// Error: Partner Key is required for Chatoshi initialization

// ❌ This will throw an error  
const chat = new Chatoshi({
  partnerKey: 'partner-123',
  mode: 'default'
  // Missing container for default mode
});
// Error: Container is required for Chatoshi initialization

Environment-Specific Configuration

Development

const chat = new Chatoshi({
  partnerKey: 'dev-partner-key',
  container: '#chat-container',
  theme: 'light'
});

Production

const chat = new Chatoshi({
  partnerKey: process.env.CHATOSHI_PARTNER_KEY,
  container: '#chat-container',
  mode: 'popup',
  theme: 'system',
  colors: {
    primary: '#your-brand-color',
    background: '#ffffff'
  },
  customLogo: 'https://yourdomain.com/logo.png'
});

Next Steps