@consilioweb/payload-support

v0.6.4

Published

8 hours ago

Payload CMS plugin — professional support & ticketing system with AI, SLA, time tracking, live chat, and more

[!IMPORTANT]
⚠️ Next.js 16 + Turbopack — Known Issue
If you're using Next.js 16 with Turbopack (default bundler), you may encounter a createContext is not a function error during next build. This is a known Payload CMS issue (#15429, #14330) — not specific to this plugin.
Workaround — Add this to your admin page (src/app/(payload)/admin/[[...segments]]/page.tsx):
export const dynamic = 'force-dynamic'
And ensure all @consilioweb/* packages are in transpilePackages in your next.config.ts:
transpilePackages: ['@consilioweb/seo-analyzer', '@consilioweb/admin-nav', /* ...other @consilioweb packages */],
✅ Next.js 15 works without any workaround.

About

@consilioweb/payload-support — A complete, production-ready support & ticketing system for Payload CMS 3. Comparable to Freshdesk, HelpScout, and Crisp — but free, open-source, and fully integrated into Payload's admin panel.

Features

Core Ticketing

Auto-increment ticket numbers (TK-0001, TK-0002...)
Statuses, priorities, categories, tags
Multi-agent assignment with round-robin distribution
Ticket merge, split, snooze
Scheduled replies
Bulk actions on multiple tickets
Command palette (⌘K) for instant search

AI Integration

Sentiment analysis — detect client mood from messages
AI summary — generate conversation synthesis
Smart reply — suggest contextual responses
Rewrite — rephrase messages professionally
Multi-provider: Anthropic Claude, OpenAI, Ollama, custom endpoint
AI chatbot for first-line self-service

SLA & Compliance

Response & resolution time targets per priority
Business hours support
SLA breach alerts on dashboard
Webhook dispatch on sla_breached events

Time Tracking & Billing

Built-in timer with pause/resume
Manual time entries per ticket
Time dashboard with analytics
Billing/invoicing foundation
Facturable toggle per ticket

Live Chat

Real-time chat sessions via Server-Sent Events (SSE) (v0.2.0)
Automatic SSE to polling fallback when EventSource unavailable (v0.2.0)
Typing indicators
Chat-to-ticket conversion
Agent presence/collision detection

Email Integration

Inbound email → ticket/message (via webhook)
Pending email queue with client matching
Email pixel tracking (opens)
Per-agent email signatures
Email log viewer with purge

Client Management (CRM)

Client profiles with history
Impersonation (view as client)
Client merge
Satisfaction surveys (CSAT 1-5)
Knowledge base / FAQ
Client portal (separate auth)

Automation

Auto-close inactive tickets
Canned responses with template variables
Macros (multi-action shortcuts)
Webhooks (HMAC-SHA256 signed) with dispatch on ticket events (v0.2.0)
Scheduled replies processing endpoint (v0.2.0)
Activity log (full audit trail)

Security (v0.2.0)

XSS prevention — escapeHtml on all email template dynamic fields
2FA codes hashed with HMAC-SHA256 before storage
Tracking pixels signed with HMAC
OAuth Google — allowedEmailDomains option for domain restriction
Rate limiting — unified RateLimiter class on all public endpoints
Collection injection protection — validates collection parameters against whitelist
Password generation — uses crypto.randomBytes (not Math.random)

Internationalization

Full FR/EN support
Locale toggle in settings
Extensible translation system

Architecture

Collections (15)

| Collection | Description | |------------|-------------| | tickets | Core ticket with auto-increment, SLA, activity hooks | | ticket-messages | Conversation messages with author type, attachments | | support-clients | Client auth collection (email/password) | | time-entries | Time tracking per ticket | | canned-responses | Quick reply templates with variables | | ticket-activity-log | Immutable audit trail | | satisfaction-surveys | CSAT ratings (1-5) | | knowledge-base | FAQ articles with rich text | | chat-messages | Live chat sessions | | pending-emails | Inbound email queue | | email-logs | Email delivery audit | | auth-logs | Authentication audit | | webhook-endpoints | Outbound webhook config | | sla-policies | SLA rules per priority | | macros | Multi-action shortcuts | | ticket-statuses | Custom configurable statuses |

API Endpoints (34)

| Category | Endpoints | |----------|-----------| | Tickets | search, bulk-action, merge-tickets, split-ticket, export-csv, export-data | | AI | ai (sentiment/synthesis/suggest/rewrite), chatbot | | Chat | chat, admin-chat, typing, presence | | Email | pending-emails/process, resend-notification, track-open, email-stats | | Config | settings, signature, round-robin-config, statuses, sla-check, auto-close | | Auth | login, 2fa, oauth/google, delete-account | | SSE | client-stream, admin-stream (v0.2.0) | | Scheduled | process-scheduled (v0.2.0) | | Misc | apply-macro, purge-logs, seed-kb, admin-stats, billing, import-conversation, merge-clients, satisfaction |

Admin Views (12)

| View | Path | Description | |------|------|-------------| | Inbox | /support/inbox | Superhuman-style ticket list with keyboard nav | | Dashboard | /support/dashboard | KPIs, SLA metrics, active tickets | | Ticket Detail | /support/ticket?id=X | Full conversation with sidebar panels | | New Ticket | /support/new-ticket | Create ticket with client search | | Settings | /support/settings | Feature flags, AI, SLA, auto-close config | | CRM | /support/crm | Client list and profiles | | Chat | /support/chat | Live chat sessions | | Pending Emails | /support/emails | Inbound email queue | | Email Tracking | /support/tracking | Open/delivery tracking | | Time Dashboard | /support/time | Time entries analytics | | Logs | /support/logs | Email & auth audit logs | | Billing | /support/billing | Invoice management |

Client Portal (30 files)

Full-featured client-facing support portal with its own auth system:

| Page | Description | |------|-------------| | Login / Register | Email + password auth, Google OAuth | | Forgot / Reset password | Email-based password recovery | | Dashboard | Ticket stats, recent activity, quick actions | | Ticket List | Filterable, sortable ticket list | | Ticket Detail | Conversation thread, reply form, file attachments, satisfaction survey | | New Ticket | Category selection, priority, file upload | | FAQ | Knowledge base with search | | Profile | Edit name, company, email, password, notification prefs, 2FA, delete account | | Chat Widget | Real-time live chat with agent | | Chatbot | AI-powered self-service from knowledge base |

Email Template System

Configurable, responsive HTML email templates:

import { createEmailTemplateFactory } from '@consilioweb/payload-support'

const emails = createEmailTemplateFactory({
  brandName: 'My Company',
  brandColor: '#2563eb',
  logoUrl: 'https://example.com/logo.png',
  supportEmail: '[email protected]',
  websiteUrl: 'https://example.com',
})

// Use pre-configured functions
const html = emails.wrapper('Welcome', [
  emails.paragraph('Hello <strong>John</strong>,'),
  emails.button('Open Dashboard', 'https://example.com/dashboard'),
].join(''))

Available functions: emailWrapper, emailButton, emailParagraph, emailQuote, emailInfoRow, emailRichContent, emailTrackingPixel, escapeHtml

Installation

pnpm add @consilioweb/payload-support

Or with npm/yarn:

npm install @consilioweb/payload-support
yarn add @consilioweb/payload-support

Peer Dependencies

| Package | Version | Required | |---------|---------|----------| | payload | ^3.0.0 | Yes | | @payloadcms/next | ^3.0.0 | Optional (admin views) | | @payloadcms/ui | ^3.0.0 | Optional (admin UI) | | next | ^14.0.0 \|\| ^15.0.0 \|\| ^16.0.0 | Optional (admin UI) | | react | ^18.0.0 \|\| ^19.0.0 | Optional (admin UI) |

Quick Start

import { buildConfig } from 'payload'
import { supportPlugin } from '@consilioweb/payload-support'

export default buildConfig({
  // ... your existing config
  plugins: [
    supportPlugin({
      // All features enabled by default — disable what you don't need
      features: {
        chat: false,        // disable live chat
        billing: false,     // disable billing
        roundRobin: true,   // enable round-robin (off by default)
      },

      // AI provider (optional)
      ai: {
        provider: 'anthropic',
        model: 'claude-haiku-4-5-20251001',
      },

      // Locale
      locale: 'fr',

      // Email
      email: {
        fromAddress: '[email protected]',
        fromName: 'Support Team',
      },
    }),
  ],
})

Next.js Configuration

Add the plugin to transpilePackages in your next.config.mjs so Next.js can resolve the view components:

// next.config.mjs
import { withPayload } from '@payloadcms/next/withPayload'

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@consilioweb/payload-support'],
}

export default withPayload(nextConfig)

Then regenerate the import map:

pnpm generate:importmap

Configuration

`SupportPluginConfig`

supportPlugin({
  features: {},                    // Feature flags (see below)
  ai: { provider, apiKey, model }, // AI provider config
  email: { fromAddress, fromName, replyTo },
  locale: 'fr',                    // 'fr' | 'en'
  navGroup: 'Support',             // Sidebar group label
  basePath: '/support',            // Admin view base path
  userCollectionSlug: 'users',     // Agent collection slug
  collectionSlugs: {               // Override any collection slug
    tickets: 'my-tickets',
    ticketMessages: 'my-messages',
    // ...
  },

  // v0.2.0 — Webhook dispatch
  webhooks: {
    url: 'https://hooks.slack.com/services/...',
    secret: process.env.WEBHOOK_SECRET,
    events: ['ticket.created', 'ticket.resolved', 'ticket.assigned', 'ticket.replied'],
  },

  // v0.2.0 — OAuth restrictions
  allowedEmailDomains: ['mycompany.com', 'partner.com'],
})

Feature Flags (25+)

All features are enabled by default except roundRobin and customStatuses.

| Flag | Default | Description | |------|---------|-------------| | timeTracking | true | Timer, manual entries, billing | | ai | true | Sentiment, synthesis, suggestion, rewrite | | satisfaction | true | CSAT surveys after resolution | | chat | true | Live chat sessions | | emailTracking | true | Pixel tracking, open status | | canned | true | Quick reply templates | | merge | true | Merge two tickets | | snooze | true | Temporarily hide ticket | | externalMessages | true | Add external messages | | clientHistory | true | Past tickets sidebar | | activityLog | true | Audit trail | | splitTicket | true | Extract message to new ticket | | scheduledReplies | true | Future message sending | | autoClose | true | Close inactive tickets | | autoCloseDays | 7 | Days before auto-close | | roundRobin | false | Distribute tickets to agents | | sla | true | SLA policies & alerts | | webhooks | true | Outbound HTTP hooks | | macros | true | Multi-action shortcuts | | customStatuses | false | Configurable ticket statuses | | collisionDetection | true | Multi-agent collision warning | | signatures | true | Per-agent email signatures | | chatbot | true | AI self-service chatbot | | bulkActions | true | Bulk ticket operations | | commandPalette | true | ⌘K search | | knowledgeBase | true | FAQ / knowledge base | | pendingEmails | true | Inbound email queue | | authLogs | true | Authentication audit logs (v0.2.0) |

AI Providers

Anthropic (Claude)

supportPlugin({
  ai: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY,
    model: 'claude-haiku-4-5-20251001', // fast & affordable
  },
})

OpenAI

supportPlugin({
  ai: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o-mini',
  },
})

Ollama (self-hosted)

supportPlugin({
  ai: {
    provider: 'ollama',
    baseUrl: 'https://ollama.example.com',
    model: 'qwen2.5:32b',
  },
})

Package Exports

// Server — plugin, types, collections
import { supportPlugin, DEFAULT_FEATURES } from '@consilioweb/payload-support'
import type {
  SupportPluginConfig,
  SupportFeatures,
  AIProviderConfig,
  TicketData,
  MessageData,
} from '@consilioweb/payload-support'

// Client — React components for Payload admin
import { /* components */ } from '@consilioweb/payload-support/client'

// Views — server components wrapped in DefaultTemplate
import { /* views */ } from '@consilioweb/payload-support/views'

Roadmap

Custom ticket statuses — dynamic workflow states instead of hardcoded open/waiting/resolved
Snooze tickets — hide from inbox until a specified date
Billing & invoicing — time-based billing, invoice PDF generation
Knowledge base search — client portal FAQ with full-text search
Email inbound processing — parse email replies into ticket messages
Real-time typing indicators via SSE
Canned responses / macros UI — quick reply templates in admin
Dashboard analytics — charts, trends, response times, SLA compliance
Multi-language client portal — full i18n beyond FR/EN
File attachments on ticket messages
Ticket tags & custom fields

Requirements

Node.js >= 18
Payload CMS 3.x
React 18.x or 19.x
Database: Any Payload-supported adapter (SQLite, PostgreSQL, MongoDB)

☕ Support

If this plugin saves you time, consider buying me a coffee!

License

MIT

Author

Made with passion by ConsilioWEB