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;
}
| Option | What it does |
|---|---|
| partnerKey | Your partner key from the Chatoshi team. Required. |
| container | Element or selector the chat embeds into. Required in default mode. |
| containerStyle, containerClass | Inline styles and CSS classes applied to the container. |
| mode | Where the chat renders: default, popup, drawer, full, or core. See Display modes. |
| theme | light, dark, or system. |
| popupOptions | Size, position, and toggle button for popup mode. |
| drawerOptions | Width, side, resizing, and close button for drawer mode. |
| splashScreen | Loading screen shown until the chat is ready. false disables it, custom HTML replaces it. |
| colors | Brand colors: one scheme, or separate schemes for light and dark mode. |
| customLogo | Your logo in the chat UI. One URL, or different logos for light and dark. |
| transparent | Transparent widget backgrounds, so your page shows through. |
| preset | Server-side UI preset identifier, if one is configured for your account. |
| customView | Makes the theme, colors, and customLogo from these options take precedence over portal settings. |
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