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

Need help with configuration? Check our examples or contact support.