PiqoChat Widget

A lightweight, embeddable chat widget for websites. Built with TypeScript and Vite for maximum performance and maintainability.

🚀 Features

• Real-time messaging with live agents
• Lightweight - Only ~8kB gzipped
• TypeScript - Full type safety and IntelliSense
• Mobile responsive design
• Automatic persistence - Conversations survive page reloads
• Easy integration - Drop-in script with data attributes
• Customizable - Theme, position, and behavior options
• No dependencies - Self-contained widget

📦 Installation

Option 1: Script Tag (Recommended)

Add this to your website before the closing </body> tag:

<!-- PiqoChat Widget -->
<script
  src="https://your-cdn.com/piqochat-widget.umd.js"
  data-piqochat-workspace-id="your-workspace-id"
  data-piqochat-base-url="http://localhost:8090"
  data-piqochat-welcome-message="Hello! How can I help you today?"
></script>

Option 2: JavaScript API

<script src="https://your-cdn.com/piqochat-widget.umd.js"></script>
<script>
  PiqoChatWidget.init({
    workspaceId: 'your-workspace-id',
    baseUrl: 'http://localhost:8090',
    welcomeMessage: 'Hello! How can I help you today?'
  })
</script>

Option 3: ES Module

import PiqoChatWidget from 'piqochat-widget'

PiqoChatWidget.init({
  workspaceId: 'your-workspace-id',
  baseUrl: 'http://localhost:8090'
})

⚙️ Configuration Options

interface WidgetConfig {
  workspaceId: string // Required: Your PiqoChat workspace ID
  baseUrl?: string // Default: 'http://localhost:8090'
  welcomeMessage?: string // Default: 'Hello! How can I help you today?'
  theme?: {
    primaryColor?: string
    backgroundColor?: string
    textColor?: string
    borderRadius?: string
  }
  position?: {
    bottom?: string // Default: '1rem'
    right?: string // Default: '1rem'
    left?: string
    top?: string
  }
}

🎯 API Reference

Global Methods

// Initialize the widget
PiqoChatWidget.init(config)

// Set visitor information
PiqoChatWidget.setVisitorInfo({
  name: 'John Doe',
  email: '[email protected]',
  customData: { userId: '123' }
})

// Update configuration
PiqoChatWidget.updateConfig({
  welcomeMessage: 'New welcome message'
})

// Programmatically open the widget
PiqoChatWidget.open()

// Destroy the widget
PiqoChatWidget.destroy()

Data Attributes

You can configure the widget using data attributes on the script tag:

• data-piqochat-workspace-id - Your workspace ID (required)
• data-piqochat-base-url - Your PiqoChat server URL
• data-piqochat-welcome-message - Custom welcome message

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd piqochat-widget

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Project Structure

src/
├── index.ts              # Main entry point and global API
├── PiqoChatWidget.ts     # Core widget class
├── types.ts              # TypeScript interfaces
├── styles.ts             # Widget CSS styles
└── sdk/                  # Minimal PocketBase SDK
    ├── PiqoChatClient.ts
    ├── RecordService.ts
    ├── RealtimeService.ts
    └── ...

Testing

Open example.html in your browser to test the widget:

# Serve the built widget
npm run serve

# Or open directly
open example.html?workspace=your-workspace-id

📱 Mobile Support

The widget is fully responsive and includes specific optimizations for mobile devices:

• Adaptive sizing for smaller screens
• Touch-friendly interface
• Proper viewport handling

🔒 Privacy & Storage

The widget stores conversation data in localStorage:

• piqochat_conversation - Active conversation metadata
• piqochat_messages - Message history
• piqochat_visitor_info - Visitor information

This ensures conversations persist across page reloads while respecting user privacy.

🏗️ Architecture

The widget is built with a modular architecture:

1. Core Widget (PiqoChatWidget.ts) - Main widget logic and UI
2. Minimal SDK (sdk/) - Lightweight PocketBase client (~3.8kB)
3. Global API (index.ts) - Public API and auto-initialization
4. Styles (styles.ts) - Scoped CSS with no external dependencies

🚀 Deployment

Build for Production

npm run build

This creates:

• dist/piqochat-widget.es.js - ES module version
• dist/piqochat-widget.umd.js - UMD version (for script tags)
• Type definitions for TypeScript users

CDN Deployment

Upload the built files to your CDN and update the installation URLs.

Self-Hosting

You can host the widget files on your own server:

1. Build the widget: npm run build
2. Upload dist/ files to your server
3. Update script src URLs in your installation code

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Run tests: npm test
5. Build: npm run build
6. Commit changes: git commit -am 'Add new feature'
7. Push: git push origin feature/new-feature
8. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For questions and support:

1. Check the documentation
2. Open an issue on GitHub
3. Contact the PiqoChat team

Made with ❤️ for better customer communication