Helpdesk Core

marketplace-platform/helpdesk-core - Core ticketing and support engine for multi-tenant helpdesk systems.

A Laravel package providing a complete, multi-tenant helpdesk and ticketing system with SLA management, AI co-pilot, customer portal, workflow automation, and analytics.

Self-hosted by design

This package is designed to be deployed self-hosted (inside your Laravel application and infrastructure) so you can keep data, auth, and operational control within your own environment.

Licensing & pricing

This package is proprietary (license: proprietary in composer.json) and intended for Marketplace Platform usage. It is not positioned as a standalone SaaS offering; deployment is self-hosted as part of the host application.

Features

• Multi-tenant ticketing system with complete isolation
• SLA management with business hours and escalation policies
• Queue-based ticket routing and assignment
• AI co-pilot integration for intelligent ticket handling
• Customer portal for self-service support
• Workflow automation engine
• Email channel support (inbound and outbound)
• Comprehensive analytics and metrics
• Customizable fields and ticket forms
• Team management and collaboration
• Attachment handling with security scanning

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher (or Laravel 12.0)
• MySQL 8.0 or PostgreSQL 13+
• Redis (for queues and cache)

Installation

Install the package via Composer:

composer require marketplace-platform/helpdesk-core

Publish the configuration file:

php artisan vendor:publish --tag=helpdesk-core-config

Publish and run the migrations:

php artisan vendor:publish --tag=helpdesk-core-migrations
php artisan migrate

Optionally publish the views for customization:

php artisan vendor:publish --tag=helpdesk-core-views
php artisan vendor:publish --tag=helpdesk-portal-views

Optionally publish the customer notification templates:

php artisan vendor:publish --tag=helpdesk-notifications

Configuration

1. Configure Tenant Resolver

In your config/helpdesk-core.php, set the tenant resolver:

'tenant_resolver' => \HelpdeskCore\Support\HttpHeaderTenantResolver::class,

Or implement your own by implementing HelpdeskCore\Contracts\TenantResolver:

namespace App\Services;

use HelpdeskCore\Contracts\TenantResolver;

class MyTenantResolver implements TenantResolver
{
    public function currentTenantId(): ?string
    {
        // Your tenant resolution logic
        // Example: resolve from authenticated user
        return auth()->user()?->tenant_id;
    }
}

2. Configure User Model

Set your application's user model in the config:

'user_model' => \App\Models\User::class,
'user_model_type' => 'unsignedBigInteger', // or 'uuid', 'ulid', 'string'

3. Apply Authentication Middleware

CRITICAL: The helpdesk-core package does NOT provide authentication. Your application MUST apply authentication middleware to the helpdesk routes.

See the Security section below for details.

Usage

Creating a Ticket

use HelpdeskCore\Contracts\TicketCreator;
use HelpdeskCore\DTOs\CreateTicketDTO;
use HelpdeskCore\Enums\TicketMessageChannel;

$ticketCreator = app(TicketCreator::class);

$ticket = $ticketCreator->create('your-tenant-id', new CreateTicketDTO(
    subject: 'Need help with billing',
    requesterEmail: '[email protected]',
    initialContent: 'I have a question about my invoice.',
    channel: TicketMessageChannel::Email,
));

Adding a Message to a Ticket

use HelpdeskCore\Contracts\TicketMessageService;
use HelpdeskCore\DTOs\CreateMessageDTO;
use HelpdeskCore\Enums\TicketMessageChannel;
use HelpdeskCore\Enums\TicketMessageDirection;

$messageService = app(TicketMessageService::class);

$message = $messageService->addMessage($ticket, new CreateMessageDTO(
    content: 'Thanks for reaching out. Let me check on that for you.',
    direction: TicketMessageDirection::Outgoing,
    channel: TicketMessageChannel::Email,
));

Querying Tickets

use HelpdeskCore\Models\Ticket;

// Get all tickets for the current tenant
$tickets = Ticket::all();

// Filter by status
$openTickets = Ticket::whereIn('status', ['new', 'open', 'pending'])->get();

// With relationships
$ticket = Ticket::with(['messages', 'customer', 'queue', 'assignedAgent'])->find($id);

Security

CRITICAL: Host applications MUST apply authentication middleware to all helpdesk-core API routes.

The helpdesk-core package does NOT provide built-in authentication. It expects the host application to:

1. Apply auth:sanctum or equivalent auth middleware to the route group
2. Ensure tenant access is validated through the configured TenantResolver
3. Verify agent permissions before allowing administrative actions

Example Route Configuration

In your RouteServiceProvider or routes file:

Route::middleware(['auth:sanctum'])->group(function () {
    // Helpdesk API routes will be registered here automatically
    // via the helpdesk-core service provider
});

API Middleware Stack

The default API routes use these middleware:

• api - Standard Laravel API middleware
• EnsureTenantAccess - Validates X-Tenant-ID header
• YOUR AUTH MIDDLEWARE - Must be added by host application

Portal Middleware Stack

Portal routes default to ['web', 'auth'] but can be customized via config:

'portal' => [
    'middleware' => ['web', 'auth:sanctum'],
]

Documentation

For detailed documentation, see the docs/ folder:

• Integration Guide - Complete integration walkthrough
• Migration Guide - Migrating from other helpdesk systems
• API Standards - API design and usage
• Security Standards - Security requirements and best practices
• Testing Standards - Testing patterns and requirements

API Routes

When features.api is enabled in config, the following routes are automatically registered:

Ticket Management

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/v1/tickets | List tickets | | POST | /api/helpdesk-core/v1/tickets | Create ticket | | GET | /api/helpdesk-core/v1/tickets/{id} | Get ticket details | | PATCH | /api/helpdesk-core/v1/tickets/{id} | Update ticket | | POST | /api/helpdesk-core/v1/tickets/{id}/reply | Add message to ticket |

AI Endpoints

Requires features.ai to be enabled (default: true).

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/helpdesk-core/v1/tickets/{id}/summarize | Generate AI summary of ticket | | POST | /api/helpdesk-core/v1/tickets/{id}/suggest-reply | Get AI-suggested reply | | POST | /api/helpdesk-core/v1/tickets/{id}/classify | AI classification (tags/routing) |

Analytics

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/v1/analytics/queues | Queue metrics | | GET | /api/helpdesk-core/v1/analytics/agents | Agent performance metrics | | GET | /api/helpdesk-core/v1/analytics/overview | Overview metrics | | GET | /api/helpdesk-core/v1/analytics/volume | Ticket volume over time |

Presence / Collision Detection

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/v1/tickets/{id}/presence | Get active viewers on ticket | | POST | /api/helpdesk-core/v1/tickets/{id}/presence | Update presence (heartbeat) | | DELETE | /api/helpdesk-core/v1/tickets/{id}/presence | Remove presence |

Canned Responses

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/v1/canned-responses | List canned responses | | POST | /api/helpdesk-core/v1/canned-responses | Create canned response | | GET | /api/helpdesk-core/v1/canned-responses/search | Search canned responses | | GET | /api/helpdesk-core/v1/canned-responses/categories | List categories | | GET | /api/helpdesk-core/v1/canned-responses/stats | Usage statistics | | GET | /api/helpdesk-core/v1/canned-responses/{id} | Get canned response | | PUT | /api/helpdesk-core/v1/canned-responses/{id} | Update canned response | | DELETE | /api/helpdesk-core/v1/canned-responses/{id} | Delete canned response | | POST | /api/helpdesk-core/v1/canned-responses/{id}/render | Render with variables | | POST | /api/helpdesk-core/v1/canned-responses/{id}/duplicate | Duplicate response |

Real-time Polling

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/v1/broadcast/poll | Poll for events (non-WebSocket clients) |

For detailed API documentation including request/response schemas, see docs/api/helpdesk-core-openapi.yaml.

Customer Portal

When features.portal is enabled, customers can access their tickets via the portal routes:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/helpdesk-core/portal/tickets | List customer's tickets | | POST | /api/helpdesk-core/portal/tickets | Create new ticket | | GET | /api/helpdesk-core/portal/tickets/{id} | View ticket | | POST | /api/helpdesk-core/portal/tickets/{id}/reply | Reply to ticket | | POST | /api/helpdesk-core/portal/tickets/{id}/satisfaction | Rate satisfaction |

Events

The package dispatches several events you can listen to:

• HelpdeskCore\Events\TicketCreated
• HelpdeskCore\Events\TicketStatusChanged
• HelpdeskCore\Events\TicketQueueChanged
• HelpdeskCore\Events\TicketMessageAdded
• HelpdeskCore\Events\TicketAssigned
• HelpdeskCore\Events\TicketReassigned
• HelpdeskCore\Events\TicketUnassigned
• HelpdeskCore\Events\TicketMessageRedacted
• HelpdeskCore\Events\AgentMentionedInTicket
• HelpdeskCore\Events\Sla\SlaBreached
• HelpdeskCore\Events\Sla\SlaBreachWarning
• HelpdeskCore\Events\Email\InboundEmailReceived
• HelpdeskCore\Events\Email\EmailMessageDelivered
• HelpdeskCore\Events\Email\EmailMessageBounced
• HelpdeskCore\Events\Email\EmailMessageComplained
• HelpdeskCore\Events\Email\EmailAddressSuppressed

Register custom listeners in your config:

'listeners' => [
    \HelpdeskCore\Events\TicketCreated::class => [
        \App\Listeners\SendSlackNotification::class,
    ],
],

Testing

Run the test suite:

composer test

Run static analysis:

composer analyse

Format code:

composer format

License

Proprietary. All rights reserved.

Copyright (c) 2024-2026 Marketplace Platform