@paperlinkai/chat
Version:
PaperLink AI Chat Widget - Easy integration for any website
402 lines (313 loc) • 11.1 kB
Markdown
# 🤖 PaperLink Chat
[](https://badge.fury.io/js/@paperlink%2Fchat)
[](https://opensource.org/licenses/MIT)
**Easy-to-integrate AI chat widget for any website**
Add an intelligent chat assistant to your website in under 60 seconds. Built with modern web technologies, optimized for performance, and designed for seamless integration.
## ✨ Features
- 🚀 **Lightning fast** - 63KB total bundle size
- 📱 **Mobile responsive** - Works perfectly on all devices
- 🎨 **Fully customizable** - Colors, position, size, and behavior
- 🔒 **Privacy focused** - Shadow DOM isolation, no conflicts
- 🌐 **Universal** - Works with any website or framework
- 📦 **Zero dependencies** - Self-contained and optimized
- 🛡️ **TypeScript support** - Full type definitions included
## 🚀 Quick Start
### Option 1: CDN (Easiest)
Add these two lines to your website:
```html
<!-- Add to <head> -->
<link
rel="stylesheet"
href="https://unpkg.com/@paperlink/chat@latest/dist/style.css"
/>
<!-- Add before closing </body> -->
<script src="https://unpkg.com/@paperlink/chat@latest/dist/chat.min.js"></script>
<script>
PaperlinkChat.init({
apiKey: "your-api-key-here",
title: "AI Assistant",
greeting: "Hi! How can I help you today?",
});
</script>
```
### Option 2: NPM Install
```bash
npm install @paperlink/chat
```
```javascript
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";
Chat.init({
apiKey: "your-api-key-here",
title: "AI Assistant",
});
```
## 📋 Configuration
### Basic Configuration
```javascript
PaperlinkChat.init({
// Required
apiKey: "your-organization-api-key",
// Optional
title: "Customer Support",
greeting: "How can we help you today?",
placeholder: "Type your message...",
position: "bottom-right", // 'bottom-left', 'top-right', 'top-left'
width: 384,
height: 600,
autoOpen: false,
debug: false,
});
```
### Theme Customization
```javascript
PaperlinkChat.init({
apiKey: "your-api-key",
theme: {
primaryColor: "#2563eb",
backgroundColor: "#ffffff",
textColor: "#1f2937",
userMessageColor: "#2563eb",
botMessageColor: "#f3f4f6",
borderColor: "#e5e7eb",
},
});
```
### Custom Icons
Customize the widget icons with your own branding:
```javascript
PaperlinkChat.init({
apiKey: "your-api-key",
customIcons: {
bot: "https://your-domain.com/bot-icon.svg",
send: "https://your-domain.com/send-icon.svg",
minimize: "https://your-domain.com/minimize-icon.svg",
chatButton: "https://your-domain.com/chat-button-icon.svg",
},
});
```
**Icon Requirements:**
- **Formats**: SVG, PNG, JPG, WebP
- **Size**: Recommended 24x24px or 32x32px
- **URL**: Must be publicly accessible HTTPS URLs
- **CORS**: Icons must allow cross-origin requests
- **Fallback**: Default Material Icons used if custom icons fail to load
- **Validation**: Icons are validated for dimensions and CORS headers
- **Caching**: Successfully loaded icons are cached for the session
- **Error Handling**: Detailed error logging for debugging
**Icon Types:**
- `bot` - Bot avatar in messages and typing indicator
- `send` - Send button in message input
- `minimize` - Minimize button in chat header
- `scrollDown` - Scroll to bottom button (when chat is scrolled up)
- `chatButton` - Chat button that opens/expands the widget
### Chat Button Customization
Customize the appearance of the chat button that opens your widget:
```javascript
PaperlinkChat.init({
apiKey: "your-api-key",
// Custom background color
chatButtonBackgroundColor: "#10b981", // Any valid CSS color
// Hide background circle (icon only)
showChatButtonBackground: false,
// Custom chat button icon
customIcons: {
chatButton: "https://your-domain.com/chat-icon.svg",
},
});
```
**Chat Button Options:**
- **Background Color**: Use any valid CSS color (hex, rgb, rgba, named colors)
- **Background Visibility**: Show or hide the circular background
- **Custom Icon**: Replace the default chat bubble with your own icon
- **Hover Effects**: Automatic darker shade on hover for custom colors
**⚠️ Important**:
- `showChatButtonBackground: false` hides only the background circle - the icon remains visible for user interaction
- `showChatButton: false` completely hides the entire button - you'll need an alternative way for users to open the chat (e.g., programmatically via `widget.open()`)
This design ensures users can always access the widget while giving you complete control over appearance.
### All Options
| Parameter | Type | Default | Description |
| --------------------------- | --------- | ------------------------- | --------------------------------------- |
| `apiKey` | `string` | **Required** | Your PaperLink organization API key |
| `title` | `string` | "AI Assistant" | Widget header title |
| `greeting` | `string` | "Hi! How can I help you?" | Initial greeting message |
| `placeholder` | `string` | "Type your message..." | Input field placeholder |
| `position` | `string` | "bottom-right" | Widget position on screen |
| `width` | `number` | 384 | Widget width in pixels |
| `height` | `number` | 600 | Widget height in pixels |
| `autoOpen` | `boolean` | false | Auto-open widget on page load |
| `debug` | `boolean` | false | Enable debug mode (mock API) |
| `maxMessages` | `number` | 50 | Maximum messages to store |
| `customIcons` | `object` | {} | Custom icon URLs for branding |
| `chatButtonBackgroundColor` | `string` | undefined | Custom background color for chat button |
| `showChatButtonBackground` | `boolean` | true | Show/hide chat button background circle (icon remains visible) |
| `showChatButton` | `boolean` | true | Show/hide entire chat button (complete control) |
## 🎯 Framework Integration
### React
```jsx
import { useEffect } from "react";
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";
export default function App() {
useEffect(() => {
const widget = Chat.init({
apiKey: "your-api-key",
title: "Support Chat",
});
return () => {
// Cleanup on unmount
widget.destroy();
};
}, []);
return <div>Your app content</div>;
}
```
### Vue.js
```vue
<template>
<div>Your app content</div>
</template>
<script>
import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";
export default {
mounted() {
this.widget = Chat.init({
apiKey: "your-api-key",
title: "Vue Chat",
});
},
beforeUnmount() {
if (this.widget) {
this.widget.destroy();
}
},
};
</script>
```
### Next.js
```jsx
import { useEffect } from "react";
import dynamic from "next/dynamic";
// Dynamically import to avoid SSR issues
const Chat = dynamic(() => import("@paperlink/chat"), {
ssr: false,
});
export default function Layout({ children }) {
useEffect(() => {
import("@paperlink/chat/dist/style.css");
import("@paperlink/chat").then((Chat) => {
Chat.default.init({
apiKey: "your-api-key",
});
});
}, []);
return <div>{children}</div>;
}
```
### WordPress
Add to your theme's `functions.php`:
```php
function add_paperlink_widget() {
wp_enqueue_style('paperlink-chat', 'https://unpkg.com/@paperlink/chat/dist/style.css');
wp_enqueue_script('paperlink-chat', 'https://unpkg.com/@paperlink/chat/dist/chat.min.js', array(), null, true);
wp_add_inline_script('paperlink-chat', '
PaperlinkChat.init({
apiKey: "your-api-key",
title: "Support Chat"
});
');
}
add_action('wp_enqueue_scripts', 'add_paperlink_widget');
```
## 🔧 Programmatic Control
```javascript
// Initialize widget
const widget = PaperlinkChat.init({
apiKey: "your-api-key",
autoOpen: false,
});
// Control methods
widget.open(); // Open the widget
widget.close(); // Close the widget
widget.destroy(); // Remove widget completely
widget.updateConfig({
// Update configuration
title: "New Title",
theme: { primaryColor: "#red" },
});
// Get current state
const config = widget.getConfig();
```
## 🛠️ Troubleshooting
### Widget not appearing?
- Check browser console for errors
- Verify your API key is correct
- Ensure CSS file is loaded before JavaScript
- Check for Content Security Policy restrictions
### Styling conflicts?
- Widget uses Shadow DOM for style isolation
- All styles are prefixed and contained
- No external CSS should affect the widget
### Performance concerns?
- Widget is optimized for minimal impact
- Total size: ~73KB (JS + CSS combined)
- Loads asynchronously after page content
- Uses efficient bundling and tree-shaking
## 📱 Browser Support
- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 12+
- ✅ Edge 79+
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
## 🔒 Security
- 🛡️ **Shadow DOM isolation** - No CSS/JS conflicts
- 🔐 **HTTPS only** - All communications encrypted
- 🚫 **No tracking** - Privacy-focused design
- ✅ **CSP compatible** - Works with strict security policies
## 🎨 Customization Examples
### Dark Theme
```javascript
PaperlinkChat.init({
apiKey: "your-api-key",
theme: {
primaryColor: "#8b5cf6",
backgroundColor: "#1f2937",
textColor: "#ffffff",
borderColor: "#374151",
userMessageColor: "#8b5cf6",
botMessageColor: "#374151",
},
});
```
### Corporate Branding
```javascript
PaperlinkChat.init({
apiKey: "your-api-key",
title: "Customer Success",
greeting: "Welcome! How can we assist you today?",
theme: {
primaryColor: "#dc2626", // Your brand color
backgroundColor: "#ffffff",
userMessageColor: "#dc2626",
botMessageColor: "#f3f4f6",
},
});
```
## 📖 API Reference
### Methods
- `PaperlinkChat.init(config)` - Initialize widget with configuration
- `widget.open()` - Open the chat widget
- `widget.close()` - Close the chat widget
- `widget.destroy()` - Remove widget from page
- `widget.updateConfig(newConfig)` - Update widget configuration
- `widget.getConfig()` - Get current configuration
### Events (Coming Soon)
- `paperlink-chat-open` - Widget opened
- `paperlink-chat-close` - Widget closed
- `paperlink-chat-message` - New message sent/received
## 📞 Support
- ✉️ **Email**: admin@paperlinkai.com
**Made with ❤️ by the PaperLink AI team**
[Website](https://paperlinkai.com)
</div>