HelpCenter & Knowledge Base

A full-featured customer support system with ticket management, departmental routing, custom fields, and an integrated Knowledge Base: all built into a single Larapen add-on.

Use Cases

Product Support Desk

You sell software or digital products and need a structured support system.

• Create departments for each product line (e.g. “Plugin Support”, “Theme Support”).
• Add custom fields to collect product version, URL, or license key on ticket creation.
• Enable guest access so customers can submit tickets without registering.
• Use the AI assistant to draft replies and speed up response times.

Internal IT HelpDesk

Your company needs an internal ticketing system for IT support requests.

• Disable guest access: only authenticated employees can submit tickets.
• Create departments: “Hardware”, “Software”, “Network”, “Access & Permissions”.
• Use priority levels (Low, Medium, High, Urgent) for SLA tracking.
• Build a Knowledge Base with FAQs and troubleshooting guides to reduce ticket volume.

Self-Service Documentation Portal

You want a public-facing help center with searchable articles organized by topic.

• Create KB collections for major topics (Getting Started, API Reference, Billing, etc.).
• Use nested collections for sub-categories.
• Enable helpful votes so users can rate articles.
• Link the “Submit a Ticket” form from article pages for issues not covered by documentation.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+
• barryvdh/laravel-dompdf (for PDF export)
• laravel/ai (for AI assistant features; optional but recommended)

Installation

Step 1: Place the Add-on

Copy or symlink the helpcenter folder into your Larapen "extensions/addons" directory:

Step 2: Activate the Add-on

Go to Admin → Add-ons → Installed Add-ons and activate HelpCenter & Knowledge Base.

Step 3: Run Migrations

This creates 6 tables: helpcenter_departments, helpcenter_tickets, helpcenter_replies, helpcenter_custom_fields, helpcenter_custom_field_values, helpcenter_kb_collections, and helpcenter_kb_articles.

Step 4: Set Permissions

The add-on registers 21 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.

Step 5: Create Departments

Navigate to Admin → HelpCenter → Departments and create at least one department (e.g. “General Support”). Departments are required: a ticket cannot be submitted without one.

Step 6: Configure (Optional)

Review settings at Admin → HelpCenter → Settings. See Configuration for all available options.

Configuration

Settings are managed in Admin → HelpCenter → Settings (stored in the settings table, group helpcenter). Config file defaults are in config/helpcenter.php.

Ticket Settings

Setting	Description	Default
helpcenter_guest_access	Allow non-authenticated users to create tickets.	true
helpcenter_items_per_page	Number of tickets per page in lists.	15
helpcenter_auto_close_days	Auto-close resolved tickets after N days of inactivity. Set to 0 to disable.	0
helpcenter_allow_customer_close	Allow customers to close their own tickets from the front-end portal.	true
helpcenter_allow_priority_selection	Show priority selector on the ticket creation form.	false
helpcenter_allow_attachments	Allow file attachments on tickets and replies.	true
helpcenter_max_attachment_size	Maximum attachment file size in KB.	5120 (5 MB)
helpcenter_replies_order	Display order of replies: oldest_first or newest_first.	oldest_first
helpcenter_response_time	Expected response time displayed to customers.	48
helpcenter_response_time_unit	Unit for response time: minutes, hours, days, weeks.	hours

Notification Settings

Setting	Description	Default
helpcenter_notify_admin_on_new_ticket	Send email notification to all admin users when a new ticket is created.	true
helpcenter_notify_author_on_new_ticket	Send confirmation email to the ticket author after submission.	true
helpcenter_notify_author_on_new_reply	Notify the ticket author when an admin posts a reply (internal notes are excluded).	true

Knowledge Base Settings

Setting	Description	Default
kb_guest_access	Allow non-authenticated users to browse the Knowledge Base.	true
kb_require_auth	Require authentication to access the Knowledge Base.	false
kb_items_per_page	Number of articles per page.	12
kb_show_search	Display the search bar on the KB index page.	true
kb_show_reading_time	Show estimated reading time on articles (calculated at ~200 words/min).	true
kb_show_helpful_votes	Display “Was this helpful?” yes/no voting on articles.	true
kb_show_related_articles	Show related articles from the same collection at the bottom of article pages.	true

Allowed Attachment Types

The following file types are accepted for attachments (configured in config/helpcenter.php):

Admin: Dashboard

The Dashboard (HelpCenter → Dashboard) provides a combined view of all tickets with statistics.

Stats Cards

Aggregate counts displayed at the top:

• Total: all tickets in the system
• Open: tickets with open status
• In Progress: tickets being actively worked on
• Waiting: combined count of waiting_customer and waiting_agent
• Resolved: tickets marked as resolved
• Closed: permanently closed tickets

Ticket Table

Below the stats cards, a paginated and filterable table of all tickets showing reference, subject, department, status badge, priority badge, submitter name, and last activity date. Filters include status, priority, department, and free-text search (searches reference, subject, guest name, and guest email).

Admin: Tickets

Filtered Ticket Lists

The sidebar provides pre-filtered ticket views, each showing only tickets in a specific status group:

Sidebar Link	Statuses Included
Open	open
In Progress	in_progress, waiting_customer, waiting_agent
Resolved	resolved
Closed	closed

Each list supports additional filters for priority, department, and search.

Ticket Detail Page

The ticket detail page (HelpCenter → Tickets → {reference}) shows:

• Ticket header: reference number, subject, status badge, priority badge, department, submitter info, creation date
• Status/Priority/Department controls: inline dropdown selectors to change status, priority, or department (AJAX-powered, returns JSON responses)
• Conversation thread: all replies in chronological order (configurable via helpcenter_replies_order). Each reply shows author name, admin/customer badge, timestamp, body text, and attachments
• Internal notes: admin-only notes visible only to staff, styled differently from customer replies
• Custom field values: the values submitted for all custom fields on the ticket
• Recent tickets: sidebar panel showing up to 10 recent tickets from the same customer
• Envato purchases: if the Envato add-on is active and the ticket has a linked user, shows the user’s verified Envato purchases

Replying to Tickets

The reply form at the bottom of the ticket detail page supports:

• Reply body: rich text area for the response
• Internal note toggle: marks the reply as an internal-only note (not sent to customer, not visible on front-end)
• File attachments: attach files to the reply
• Reply action: after sending, choose to: stay on the ticket, go to the ticket list, or jump to the next ticket
• Edit/Delete replies: admin users can edit the body of any reply or delete replies entirely (AJAX-powered)

Auto-Status Updates on Reply

When a reply is posted on an open ticket:

• Admin reply → status automatically changes to in_progress
• Customer reply → status automatically changes to open
• Closed/resolved tickets are not auto-updated

Merge & PDF Export

Merging Tickets

Admin can merge a source ticket into a target ticket via POST admin/helpcenter/tickets/{ticket}/merge. This operation:

1. Moves all replies from the source to the target ticket
2. Moves ticket-level attachments (morph relation) to the target
3. Deletes custom field values from the source (not transferable)
4. Deletes the source ticket record

The entire operation runs inside a database transaction.

PDF Export

Click the Download PDF button on any ticket detail page to generate a formatted PDF containing the ticket header, all replies, and metadata. Uses barryvdh/laravel-dompdf.

Admin: Departments

Departments organize tickets into logical groups (e.g. “Sales”, “Technical Support”, “Billing”). Managed via HelpCenter → Departments.

Department Fields

Field	Description
Name (translatable)	Display name shown to customers in the department selector.
Slug (translatable)	URL-friendly identifier.
Description (translatable)	Optional description for admin reference.
Email	Optional contact email for the department.
Is Active	Only active departments appear in the ticket creation form.
Position	Sort order in dropdowns and lists.

The department list page shows ticket counts per department. Standard CRUD operations: create, edit, delete.

Admin: Custom Fields

Custom fields extend the ticket creation form with additional data collection. Managed via HelpCenter → Custom Fields.

Supported Field Types

Type	Description	Has Options?
text	Single-line text input (max 255 characters)	No
textarea	Multi-line text input (max 5000 characters)	No
select	Dropdown select with predefined options	Yes
checkbox	Multiple checkboxes (values stored as JSON)	Yes
radio	Radio buttons with predefined options	Yes
number	Numeric input	No
email	Email address input with format validation	No
date	Date picker input	No
file	File upload (stored via MediaService)	No

Custom Field Properties

Field	Description
Label (translatable)	Display label shown to the user.
Name	Internal identifier (used as form field name).
Type	One of the 9 supported types above.
Options	Array of valid values (only for select, checkbox, radio types).
Placeholder (translatable)	Placeholder text for the input.
Is Required	Whether the field is mandatory on ticket creation.
Is Active	Only active fields are shown on the form.
Position	Sort order on the form.

Dynamic Validation

The CustomFieldService::buildValidationRules() method automatically generates Laravel validation rules from the active custom field definitions. Rules are type-aware (e.g. email type adds email validation, select/radio validate against the defined options, file validates size limits).

Admin: Knowledge Base

KB Collections

Collections group articles into categories. Managed via HelpCenter → KB Collections.

• Nestable: collections support a parent/child hierarchy (via parent_id).
• Translatable: name, slug, and description support multiple languages.
• Icon: optional Bootstrap Icon class (e.g. bi-book) displayed on the front-end.
• Active/Inactive: only active collections are shown on the front-end.
• Position: controls sort order.

KB Articles

Articles are rich-content documents within collections. Managed via HelpCenter → KB Articles.

Article Fields

Field	Description
Title (translatable)	Article title displayed in lists and as the page heading.
Slug (translatable)	URL-friendly identifier, translatable for each language.
Content (translatable)	Full article body (HTML content).
Excerpt (translatable)	Short summary shown in article listings.
Meta Title / Meta Description (translatable)	SEO metadata overrides.
Collection	Which KB collection this article belongs to.
Status	draft, published, or archived.
Visibility	public (visible to everyone) or auth_only (requires login).
Position	Sort order within the collection.

Computed Properties

• Reading time: calculated from word count at ~200 words per minute.
• Helpful percentage: ratio of yes votes to total votes (null if no votes).
• View count: incremented each time the article is viewed on the front-end.

Article List

The admin article list is paginated and filterable by status, collection, and search term. Columns: title, collection, status badge, visibility, view count, position.

KB Settings

A separate settings page at HelpCenter → KB Settings controls Knowledge Base display options (see Configuration: Knowledge Base Settings).

Admin: Settings

The settings page (HelpCenter → Settings) is organized into sections:

Ticket Configuration

• Guest access toggle
• Items per page
• Auto-close days
• Allow customer close toggle
• Allow priority selection toggle
• Allow attachments toggle + max size
• Replies order (oldest first / newest first)
• CAPTCHA toggle (integrates with core CaptchaService)
• Response time and unit

Notification Configuration

• Notify admins on new ticket
• Send confirmation to ticket author
• Notify author on new reply

Knowledge Base Configuration

• Guest access / require auth
• Items per page
• Show search / reading time / helpful votes / related articles

Admin: AI Assistant

The AI assistant is available on the ticket detail page and provides context-aware AI actions powered by the Laravel AI SDK.

Available Actions

Action	Description
suggest_reply	Generate a professional reply to a single customer message.
suggest_reply_conversation	Generate a reply based on the full ticket conversation history. The current message is marked with [CURRENT MESSAGE] for the AI to focus on.
suggest_reply_articles	Generate a reply referencing relevant Knowledge Base articles. Up to 5 articles are searched by keyword match and view count.
summarize	Summarize the key points of a customer message.
translate_english	Translate the message into English.
translate_french	Translate the message into French.
make_shorter	Condense a message while preserving its meaning.
custom_prompt	Process the text with a custom instruction provided by the admin.

Agent Configuration

The TicketAiAssistantAgent is configured with:

• Temperature(0.7): balanced creativity and accuracy
• MaxTokens(4096): allows for detailed responses
• The AI model is read from setting('ai_default_model') or falls back to the default provider model

Front-end: Ticket Portal

Routes

Method	URL	Route Name	Auth?	Description
GET	/{locale}/help/tickets/new	helpcenter.create.localized	Guest*	Ticket creation form
POST	/{locale}/help/tickets	helpcenter.store.localized	Guest*	Submit a new ticket
GET	/{locale}/help/tickets/confirmation/{reference}	helpcenter.confirmation.localized	Guest*	Ticket confirmation page
GET	/{locale}/help/tickets	helpcenter.tickets.localized	Yes	My tickets list
GET	/{locale}/help/tickets/{reference}	helpcenter.show.localized	Yes	View ticket detail & conversation
POST	/{locale}/help/tickets/{reference}/reply	helpcenter.reply.localized	Yes	Post a customer reply
POST	/{locale}/help/tickets/{reference}/close	helpcenter.close.localized	Yes	Close a ticket

* Guest access depends on the helpcenter_guest_access setting. Non-localized variants (without {locale}) are also registered.

Ticket Creation Form

The creation form includes:

• Subject: required text field (max 255 characters)
• Department: required dropdown of active departments
• Message: required text area (max 10,000 characters)
• Priority: optional dropdown (only shown if helpcenter_allow_priority_selection is enabled)
• Guest fields: name and email fields (only shown for non-authenticated users)
• Custom fields: all active custom fields are rendered dynamically
• Attachments: file upload (up to 5 files, if attachments are enabled)
• CAPTCHA: shown if enabled via helpcenter_captcha_enabled

Ticket Reference Numbers

Each ticket is assigned a unique reference number in the format HD-00001, auto-generated by the TicketObserver during creation. References are sequential and zero-padded to 5 digits.

Customer Ticket View

The front-end ticket detail page shows:

• Ticket header (reference, subject, status, priority, department)
• Conversation thread: internal notes are filtered out (not visible to customers)
• Reply form for posting additional messages
• Close button (if helpcenter_allow_customer_close is enabled and ticket is not already closed)
• Custom field values

Access Control

• Authenticated users can only see their own tickets (user_id match)
• Admin users can see all tickets
• Closed tickets cannot receive new replies

Front-end: Knowledge Base

Routes

Method	URL	Route Name	Description
GET	/{locale}/help	kb.index.localized	KB home: collections, popular & recent articles, search
GET	/{locale}/help/{slug}	kb.collection.localized	Collection page: articles in collection + child collections
GET	/{locale}/help/article/{slug}	kb.show.localized	Article page: full content + related articles + voting
POST	/{locale}/help/vote/{id}	kb.vote.localized	Vote article as helpful/not helpful (AJAX)

Non-localized variants (without {locale}) are also registered.

KB Index Page

• Search bar: full-text search across article titles, content, and excerpts (if kb_show_search is enabled)
• Collections grid: root-level collections with article counts
• Popular articles: top 5 articles by view count
• Recent articles: 5 most recently published articles

Collection Page

• Collection name, description, and icon
• Paginated list of published articles in the collection
• Child collections (if any)

Article Page

• Full article content with reading time estimate
• Helpful votes (“Was this helpful?” yes/no buttons, AJAX-powered)
• Related articles from the same collection
• SEO metadata (meta title / meta description from article fields or auto-generated)

Visibility & Access

• Public articles are visible to everyone
• Auth Only articles are visible only to authenticated users
• If kb_require_auth is enabled, the entire KB requires authentication

Envato Add-on Integration

When the Envato Market Integration add-on is active, the HelpCenter integrates with it for purchase-based access control.

Department Gating

When envato_helpcenter_require_purchase is enabled:

• The ticket creation form filters the department list to only show departments the user has purchase access to.
• Access is determined by EnvatoPurchaseValidator::getAccessibleEntityIds() using helpcenter_department as the linkable type.
• Departments with no linked Envato items remain unrestricted.

KB Collection Gating

When envato_kb_restrict_by_purchase is enabled:

• Article pages check if the article’s collection has linked Envato items.
• Non-buyers are shown a “Purchase Required” page with the list of required items.
• Unauthenticated users are redirected to the login page.

Ticket Detail Context

The admin ticket detail page shows the customer’s verified Envato purchases in a sidebar panel (if the user has a linked account), giving agents immediate context about what products the customer owns.

Notifications

The add-on sends three types of email notifications:

Notification	Recipient	Trigger	Setting
NewTicketAdminNotification	All admin users	New ticket created	helpcenter_notify_admin_on_new_ticket
TicketConfirmationNotification	Ticket author	New ticket created	helpcenter_notify_author_on_new_ticket
NewReplyNotification	Ticket author	Admin posts a reply (not internal notes)	helpcenter_notify_author_on_new_reply

Updating

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

Step 3: Clear Caches

Step 4: Verify

Visit HelpCenter → Dashboard and confirm ticket listing loads correctly. Check the Knowledge Base front-end page to verify articles are displayed.

Troubleshooting

Ticket creation form shows no departments

• Ensure at least one department exists and is marked as active.
• If the Envato add-on is active with envato_helpcenter_require_purchase enabled, the user must have a verified purchase for a product linked to that department.

Guest users cannot submit tickets

• Check that helpcenter_guest_access is set to true in settings.
• The setting defaults to true but may have been disabled in the admin panel.

Custom fields not appearing on the ticket form

• Ensure the custom field is marked as active.
• Verify the field type is set correctly.
• For select/checkbox/radio fields, ensure the options array is populated.

Notifications not being sent

• Check that the corresponding notification setting is enabled (e.g. helpcenter_notify_admin_on_new_ticket).
• Verify your mail configuration in .env (SMTP, Mailgun, etc.) is correct.
• Check the failed_jobs table for queued notification failures.
• For guest tickets, ensure the guest email address is valid.

AI Assistant returns errors

• Ensure at least one AI provider API key is configured in .env (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY).
• Check config/ai.php for the default provider configuration.
• Verify the laravel/ai package is installed (composer show laravel/ai).
• Check server logs for detailed error messages from the AI provider.

KB articles not showing on the front-end

• Ensure articles have status set to published and published_at is in the past.
• Check visibility: auth_only articles are hidden from guests.
• If kb_require_auth is enabled, unauthenticated users are redirected to login.
• Ensure the article’s collection is marked as active.

PDF export fails

• Ensure the barryvdh/laravel-dompdf package is installed.
• Check that the storage/app directory is writable by the web server.
• If ticket content contains external images, ensure isRemoteEnabled is true (it is by default).

Ticket merge fails

• You cannot merge a ticket into itself: the source and target must be different tickets.
• Ensure you have the helpcenter.tickets.edit permission.
• Check server logs for database transaction errors.

Helpful votes not working

• Ensure kb_show_helpful_votes is enabled in KB settings.
• The vote endpoint (POST /help/vote/{id}) returns JSON: verify that JavaScript is handling the AJAX call correctly.
• Check the browser console for network errors.

Envato purchase gating not restricting access

• Ensure the Envato Market Integration add-on is installed and active.
• Enable envato_helpcenter_require_purchase in the Envato settings.
• Link at least one Envato item to the department or KB collection you want to restrict. Entities with no linked items are always unrestricted.