@paperlinkai/chat

v0.1.5

Published

a month ago

PaperLink AI Chat Widget - Easy integration for any website

0High
0Medium
0Low

paperlinkai

chatbot widget embed ai rag paperlink

🤖 PaperLink Chat

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:

<!-- 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

npm install @paperlink/chat

import Chat from "@paperlink/chat";
import "@paperlink/chat/dist/style.css";

Chat.init({
  apiKey: "your-api-key-here",
  title: "AI Assistant",
});

📋 Configuration

Basic Configuration

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

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:

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:

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

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

<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

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:

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

// 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

PaperlinkChat.init({
  apiKey: "your-api-key",
  theme: {
    primaryColor: "#8b5cf6",
    backgroundColor: "#1f2937",
    textColor: "#ffffff",
    borderColor: "#374151",
    userMessageColor: "#8b5cf6",
    botMessageColor: "#374151",
  },
});

Corporate Branding

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: [email protected]

Made with ❤️ by the PaperLink AI team

Website