Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@ticketping/chat-widget

ticketping-com712MIT1.7.7TypeScript support: included

Customer support chat widget for Ticketping - Intercom-like experience with real-time messaging

chat-widget, customer-support, ticketping, help-desk, live-chat, support-widget, real-time, javascript, typescript

readme

Ticketping Chat Widget

A modern, customizable customer support chat widget with real-time messaging capabilities. Built for seamless integration into any website.

npm version License: MIT

This widget is meant to be used with Ticketping - Customer support meets Slack

Features

  • Real-time messaging with WebSocket support
  • Fully customizable themes and colors
  • Mobile responsive design
  • Conversation history and persistence
  • File attachments support
  • Secure authentication with JWT
  • Lightweight (< 50KB gzipped)

| | URL | |----------------|---------------------------------------------------------------------| | Documentation | docs.ticketping.com | | Demo | Ticketping | | Email | support@ticketping.com | | Issues | GitHub Issues | | NPM | NPM Package |

Installation

npm install @ticketping/chat-widget

Or via CDN:

<script src="https://unpkg.com/@ticketping/chat-widget@latest/dist/widget.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@ticketping/chat-widget@latest/dist/widget.css">

Quick Start

Basic Usage

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://unpkg.com/@ticketping/chat-widget@latest/dist/widget.css">
</head>
<body>
    <script src="https://unpkg.com/@ticketping/chat-widget@latest/dist/widget.min.js"></script>
    <script>
        window.TicketpingChat.init({
            appId: 'your-app-id',
            teamSlug: 'your-team-slug',
            teamLogoIcon: 'cdn-link-to-your-logo-square',
        });
    </script>
</body>
</html>

ES Modules

import TicketpingChat from '@ticketping/chat-widget';
import '@ticketping/chat-widget/style';

const chat = new TicketpingChat({
    appId: 'your-app-id',
    teamSlug: 'your-team-slug',
    teamLogoIcon: 'cdn-link-to-your-logo-square',
});

React Integration

// Install the package and React
npm install @ticketping/chat-widget react
import React, { useRef } from 'react';
import TicketpingChat from '@ticketping/chat-widget/react';

function App() {
  const chatRef = useRef();

  return (
    <div>
      <h1>My App</h1>

      <TicketpingChat
        ref={chatRef}
        appId="your-app-id"
        teamSlug="your-team-slug"
        teamLogoIcon="cdn-link-to-your-logo-square"
      />
    </div>
  );
}

export default App;

Custoizing theme and troubleshooting

Read more on react docs.

React Component Props

Prop Type Default Description
appId string '' Your Ticketping app ID
teamSlug string '' Your team slug
teamLogoIcon string '' URL to your team logo
apiBase string 'https://api.ticketping.com' API base URL
wsBase string 'wss://api.ticketping.com' WebSocket base URL
userJWT string '' User authentication token
debug boolean false Enable debug mode
analytics boolean true Enable analytics
theme object null Custom theme configuration
open boolean false Control widget open state

Svelte Integration

Svelte 5 (Recommended)

// Install the package and Svelte
npm install @ticketping/chat-widget
<script>
  import TicketpingChat from '@ticketping/chat-widget/svelte';
  import('@ticketping/chat-widget/style')
</script>

<TicketpingChat
  appId="your-app-id"
  teamSlug="your-team-slug"
  teamLogoIcon="cdn-link-to-your-logo-square"
/>

Svelte 4

// Install the package and Svelte 4
npm install @ticketping/chat-widget svelte@^4.0.0
<script>
  import TicketpingChat from '@ticketping/chat-widget/svelte4';
  import('@ticketping/chat-widget/style')
</script>

<TicketpingChat
  appId="your-app-id"
  teamSlug="your-team-slug"
  teamLogoIcon="cdn-link-to-your-logo-square"
/>

Svelte Component Props

Prop Type Default Description
appId string '' Your Ticketping app ID
teamSlug string '' Your team slug
teamLogoIcon string '' URL to your team logo
apiBase string 'https://api.ticketping.com' API base URL
wsBase string 'wss://api.ticketping.com' WebSocket base URL
userJWT string '' User authentication token
debug boolean false Enable debug mode
analytics boolean true Enable analytics
theme object null Custom theme configuration
open boolean false Control widget open state
userData object null User identification data

Configuration

Basic Configuration

window.TicketpingChat.init({
    // Required
    appId: 'your-app-id',
    teamSlug: 'your-team-slug',
    teamLogoIcon: 'cdn-link-to-your-logo-square',

    // Optional - API endpoints
    apiBase: 'https://api.ticketping.com',
    wsBase: 'wss://ws.ticketping.com',

    // Optional - Authentication
    userJWT: 'your-user-jwt-token',

    // Optional - Behavior
    autoOpen: false,
    position: 'bottom-right' // or 'bottom-left'
});

Custom Theme

window.TicketpingChat.init({
    appId: 'your-app-id',
    teamSlug: 'your-team-slug',
    teamLogoIcon: 'cdn-link-to-your-logo-square',
    theme: {
        primaryColor: '#3b82f6',  // accent color
        primaryHover: '#2563eb',  // slightly darker accent color
        // ... more theme options
    }
});

Event Callbacks

window.TicketpingChat.init({
    appId: 'your-app-id',
    teamSlug: 'your-team-slug',
    teamLogoIcon: 'cdn-link-to-your-logo-square',

    // Event callbacks
    onReady: () => console.log('Widget ready'),
    onOpen: () => console.log('Widget opened'),
    onClose: () => console.log('Widget closed'),
    onMessageSent: (message) => console.log('Message sent:', message),
    onMessageReceived: (message) => console.log('Message received:', message),
    onConversationStarted: (id) => console.log('Conversation started:', id),
    onError: (error) => console.error('Widget error:', error)
});

API Methods

After initialization, you can control the widget programmatically:

const chat = window.TicketpingChat;

// Open/close the widget
chat.open();
chat.close();

// Identify the current user
chat.identify({
    id: 'user-123',
    email: 'user@example.com',
    name: 'John Doe',
    userJWT: 'your-user-jwt'
});

// Start a new conversation
chat.startConversation();

// Clean up
chat.destroy();

Theming

The widget supports extensive theming through CSS custom properties:

:root {
    --tp-primary-color: #your-brand-color;
    --tp-text-primary: #333333;
    --tp-background: #ffffff;
    /* ... more variables */
}

Available Theme Variables

  • --tp-primary-color - Primary brand color
  • --tp-primary-hover - Primary color hover state
  • --tp-text-primary - Primary text color
  • --tp-text-secondary - Secondary text color
  • --tp-text-muted - Muted text color
  • --tp-background - Main background color
  • --tp-background-secondary - Secondary background color
  • --tp-border - Border color
  • And many more...

Browser Support

  • Chrome/Edge 80+
  • Firefox 75+
  • Safari 13+
  • Mobile browsers (iOS Safari, Chrome Mobile)

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

Examples

Check out the /examples directory for integration examples with:

  • Vanilla JavaScript
  • React
  • Next.js
  • Svelte

License

MIT © Ticketping

Support

changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] - 2025-07-26

Added

  • Initial release of Ticketping Chat Widget
  • Real-time messaging with WebSocket support
  • Fully customizable themes and colors
  • Mobile-responsive design
  • Conversation history and persistence
  • File attachment support
  • Typing indicators and notifications
  • Dark/Light theme support
  • Secure JWT authentication
  • Multiple integration methods (CDN, ES modules, React)
  • Comprehensive event callback system
  • Automatic conversation management
  • Local storage for conversation persistence
  • SpendCrypto.com theme integration

Features

  • Chat bubble
  • Collapsible chat window
  • Multi-tab interface (Home, Messages)
  • Message input with emoji support
  • File upload with validation
  • Agent status indicators
  • Error handling and retry mechanisms
  • Analytics tracking
  • Accessibility features
  • Cross-browser compatibility

Technical Details

  • Built with vanilla JavaScript/ES6+
  • Vite build system
  • CSS custom properties for theming
  • WebSocket with fallback to REST API
  • Local storage for data persistence
  • Responsive design with CSS Grid/Flexbox
  • Bundle size < 50KB gzipped

[Unreleased]

Planned

  • Voice message support
  • Rich text formatting
  • Emoji picker
  • Message reactions
  • Multi-language support