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>
22E-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>
34SaaS 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>
52Educational 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>
44Healthcare 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>
32Real 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>
43Multi-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>
46Advanced 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>
73Custom 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>
66Testing 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>
52Performance 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>
40These 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.