Examples

Real-world examples and use cases for implementing the Koi Widget in different scenarios.

Basic Implementation

Simple Website Integration

The most basic implementation for a standard website:

1<!DOCTYPE html>
2<html lang="en">
3<head>
4    <meta charset="UTF-8">
5    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6    <title>My Website</title>
7</head>
8<body>
9    <h1>Welcome to My Website</h1>
10    <p>Your website content here...</p>
11    
12    <!-- Koi Widget -->
13    <script>
14        window.KoiWidgetConfig = {
15            primaryColor: '#2563eb',
16            welcomeMessage: 'Hi! How can we help you today?'
17        };
18    </script>
19    <script src="https://widget.koi.im/v1.js"></script>
20</body>
21</html>
22

E-commerce Integration

Online Store with Customer Support

Perfect for e-commerce sites with product-specific support:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#059669', // Green for e-commerce
4        accentColor: '#0d9488',
5        welcomeMessage: 'Need help with your order? We\'re here to assist!',
6        quickActions: [
7            { label: 'Track Order', message: 'I want to track my order' },
8            { label: 'Return Item', message: 'I need to return an item' },
9            { label: 'Product Question', message: 'I have a question about a product' },
10            { label: 'Shipping Info', message: 'I need shipping information' }
11        ],
12        enableFileUpload: true // For order screenshots
13    };
14</script>
15<script src="https://widget.koi.im/v1.js"></script>
16
17<script>
18    // Pass product context when user is viewing a product
19    if (window.location.pathname.includes('/product/')) {
20        KoiWidget.on('ready', () => {
21            const productId = getProductIdFromUrl();
22            const productName = getProductName();
23            
24            KoiWidget.setUser({
25                metadata: {
26                    currentProduct: productId,
27                    productName: productName,
28                    page: 'product'
29                }
30            });
31        });
32    }
33</script>
34

SaaS Application

Software as a Service Platform

For SaaS platforms with user authentication and context:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#7c3aed', // Purple for SaaS
4        accentColor: '#8b5cf6',
5        position: 'bottom-right',
6        welcomeMessage: 'Hi there! Need help with your account?',
7        quickActions: [
8            { label: 'Billing Question', message: 'I have a billing question' },
9            { label: 'Feature Request', message: 'I\'d like to request a feature' },
10            { label: 'Technical Issue', message: 'I\'m experiencing a technical issue' },
11            { label: 'Account Settings', message: 'I need help with account settings' }
12        ],
13        enableFileUpload: true,
14        enableEmojis: true
15    };
16</script>
17<script src="https://widget.koi.im/v1.js"></script>
18
19<script>
20    // Set user context for authenticated users
21    document.addEventListener('DOMContentLoaded', () => {
22        const user = getCurrentUser(); // Your user data
23        
24        if (user) {
25            KoiWidget.on('ready', () => {
26                KoiWidget.setUser({
27                    id: user.id,
28                    name: user.name,
29                    email: user.email,
30                    avatar: user.avatar,
31                    metadata: {
32                        plan: user.subscription.plan,
33                        signupDate: user.createdAt,
34                        lastLogin: user.lastLogin,
35                        accountType: user.accountType
36                    }
37                });
38                
39                // Auto-open for new users
40                if (isNewUser(user)) {
41                    setTimeout(() => {
42                        KoiWidget.open();
43                        KoiWidget.sendMessage('Welcome to our platform! I\'m here to help you get started. Do you have any questions?', {
44                            sender: 'bot'
45                        });
46                    }, 3000);
47                }
48            });
49        }
50    });
51</script>
52

Educational Platform

Online Learning Platform

For educational websites with course-specific support:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#dc2626', // Red for education
4        accentColor: '#ef4444',
5        welcomeMessage: 'Need help with your studies? Ask me anything!',
6        quickActions: [
7            { label: 'Course Help', message: 'I need help with my current course' },
8            { label: 'Technical Issue', message: 'I\'m having technical difficulties' },
9            { label: 'Assignment Question', message: 'I have a question about an assignment' },
10            { label: 'Enrollment', message: 'I want to enroll in a course' }
11        ],
12        enableFileUpload: true, // For assignment uploads
13        autoOpenDelay: null // Don't auto-open during study sessions
14    };
15</script>
16<script src="https://widget.koi.im/v1.js"></script>
17
18<script>
19    KoiWidget.on('ready', () => {
20        // Set course context
21        const courseId = getCurrentCourseId();
22        const lessonId = getCurrentLessonId();
23        
24        if (courseId) {
25            KoiWidget.setUser({
26                metadata: {
27                    currentCourse: courseId,
28                    currentLesson: lessonId,
29                    studentLevel: getStudentLevel(),
30                    enrollmentDate: getEnrollmentDate()
31                }
32            });
33        }
34        
35        // Add course-specific quick actions
36        if (courseId) {
37            KoiWidget.addQuickAction({
38                label: 'Course Materials',
39                message: `I need help finding materials for ${getCourseName()}`
40            });
41        }
42    });
43</script>
44

Healthcare Platform

Medical Practice Website

For healthcare websites with appointment booking and patient support:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#0ea5e9', // Blue for healthcare
4        accentColor: '#0284c7',
5        welcomeMessage: 'How can we help you with your healthcare needs today?',
6        quickActions: [
7            { label: 'Book Appointment', message: 'I\'d like to book an appointment' },
8            { label: 'Prescription Refill', message: 'I need a prescription refill' },
9            { label: 'Test Results', message: 'I\'m looking for my test results' },
10            { label: 'Insurance Question', message: 'I have an insurance question' }
11        ],
12        enableFileUpload: true, // For medical documents
13        enableEmojis: false, // Professional tone
14        customCSS: `
15            .koi-widget-button {
16                box-shadow: 0 4px 12px rgba(14, 165, 233, 0.3);
17            }
18        `
19    };
20</script>
21<script src="https://widget.koi.im/v1.js"></script>
22
23<script>
24    // HIPAA compliance considerations
25    KoiWidget.on('ready', () => {
26        // Show privacy notice
27        KoiWidget.sendMessage('Please note: For your privacy and security, do not share sensitive medical information in this chat. For urgent medical needs, please call our office directly.', {
28            sender: 'system'
29        });
30    });
31</script>
32

Real Estate Platform

Property Listing Website

For real estate websites with property-specific inquiries:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#059669', // Green for real estate
4        accentColor: '#0d9488',
5        welcomeMessage: 'Interested in a property? Let\'s find your dream home!',
6        quickActions: [
7            { label: 'Schedule Viewing', message: 'I\'d like to schedule a property viewing' },
8            { label: 'Mortgage Info', message: 'I need information about mortgages' },
9            { label: 'Property Details', message: 'I have questions about this property' },
10            { label: 'Market Analysis', message: 'I want a market analysis' }
11        ],
12        position: 'bottom-left', // Different position
13        enableFileUpload: true
14    };
15</script>
16<script src="https://widget.koi.im/v1.js"></script>
17
18<script>
19    // Property-specific context
20    KoiWidget.on('ready', () => {
21        const propertyId = getPropertyIdFromUrl();
22        
23        if (propertyId) {
24            const property = getPropertyDetails(propertyId);
25            
26            KoiWidget.setUser({
27                metadata: {
28                    viewingProperty: propertyId,
29                    propertyAddress: property.address,
30                    propertyPrice: property.price,
31                    propertyType: property.type
32                }
33            });
34            
35            // Add property-specific quick action
36            KoiWidget.addQuickAction({
37                label: 'About This Property',
38                message: `I have questions about the property at ${property.address}`
39            });
40        }
41    });
42</script>
43

Multi-language Support

International Website

For websites serving multiple languages:

1<script>
2    // Detect user language
3    const userLang = navigator.language || navigator.userLanguage;
4    const lang = userLang.startsWith('es') ? 'es' : 
5                 userLang.startsWith('fr') ? 'fr' : 'en';
6    
7    const messages = {
8        en: {
9            welcome: 'Hi! How can I help you today?',
10            placeholder: 'Type your message...',
11            quickActions: [
12                { label: 'Get Support', message: 'I need support' },
13                { label: 'Sales Question', message: 'I have a sales question' },
14                { label: 'Technical Help', message: 'I need technical help' }
15            ]
16        },
17        es: {
18            welcome: '¡Hola! ¿Cómo puedo ayudarte hoy?',
19            placeholder: 'Escribe tu mensaje...',
20            quickActions: [
21                { label: 'Obtener Soporte', message: 'Necesito soporte' },
22                { label: 'Pregunta de Ventas', message: 'Tengo una pregunta de ventas' },
23                { label: 'Ayuda Técnica', message: 'Necesito ayuda técnica' }
24            ]
25        },
26        fr: {
27            welcome: 'Salut! Comment puis-je vous aider aujourd\'hui?',
28            placeholder: 'Tapez votre message...',
29            quickActions: [
30                { label: 'Obtenir de l\'aide', message: 'J\'ai besoin d\'aide' },
31                { label: 'Question de vente', message: 'J\'ai une question de vente' },
32                { label: 'Aide technique', message: 'J\'ai besoin d\'aide technique' }
33            ]
34        }
35    };
36    
37    window.KoiWidgetConfig = {
38        primaryColor: '#6366f1',
39        welcomeMessage: messages[lang].welcome,
40        placeholderText: messages[lang].placeholder,
41        quickActions: messages[lang].quickActions,
42        apiBaseUrl: `https://api.koi.im/${lang}` // Language-specific API
43    };
44</script>
45<script src="https://widget.koi.im/v1.js"></script>
46

Advanced Analytics Integration

Website with Comprehensive Tracking

For websites that need detailed analytics and user behavior tracking:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#8b5cf6',
4        accentColor: '#a78bfa',
5        welcomeMessage: 'Hi! How can we help you today?',
6        enableFileUpload: true,
7        enableEmojis: true
8    };
9</script>
10<script src="https://widget.koi.im/v1.js"></script>
11
12<script>
13    // Comprehensive analytics tracking
14    KoiWidget.on('ready', () => {
15        // Track widget load
16        gtag('event', 'widget_loaded', {
17            event_category: 'chat',
18            event_label: 'koi_widget'
19        });
20    });
21    
22    KoiWidget.on('open', () => {
23        // Track widget opens
24        gtag('event', 'widget_opened', {
25            event_category: 'chat',
26            event_label: 'user_interaction'
27        });
28        
29        // Facebook Pixel
30        fbq('track', 'Contact');
31        
32        // Mixpanel
33        mixpanel.track('Chat Widget Opened', {
34            page: window.location.pathname,
35            timestamp: new Date()
36        });
37    });
38    
39    KoiWidget.on('message', (message) => {
40        // Track messages
41        gtag('event', 'message_sent', {
42            event_category: 'chat',
43            event_label: 'user_message',
44            value: message.text.length
45        });
46        
47        // Track message sentiment (if available)
48        if (message.sentiment) {
49            gtag('event', 'message_sentiment', {
50                event_category: 'chat',
51                event_label: message.sentiment
52            });
53        }
54    });
55    
56    KoiWidget.on('quickAction', (action) => {
57        // Track quick action usage
58        gtag('event', 'quick_action_clicked', {
59            event_category: 'chat',
60            event_label: action.label
61        });
62    });
63    
64    KoiWidget.on('fileUpload', (file) => {
65        // Track file uploads
66        gtag('event', 'file_uploaded', {
67            event_category: 'chat',
68            event_label: file.type,
69            value: file.size
70        });
71    });
72</script>
73

Custom Styling Examples

Branded Widget Appearance

Complete custom styling to match your brand:

1<script>
2    window.KoiWidgetConfig = {
3        primaryColor: '#ff6b6b',
4        accentColor: '#4ecdc4',
5        backgroundColor: '#f8f9fa',
6        textColor: '#2d3748',
7        customCSS: `
8            /* Custom button styling */
9            .koi-widget-button {
10                background: linear-gradient(135deg, #ff6b6b 0%, #4ecdc4 100%) !important;
11                border-radius: 50% !important;
12                box-shadow: 0 8px 25px rgba(255, 107, 107, 0.3) !important;
13                transition: all 0.3s ease !important;
14            }
15            
16            .koi-widget-button:hover {
17                transform: scale(1.1) !important;
18                box-shadow: 0 12px 35px rgba(255, 107, 107, 0.4) !important;
19            }
20            
21            /* Custom header styling */
22            .koi-widget-header {
23                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
24                border-radius: 20px 20px 0 0 !important;
25            }
26            
27            /* Custom message bubbles */
28            .koi-widget-message.user {
29                background: linear-gradient(135deg, #ff6b6b 0%, #ff8e8e 100%) !important;
30                border-radius: 20px 20px 5px 20px !important;
31            }
32            
33            .koi-widget-message.bot {
34                background: linear-gradient(135deg, #4ecdc4 0%, #6ee7db 100%) !important;
35                border-radius: 20px 20px 20px 5px !important;
36            }
37            
38            /* Custom input styling */
39            .koi-widget-input {
40                border-radius: 25px !important;
41                border: 2px solid #e2e8f0 !important;
42                padding: 12px 20px !important;
43            }
44            
45            .koi-widget-input:focus {
46                border-color: #ff6b6b !important;
47                box-shadow: 0 0 0 3px rgba(255, 107, 107, 0.1) !important;
48            }
49            
50            /* Custom quick action buttons */
51            .koi-widget-quick-action {
52                background: rgba(255, 107, 107, 0.1) !important;
53                border: 1px solid rgba(255, 107, 107, 0.3) !important;
54                border-radius: 20px !important;
55                transition: all 0.2s ease !important;
56            }
57            
58            .koi-widget-quick-action:hover {
59                background: rgba(255, 107, 107, 0.2) !important;
60                transform: translateY(-2px) !important;
61            }
62        `
63    };
64</script>
65<script src="https://widget.koi.im/v1.js"></script>
66

Testing and Development

Development Environment Setup

For testing and development:

1<script>
2    // Development configuration
3    const isDevelopment = window.location.hostname === 'localhost';
4    
5    window.KoiWidgetConfig = {
6        primaryColor: '#2563eb',
7        accentColor: '#7c3aed',
8        apiBaseUrl: isDevelopment ? 'http://localhost:3000/api' : 'https://api.koi.im',
9        enableSounds: !isDevelopment, // Disable sounds in development
10        autoOpenDelay: isDevelopment ? 2000 : null, // Quick open for testing
11        welcomeMessage: isDevelopment ? 
12            'Development Mode - Widget is ready for testing!' : 
13            'Hi! How can I help you today?',
14        quickActions: isDevelopment ? [
15            { label: 'Test Message', message: 'This is a test message' },
16            { label: 'Test File Upload', message: 'Testing file upload functionality' },
17            { label: 'Test Error', message: 'trigger_error' } // For error testing
18        ] : [
19            { label: 'Get Support', message: 'I need support' },
20            { label: 'Sales Question', message: 'I have a sales question' }
21        ]
22    };
23</script>
24<script src="https://widget.koi.im/v1.js"></script>
25
26<script>
27    if (isDevelopment) {
28        // Development-only features
29        KoiWidget.on('ready', () => {
30            console.log('Koi Widget loaded in development mode');
31            
32            // Add development tools
33            window.koiDebug = {
34                openWidget: () => KoiWidget.open(),
35                closeWidget: () => KoiWidget.close(),
36                sendTestMessage: (msg) => KoiWidget.sendMessage(msg || 'Test message'),
37                getConfig: () => KoiWidget.getConfig(),
38                getMessages: () => KoiWidget.getMessages()
39            };
40            
41            console.log('Debug tools available at window.koiDebug');
42        });
43        
44        // Log all events in development
45        ['open', 'close', 'message', 'quickAction', 'error'].forEach(event => {
46            KoiWidget.on(event, (data) => {
47                console.log(`[Koi Widget] ${event}:`, data);
48            });
49        });
50    }
51</script>
52

Performance Optimization

Lazy Loading Implementation

For optimal performance with conditional loading:

1<script>
2    // Only load widget when user shows interest
3    let widgetLoaded = false;
4    
5    function loadKoiWidget() {
6        if (widgetLoaded) return;
7        
8        widgetLoaded = true;
9        
10        // Set configuration
11        window.KoiWidgetConfig = {
12            primaryColor: '#2563eb',
13            accentColor: '#7c3aed',
14            welcomeMessage: 'Thanks for your interest! How can we help?'
15        };
16        
17        // Load widget script
18        const script = document.createElement('script');
19        script.src = 'https://widget.koi.im/v1.js';
20        script.async = true;
21        document.head.appendChild(script);
22    }
23    
24    // Load widget on user interaction
25    document.addEventListener('scroll', () => {
26        if (window.scrollY > 1000) { // After scrolling 1000px
27            loadKoiWidget();
28        }
29    }, { once: true });
30    
31    // Load widget on mouse movement (user is active)
32    document.addEventListener('mousemove', loadKoiWidget, { once: true });
33    
34    // Load widget after 10 seconds
35    setTimeout(loadKoiWidget, 10000);
36    
37    // Load widget on specific button click
38    document.getElementById('contact-btn')?.addEventListener('click', loadKoiWidget);
39</script>
40

These examples should give you a solid foundation for implementing the Koi Widget in various scenarios. For more specific use cases or custom implementations, contact our support team.