Configuration
Customize the Koi Widget to perfectly match your brand and requirements. This guide covers all available configuration options and how to use them.
Basic Configuration
Configure the widget by setting window.KoiWidgetConfig
before loading the script:
1<script>
2 window.KoiWidgetConfig = {
3 primaryColor: '#2563eb',
4 accentColor: '#7c3aed',
5 position: 'bottom-right'
6 };
7</script>
8<script src="https://widget.koi.im/v1.js"></script>
9
Configuration Options
Appearance
primaryColor
- Type:
string
- Default:
'#2563eb'
- Description: Main brand color for buttons, headers, and accents
primaryColor: '#ff6b6b' // Custom red color
accentColor
- Type:
string
- Default:
'#7c3aed'
- Description: Secondary color for highlights and interactive elements
accentColor: '#4ecdc4' // Teal accent color
backgroundColor
- Type:
string
- Default:
'#ffffff'
- Description: Background color of the chat interface
backgroundColor: '#f8fafc' // Light gray background
textColor
- Type:
string
- Default:
'#1f2937'
- Description: Primary text color
textColor: '#2d3748' // Dark gray text
Positioning
position
- Type:
'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
- Default:
'bottom-right'
- Description: Widget position on the page
position: 'bottom-left' // Position on bottom-left
offset
- Type:
{ x: number, y: number }
- Default:
{ x: 20, y: 20 }
- Description: Offset from the edge in pixels
offset: { x: 30, y: 50 } // 30px from side, 50px from bottom/top
zIndex
- Type:
number
- Default:
9999
- Description: CSS z-index for the widget
zIndex: 10000 // Higher z-index
Behavior
autoOpenDelay
- Type:
number | null
- Default:
null
- Description: Auto-open delay in milliseconds (null = disabled)
autoOpenDelay: 5000 // Auto-open after 5 seconds
enableFileUpload
- Type:
boolean
- Default:
true
- Description: Enable file upload functionality
enableFileUpload: false // Disable file uploads
enableEmojis
- Type:
boolean
- Default:
true
- Description: Enable emoji picker
enableEmojis: false // Disable emoji picker
showQuickActions
- Type:
boolean
- Default:
true
- Description: Show quick action buttons
showQuickActions: false // Hide quick actions
enableTypingIndicator
- Type:
boolean
- Default:
true
- Description: Show typing indicators
enableTypingIndicator: false // Disable typing indicators
Content & Messaging
welcomeMessage
- Type:
string
- Default:
'Hi! How can I help you today?'
- Description: Initial welcome message
welcomeMessage: 'Welcome to our support chat! What can we help you with?'
placeholderText
- Type:
string
- Default:
'Type your message...'
- Description: Input placeholder text
placeholderText: 'Ask us anything...'
quickActions
- Type:
Array<{ label: string, message: string }>
- Default:
[...]
- Description: Quick action buttons
1quickActions: [
2 { label: 'Get Pricing', message: 'I would like to know about your pricing plans' },
3 { label: 'Book Demo', message: 'I would like to schedule a demo' },
4 { label: 'Technical Support', message: 'I need technical support' }
5]
6
API & Integration
apiBaseUrl
- Type:
string
- Default:
'https://api.koi.im'
- Description: Base URL for API requests
apiBaseUrl: 'https://your-api.example.com'
apiKey
- Type:
string
- Default:
undefined
- Description: API key for authentication
apiKey: 'your-api-key-here'
userId
- Type:
string
- Default:
undefined
- Description: Unique user identifier
userId: 'user-123'
sessionId
- Type:
string
- Default:
undefined
- Description: Session identifier
sessionId: 'session-abc-123'
Advanced Options
customCSS
- Type:
string
- Default:
''
- Description: Custom CSS to inject
1customCSS: `
2 .koi-widget-button {
3 border-radius: 50% !important;
4 }
5 .koi-widget-header {
6 background: linear-gradient(45deg, #ff6b6b, #4ecdc4) !important;
7 }
8`
9
enableSounds
- Type:
boolean
- Default:
true
- Description: Enable notification sounds
enableSounds: false // Disable sounds
maxFileSize
- Type:
number
- Default:
10485760
(10MB) - Description: Maximum file upload size in bytes
maxFileSize: 5242880 // 5MB limit
allowedFileTypes
- Type:
string[]
- Default:
['image/*', 'application/pdf', 'text/*']
- Description: Allowed file MIME types
allowedFileTypes: ['image/*', 'application/pdf'] // Only images and PDFs
Complete Configuration Example
Here's a comprehensive configuration example:
1<script>
2 window.KoiWidgetConfig = {
3 // Appearance
4 primaryColor: '#2563eb',
5 accentColor: '#7c3aed',
6 backgroundColor: '#ffffff',
7 textColor: '#1f2937',
8
9 // Positioning
10 position: 'bottom-right',
11 offset: { x: 20, y: 20 },
12 zIndex: 9999,
13
14 // Behavior
15 autoOpenDelay: null,
16 enableFileUpload: true,
17 enableEmojis: true,
18 showQuickActions: true,
19 enableTypingIndicator: true,
20 enableSounds: true,
21
22 // Content
23 welcomeMessage: 'Hi! How can I help you today?',
24 placeholderText: 'Type your message...',
25 quickActions: [
26 { label: 'Get Pricing', message: 'What are your pricing plans?' },
27 { label: 'Book Demo', message: 'I would like to schedule a demo' },
28 { label: 'Support', message: 'I need technical support' }
29 ],
30
31 // API
32 apiBaseUrl: 'https://api.koi.im',
33 apiKey: 'your-api-key',
34 userId: 'user-123',
35
36 // Advanced
37 maxFileSize: 10485760, // 10MB
38 allowedFileTypes: ['image/*', 'application/pdf', 'text/*'],
39 customCSS: `
40 .koi-widget-button {
41 box-shadow: 0 4px 20px rgba(37, 99, 235, 0.3);
42 }
43 `
44 };
45</script>
46<script src="https://widget.koi.im/v1.js"></script>
47
Runtime Configuration
You can also update configuration after the widget loads:
1// Update colors
2KoiWidget.configure({
3 primaryColor: '#ff6b6b',
4 accentColor: '#4ecdc4'
5});
6
7// Update welcome message
8KoiWidget.setWelcomeMessage('Welcome back! How can we help?');
9
10// Update quick actions
11KoiWidget.setQuickActions([
12 { label: 'New Action', message: 'This is a new quick action' }
13]);
14
Environment-Specific Configuration
Development
1window.KoiWidgetConfig = {
2 apiBaseUrl: 'http://localhost:3000/api',
3 enableSounds: false, // Disable sounds during development
4 autoOpenDelay: 1000 // Quick auto-open for testing
5};
6
Production
1window.KoiWidgetConfig = {
2 apiBaseUrl: 'https://api.yoursite.com',
3 enableSounds: true,
4 autoOpenDelay: null // No auto-open in production
5};
6
Validation
The widget validates configuration options and will log warnings for invalid values:
1// This will show a warning and use default
2window.KoiWidgetConfig = {
3 position: 'invalid-position', // Warning: invalid position
4 primaryColor: 'not-a-color', // Warning: invalid color
5 maxFileSize: -1 // Warning: invalid file size
6};
7
Next Steps
- API Reference - Learn about programmatic control
- Styling Guide - Advanced customization with CSS
- Examples - See real-world configurations
- Troubleshooting - Common configuration issues
Need help with configuration? Check our examples or contact support.