Installation Guide

Get the Koi Widget up and running on your website in minutes. Choose the installation method that best fits your setup.

Quick Start (Recommended)

The fastest way to add Koi Widget to your website is with our CDN-hosted script:

<script src="https://widget.koi.im/v1.js"></script>

Add this single line to your HTML <head> or before the closing </body> tag, and the widget will automatically initialize with default settings.

Installation Methods

Method 1: CDN Integration

Perfect for most websites, blogs, and static sites.

1<!DOCTYPE html>
2<html>
3<head>
4    <title>Your Website</title>
5    <!-- Other head content -->
6</head>
7<body>
8    <!-- Your website content -->
9    
10    <!-- Koi Widget - Add before closing body tag -->
11    <script src="https://widget.koi.im/v1.js"></script>
12</body>
13</html>
14

Method 2: Self-Hosted

Download and host the widget files on your own server for maximum control.

  1. Download the widget files:

    curl -O https://widget.koi.im/v1.js
curl -O https://widget.koi.im/v1.css

  2. Upload to your server (e.g., /assets/js/ directory)

  3. Include in your HTML:

    <link rel="stylesheet" href="/assets/css/koi-widget.css">
<script src="/assets/js/koi-widget.js"></script>

Method 3: NPM Package

For modern JavaScript applications and build systems.

npm install @koi/widget

Then import and initialize:

1import KoiWidget from '@koi/widget';
2import '@koi/widget/dist/style.css';
3
4// Initialize the widget
5KoiWidget.init({
6    // Configuration options
7});
8

Method 4: React Component

For React applications, use our dedicated React component:

npm install @koi/react-widget

1import { KoiWidget } from '@koi/react-widget';
2
3function App() {
4    return (
5        <div>
6            {/* Your app content */}
7            <KoiWidget 
8                primaryColor="#2563eb"
9                position="bottom-right"
10            />
11        </div>
12    );
13}
14

Configuration During Installation

You can configure the widget before it loads by setting global configuration:

1<script>
2    // Configure before loading the widget
3    window.KoiWidgetConfig = {
4        primaryColor: '#your-brand-color',
5        accentColor: '#your-accent-color',
6        position: 'bottom-right',
7        apiBaseUrl: 'https://your-api.com',
8        enableFileUpload: true,
9        enableEmojis: true,
10        showQuickActions: true,
11        autoOpenDelay: null // Set to milliseconds for auto-open
12    };
13</script>
14<script src="https://widget.koi.im/v1.js"></script>
15

Verification

After installation, verify the widget is working:

  1. Check for the chat button in the bottom-right corner (or your configured position)
  2. Click the button to open the chat interface
  3. Send a test message to ensure connectivity
  4. Check browser console for any error messages

Content Security Policy (CSP)

If your site uses CSP headers, add these directives:

script-src 'self' https://widget.koi.im;
connect-src 'self' https://api.koi.im wss://ws.koi.im;
img-src 'self' data: https://widget.koi.im;
style-src 'self' 'unsafe-inline' https://widget.koi.im;

Framework-Specific Guides

WordPress

  1. Via Plugin (Recommended):

    • Install the "Koi Widget" plugin from the WordPress repository
    • Configure in Settings → Koi Widget

  2. Manual Installation:

    • Add the script tag to your theme's footer.php file
    • Or use a plugin like "Insert Headers and Footers"

Shopify

  1. Go to Online Store → Themes
  2. Click Actions → Edit code
  3. Open theme.liquid
  4. Add the script before </body>

Squarespace

  1. Go to Settings → Advanced → Code Injection
  2. Add the script to the Footer section

Wix

  1. Go to Settings → Custom Code
  2. Click Add Custom Code
  3. Paste the script and set it to load on All Pages

Troubleshooting Installation

Widget Not Appearing

  1. Check browser console for JavaScript errors
  2. Verify script URL is accessible
  3. Check CSP settings if applicable
  4. Ensure no ad blockers are interfering

Styling Issues

  1. Check for CSS conflicts with your site's styles
  2. Verify CSS file is loading correctly
  3. Use browser dev tools to inspect widget elements

Performance Considerations

  • The widget loads asynchronously and won't block page rendering
  • Total size: ~50KB gzipped (JS + CSS)
  • Lazy loading of additional features when needed
  • CDN delivery for optimal performance worldwide

Next Steps

Once installed, you'll want to:

  1. Configure the widget to match your brand
  2. Set up API endpoints for custom functionality
  3. Customize the appearance with CSS
  4. Test different scenarios with our examples

Having trouble with installation? Check our troubleshooting guide or contact support.