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.
-
Download the widget files:
curl -O https://widget.koi.im/v1.js curl -O https://widget.koi.im/v1.css
-
Upload to your server (e.g.,
/assets/js/
directory) -
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:
- Check for the chat button in the bottom-right corner (or your configured position)
- Click the button to open the chat interface
- Send a test message to ensure connectivity
- 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
-
Via Plugin (Recommended):
- Install the "Koi Widget" plugin from the WordPress repository
- Configure in Settings → Koi Widget
-
Manual Installation:
- Add the script tag to your theme's
footer.php
file - Or use a plugin like "Insert Headers and Footers"
- Add the script tag to your theme's
Shopify
- Go to Online Store → Themes
- Click Actions → Edit code
- Open
theme.liquid
- Add the script before
</body>
Squarespace
- Go to Settings → Advanced → Code Injection
- Add the script to the Footer section
Wix
- Go to Settings → Custom Code
- Click Add Custom Code
- Paste the script and set it to load on All Pages
Troubleshooting Installation
Widget Not Appearing
- Check browser console for JavaScript errors
- Verify script URL is accessible
- Check CSP settings if applicable
- Ensure no ad blockers are interfering
Styling Issues
- Check for CSS conflicts with your site's styles
- Verify CSS file is loading correctly
- 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:
- Configure the widget to match your brand
- Set up API endpoints for custom functionality
- Customize the appearance with CSS
- Test different scenarios with our examples
Having trouble with installation? Check our troubleshooting guide or contact support.