Configuration

Everything is configured through one object passed to new Chatoshi(). Only partnerKey is required:

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

This gives you a popup with sensible defaults. Everything below is optional.

All options

interface ChatoshiInitOptions {
  partnerKey: string;
  container?: HTMLElement | string;
  containerStyle?: Record<string, string | number>;
  containerClass?: string | string[];
  mode?: 'default' | 'full' | 'popup' | 'drawer' | 'core';
  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 };
  customView?: boolean;
  transparent?: boolean;
  preset?: string;
}

About customView

If your partner account has branding configured in the portal (theme, logo), those portal values normally win over the ones passed in code. Set customView: true to flip that and always use your local values.

This option exists mostly for the widget builder preview. Unless you know you need it, leave it out.

Popup options

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

Defaults: 400px wide, 600px tall, bottom-right corner.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'popup',
  popupOptions: {
    width: '500px',
    height: '700px',
    position: 'bottom-left'
  }
});

To use your own button instead of the built-in toggle:

popupOptions: {
  customToggleButton: '#help-button'
}

Drawer options

interface DrawerOptions {
  width?: string;
  position?: 'left' | 'right';
  closeButtonDisabled?: boolean;
  containerClass?: string | string[];
  resizable?: boolean;
  resizeOptions?: {
    minWidth?: number;
    maxWidth?: number;
  };
  transparent?: boolean;
}

Defaults: 400px wide, right side, resizable. The width a user drags to is remembered for their next visit.

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'drawer',
  drawerOptions: {
    width: '350px',
    position: 'right',
    resizable: true,
    resizeOptions: { minWidth: 300, maxWidth: 600 }
  }
});

Set closeButtonDisabled: true to remove the close button from the drawer header, useful when you control closing yourself with chat.close().

On mobile, a full-width drawer usually feels best:

drawerOptions: {
  width: '100%',
  position: 'right'
}

Styling

Theme

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

system follows the user's OS preference.

Colors

One scheme for both themes:

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

Or separate schemes for light and dark:

colors: {
  default: {
    primary: '#3b82f6',
    background: '#ffffff',
    text: '#1e293b'
  },
  dark: {
    primary: '#60a5fa',
    background: '#0f172a',
    text: '#f1f5f9'
  }
}

All fields are optional; set only what you want to change.

Logo

customLogo: 'https://example.com/logo.png'

Different logos per theme:

customLogo: {
  light: 'https://example.com/logo-light.png',
  dark: 'https://example.com/logo-dark.png'
}

PNG, SVG, or JPG all work.

Transparent background

const chat = new Chatoshi({
  partnerKey: 'your-partner-key',
  mode: 'drawer',
  transparent: true,
  drawerOptions: { transparent: true }
});

The iframe and widget backgrounds become transparent, so your page shows through. In drawer mode, drawerOptions.transparent controls the panel itself.

Splash screen

By default a loading spinner shows inside the chat area until the app is ready. Disable it:

splashScreen: false

Or replace it with your own markup:

splashScreen: {
  customHTML: '<div class="my-splash">Loading…</div>'
}

Container styling

For default mode, style the element that hosts the chat:

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

Putting it together

const chat = new Chatoshi({
  partnerKey: process.env.CHATOSHI_PARTNER_KEY,
  mode: 'popup',
  theme: 'system',
  popupOptions: {
    width: '420px',
    height: '640px',
    position: 'bottom-right'
  },
  colors: {
    default: { primary: '#f59e0b', background: '#ffffff', text: '#111827' },
    dark: { primary: '#fbbf24', background: '#1f2937', text: '#f9fafb' }
  },
  customLogo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png'
  }
});

Keep the partner key out of source control. Load it from an environment variable or fetch it from your backend.

Validation

The constructor validates its input and throws with a clear message:

new Chatoshi({ container: '#chat' });
// Error: Partner Key is required for Chatoshi initialization

new Chatoshi({ partnerKey: 'pk', mode: 'default' });
// Error: Container is required for Chatoshi initialization

Where to go next

• Display modes: what each mode looks like and when to use it
• Event handling: react to messages and lifecycle events
• API reference: methods, events, and types