Link Robins Support — Private support tickets

KBExit

Link Robins Support — private support tickets

A help-desk extension that I'm releasing publicly. It adds a private support-ticket system to Flarum with first-class support for ban appeals.

Why not just use discussions?

Tickets need stricter visibility than Flarum's discussion model gives you. The owner sees their own ticket; staff see everything; nobody else sees anything at all -- not even the URL works. With discussions this would be doable but every interaction (replyCount, "last reply by", search results, notifications) leaks something. As a separate domain it's clean.

What's in 1.0.0

The basics: admin-defined categories, a ticket page with replies, status workflow (open → in_progress → awaiting_user → resolved → closed) that auto-advances based on who replied, decisions on appeal tickets, assignment to staff.

Internal notes for staff coordination. They're filtered at the database level for non-staff -- the owner doesn't see them in the reply list, can't fetch them directly, and the replyCount excludes them from the owner's perspective. No notification fires for an internal note.

Appeal flow. A category flagged is_appeal gets stricter rate limits AND a special interaction with the Suspend extension: suspended users CAN'T file general tickets (so they can't use support as a chat workaround) but CAN file appeals (so they can actually plead their case).

Rate limits per user. Default 3 appeals per 30 days, 1 concurrent open appeal, 10 general tickets per 24 hours. All admin-configurable; set to 0 to disable any individual limit.

Permanent appeal-ban. A separate per-user flag for the case where someone is wasting your time with appeals. Blocks appeals; leaves general tickets available. Admin UI in the extension page.

Notifications. In-app + email. Owner gets notified when staff replies; staff get notified for new tickets and owner replies. Standard NotificationGrid preferences so each user can toggle drivers.

File attachments. If you already have fof/upload installed, the compose and reply forms get an "Attach files" button. Soft dependency -- no requirement to install it; the button just doesn't appear if fof/upload isn't there. Files go through fof/upload's normal pipeline (storage, mime validation, size limits, permissions).

Permissions

One permission: linkrobins-support.handle_tickets. Anyone in admin bypasses it. Default assignment is the moderate group. Anything goes.

Security notes

Tickets/replies have anti-impersonation via two layers: the JSON:API schema doesn't declare user as writable (so spoof attempts get a clean rejection), and the creating() hook overwrites user_id with the authenticated actor regardless.
Visibility scoping lives in BOTH the resource scope() (Show) and the Searcher getQuery() (Index), with identical rules. Removing either one wouldn't open a hole -- both are required by Flarum 2's pipeline -- but it's worth understanding that they're paired.
The reply Index applies WHERE is_internal_note = false for non-staff at the database level. Internal notes don't enter the response shape at all.

What's NOT in 1.0.0

Public/canned responses. Staff can use the regular reply form. (Can add if enough demand)

Install

composer require linkrobins/support
php flarum migrate
php flarum cache:clear

Then enable in admin → Extensions and configure categories.

Source

GitHub: linkrobins/support
Packagist: https://packagist.org/packages/linkrobins/support

MIT licensed.

KBExit

huoxin

Wlork

ram0ng1

Wlork

I don't have time to try it today, but it's exactly what I was looking for ! Thank you so much for all your hard work !

🙂

huoxin

I think you should use flarum CLI to create/init the extension first before letting AI to start implementing the features, or if not let AI use the CLI and go through the init process, otherwise the extension structure can end up incomplete or inconsistent. For example, your extension are using uncompiled js directly and not utilizing the checks via the github actions workflow.

KBExit

huoxin I'll look into that. I've been using Claude with access to a local Flarum container so it can extensively test, audit, and fix the code as it builds — which is how the gnarlier backend edge cases got covered. The CLI / build-pipeline side is the gap; I'll add CI at minimum and consider porting to the scaffold for the next major version.

ram0ng1

Thanks for the extension @KBExit!

Is there a possibility for the following features:

Assignment & Notifications: If a user opens a ticket, can it be assigned to a moderator/administrator? If assigned, can they be notified, and would the flarum/realtime integration trigger a toast notification?
Realtime Messages: Can the ticket messages themselves integrate with flarum/realtime?
Email Replies: Is it possible to reply via email and have that response show up correctly in the ticket? (Similar to how GitHub Issues works).
Convert Tags: Is there a possibility to turn existing Flarum tags into tickets?
Guest Tickets (Email-only): Can a user open a ticket without an account (using just their email, handling everything through email)? I'm asking because users usually don't want to create an account, let alone go through 2 or 3 steps just to open a support ticket, hahaha.

In the case of opening a ticket without an account (email-only), the system should automatically create a user profile in the dashboard assigned to that specific email. This way, if the user decides to sign up later using that same email, the system recognizes it and links all previously opened tickets to the newly created account so they can view their ticket history.

KBExit

ram0ng1

ram0ng1 Assignment & Notifications: If a user opens a ticket, can it be assigned to a moderator/administrator? If assigned, can they be notified, and would the flarum/realtime integration trigger a toast notification?

The member would assign it to themselves. If you want, I can see about auto assign and see about implementing additional features.

ram0ng1 Email Replies: Is it possible to reply via email and have that response show up correctly in the ticket? (Similar to how GitHub Issues works).

Because everyone's email configuration is different, I am refraining from shipping this as a feature. I'm sorry.

ram0ng1 Convert Tags: Is there a possibility to turn existing Flarum tags into tickets?

Due to this extension also being requested for Ban Appeals, I decided on accomplishing this extension as a separate entity, like my blog extension, to not over complicate default Flarum behaviors.

ram0ng1 Guest Tickets (Email-only): Can a user open a ticket without an account (using just their email, handling everything through email)? I'm asking because users usually don't want to create an account, let alone go through 2 or 3 steps just to open a support ticket, hahaha.

I'll look into this, but no promises.

Wlork

ram0ng1 Guest Tickets (Email-only):

KBExit I'll look into this, but no promises.

I think we should create a separate extension for guests. Something like a button that appears at the bottom corner...

We must not make this extension too heavy or complicated. It should be an internal tool, designed primarily for members. Some sites don’t want to be inundated with requests from guests 🙂

KBExit

Wlork the current implementation works for your use case I believe.

Wlork

KBExit Yes, thank you.

I was responding to his suggestion; I’m not in favour of it 🙂

ram0ng1

KBExit Because everyone's email configuration is different, I am refraining from shipping this as a feature. I'm sorry.

I believe that regardless of the user's email configuration in Flarum, there must be a way to configure POP/IMAP for a reply-to email address.

I actually started something similar, although I haven't published it or run the necessary tests yet:

ram0ng1/mail-reply

I will continue the implementation and testing to move forward with this feature.

KBExit

ram0ng1 there are limitations to emails depending on which route you take. You should look into why Ghost uses Mailgun explicitly for example.

ram0ng1

KBExit

Yes, I remember using Ghost, and at first, I was frustrated because I wanted to use my own email provider. However, I eventually accepted it since I didn't have a high volume of emails.

Even while understanding limitations such as:

Reputation and Deliverability: Sending hundreds or thousands of emails at once using your host's default SMTP will instantly get your domain and IP flagged as spam by major providers (Gmail, Outlook).
Specialized Infrastructure: Mailgun is optimized to handle IP reputation, delivery rates, and technical authentication (SPF, DKIM, and DMARC), ensuring your emails land in the inbox instead of the junk folder.
Technical Limitations: Transactional emails (like password resets) are sent one by one and work fine with a simple SMTP setup. Bulk emails, on the other hand, require API protocols.

Ghost Docs

KBExit

ram0ng1 if anything, I can entertain the idea of a separate smtp configuration just for this to allow email replies.

huoxin

filed an issue for updating of assign status: linkrobins/support1
Also do you think we should allow admin and mod to edit their own reply? This would be possible naturally if you build it on top of the post and discussion system of flarum but not sure if it should be done this way as there are quite a lot of other features introduce to the editor and post system by other extensions
If not it feels like you will need to build the diff extension again for this ticket system?

ram0ng1

Wlork I agree with you on that! I honestly hadn't thought about it.

KBExit

huoxin linkrobins/supportreleases/tag/v1.0.1

Changelog

Fix: mobile sidebar dropdown showed only the caret arrow with no title when viewing a ticket or composing. Flarum's SelectDropdown derives its toggle button label from the first child item that has active: true. On the ticket detail and compose pages, the sidebar is rendered with activeFilter: null because the user isn't viewing a filter list -- which means none of the filter items match as active, and the dropdown had nothing to show. Now passes defaultLabel: 'Support' to SelectDropdown, which is the fallback Flarum's component uses when no child is active. On filter routes (/support, /support/status/open, etc.) the active filter's label still wins, matching how Flarum's own /all and /tags pages behave.
Restored the "Support" link in the main sidebar on support pages. Previously suppressed on support routes on the theory that the support extension's own sidebar already showed a "Support" link below. But that reasoning didn't hold up: the support sidebar's items are filter links ("My tickets", "All", "Open", ...), not a generic "Support" entry. Hiding the main-sidebar Support link only made it harder to leave a filtered route view -- the link is the obvious "go home" affordance and should stay. The unused isSupportRoute() helper that supported the suppression has been removed.
Fixed desktop pages rendering too wide. Inside PageStructure, the outer .Page-container.container already applies Flarum's standard responsive max-width (768px tablet / 992px desktop / 1100px desktop-hd) and reserves the 190px sidebar offset. The support pages were applying .container AGAIN on the inner content div, which set a second fixed width that didn't account for the sidebar offset -- so the content extended past the right edge of the page chrome and looked stretched compared to other Flarum pages. Stripped the redundant .container from all six places (index, three compose branches, two show branches) so the inner div sits cleanly inside .Page-content with flex: 1 width like Flarum's own discussion pages.
Suppress flarum/tags's per-tag list on support pages. The tags extension contributes both a "Tags" link AND a long enumerated list of every tag to Flarum's IndexSidebar.navItems(). On a support page, the per-tag list crowded the support's own filter list. We now set app.current.set('noTagsList', true) in every support page's oninit -- the tags extension reads this flag at navItems render time and skips emitting the per-tag list. The standalone "Tags" link is unaffected, so users can still jump to /tags. Also a defense-in-depth strip of the separator item the tags extension emits just before its tag list, in case noTagsList doesn't take effect for some reason.
Shorter "Awaiting response" label. Previously "Awaiting your reply" in the status badge and "Awaiting user" in the filter sidebar -- two phrasings for the same state. Now both render as "Awaiting response". The internal status constant remains awaiting_user so no database / API change is needed; only the display label changes.
Status and assignment stack into their own rows on mobile. On desktop, the staff bar inside a ticket has the status setter on the left and the assignment row on the right, separated by a vertical divider and pushed apart with margin-left: auto. On phones (max-width: 767px) those two blocks now stack vertically: status setter on top, assignment row below, separated by a thin horizontal divider. Each block takes the full width so the dropdown and Claim/Unassign buttons don't fight for horizontal space.
Remove the back arrow on the ticket title header. The arrow used to sit at the start of the title row on a ticket detail page. The 1.0.2 sidebar already provides primary navigation (My tickets, All, Open, In progress, ...) and the browser back button covers the remaining case, so the arrow was just visual noise on top of those. The error-state header (when a ticket fails to load) and the compose page still have their back buttons -- those are degenerate states where the sidebar might not be obviously usable.
Sidebar nav for filters. "My tickets", "All", "Open", "In progress", "Awaiting user", "Resolved", and "Closed" are now sidebar nav items rather than a horizontal row of pill buttons inside the page body. The sidebar uses Flarum's standard PageStructure + IndexSidebar infrastructure, so on mobile it collapses into the same SelectDropdown menu Flarum uses for its own index pages, and the sidebar is positioned alongside the content on desktop the same way the forum's main sidebar is. Non-staff users only see "My tickets" (the only filter the backend allows them anyway); staff see the full list. The previously-inherited "All Discussions", Tags, and other forum sidebar items render below the support items, so users can still get back to the forum from anywhere inside the support extension.
Each filter is a distinct URL. Previously the active filter was internal state on the page; clicking pills mutated a local variable. Now each filter has its own URL: /support for My tickets, /support/status/open for Open, /support/status/resolved for Resolved, and so on. The benefits: filter selections are bookmarkable and shareable, the browser back button works between filters, and LinkButton's built-in active-state detection highlights the current filter automatically. The IndexPage watches for route attr changes via onbeforeupdate and re-fetches when the filter changes (Mithril doesn't re-run oninit when only attrs change for the same component class, so we have to detect this explicitly).
"New ticket" moves to the sidebar. Previously a button in the page header next to the "Support" title. Now it's a primary button at the top of the sidebar, mirroring the blog's "Compose" button placement. The header still shows the page title (e.g. "Open" on /support/status/open, "Support" on /support) but no longer carries an action button. The button uses Flarum's App-primaryControl itemClassName so it gets the prominent treatment Flarum reserves for primary sidebar actions.
Sidebar visible on every support page. The sidebar renders on the index page, on the new-ticket compose page, AND on individual ticket detail pages. This means staff can jump between filters or open a new ticket from inside any ticket without having to navigate back to the index first. On a ticket detail page no filter is shown as active, since the user is viewing a specific ticket rather than a filtered list.
Status setter is now a dropdown. The horizontal row of buttons ("Open | In progress | Awaiting user | Resolved | Closed") on the staff bar inside a ticket detail page is replaced by a <select> dropdown. Picks up less horizontal real estate, reads as one decision rather than five competing buttons, and the dropdown shows the current status as the selected value so there's no need for a separate "active" indicator. The assignment row (Claim / Unassign) is unchanged.
Forum-side "Support" sidebar link suppressed on support pages. Previously the forum's main IndexSidebar showed a "Support" link on every page, including support pages themselves. Now the link is hidden when the current route is inside the support extension, since the support's own sidebar already renders a richer filter list there and a duplicate generic link would sit awkwardly alongside it. The link still appears on /, /all, /d/..., etc, so the page remains discoverable.
New server-side route declaration. Added /support/status/{status} route to extend.php. Flarum needs server-side route registration to serve the SPA shell for a given path; without it, requests for /support/status/open would 404 before client-side routing could pick them up. Route ordering matters: more-specific paths come before the catch-all /support/{id} to avoid :id swallowing the status segment.
Fix: notification dropdown crashes when a support notification is present. Loading any notification that referenced a support ticket threw Class constructor a cannot be invoked without 'new' in the browser console, which then prevented the entire bell-icon dropdown from rendering — so the user couldn't see ANY of their notifications (including non-support ones) until the support notifications were cleared. The cause was the way we registered our SupportTicketModel on Flarum's store. The code used the old ES5 prototype-chain inheritance pattern (Model.apply(this, arguments) + Object.create(Model.prototype)) to subclass Flarum's Model. Flarum's Model is a modern ES6 class, and ES6 classes can only be subclassed with class X extends Y syntax — V8 throws synchronously if you invoke a class constructor without new, which is exactly what the old pattern does. Switched to class extends Model {}, which is what the rest of this codebase already uses for other classes. This has nothing to do with real-time / Redis / Horizon; it was a pure JS class-instantiation error in the store hydration path.
Fix: assignment label says "Unassigned" after assigning a staff member. Clicking the "Assign to me" / "Assign to X" button on a ticket sent the PATCH and the server correctly persisted the new assignment, but the UI label kept showing "Unassigned" until the page was reloaded. Cause: updateTicket() sent the PATCH without ?include=user,category,assignedStaff. JSON:API specifies that without an include directive, the server is not required to return related resources, and Flarum doesn't include them. So the response carried the updated relationships.assignedStaff.data.id but no users resource in included, and the label-rendering helper relatedAssignedStaff(ticket, included) returned null. Fix: PATCH now requests the same includes as the initial GET, so the response always contains the user record needed to render the label.
Feature: staff replies auto-claim unassigned tickets. When a staff member (admin or anyone with linkrobins-support.handle_tickets) posts a reply or internal note on an unassigned ticket, that ticket is now automatically assigned to the replier. This matches the natural flow: if you're answering a ticket, you're handling it. Behavior details:
- Only fires when assigned_staff_id is currently null. Existing assignments are NEVER overridden — if Alice is handling a ticket and Bob posts a single reply, the ticket stays Alice's. This protects the "second pair of eyes" case where one staff member is the owner and another pitches in for a single comment without taking the ticket over.
- Internal notes also trigger auto-claim. The reasoning is that an internal note on an unowned ticket is effectively staff picking it up. (Internal notes do NOT trigger the status bump — those stay separate concerns: status reflects the user-visible conversation state, assignment is staff routing.)
- Implemented in the existing SupportReply::created listener in SupportServiceProvider, where the status-bump logic already lives. No additional listeners or queries.

Wlork

KBExit

Thank for big update ! I see some CSS issues. I will do screenshot tomorrow 🙂

Wlork

Wlork Thank for big update ! I see some CSS issues. I will do screenshot tomorrow 🙂

@KBExit I had a GitHud :

linkrobins/support2

I’m not sure if I’ve spotted all the issues, so please feel free to check for yourself 🙂 In the meantime, the most significant issues are listed.

And i have a suggestion : it would be useful if the administrator/moderator could delete the ticket