Configuration

Navigate to Tickets → Settings in your WordPress dashboard. Settings are organized across eight tabs.

Tab 1: General

Setting Description Default
Custom Priorities Comma-separated list of priority levels Low, Medium, High
Default Priority Priority assigned to new tickets Medium
Custom Statuses Comma-separated list of workflow statuses Open, In Progress, Resolved, Closed
Default Status Status assigned to new tickets Open
Resolved Status Triggers the auto-close countdown Resolved
Closed Status Disables further client replies Closed
Re-Opened Status Assigned when a client re-opens a closed ticket Open
Auto-Close Days Days after “Resolved” before automatic closure (0 = disabled) 3
Max Upload Size Maximum file size per upload in MB 5
Max Files Per Upload Maximum number of files per submission (0 = unlimited) 5
SLA Warn Hours Hours before a ticket is flagged as an SLA warning 0 (disabled)
SLA Breach Hours Hours before a ticket is flagged as an SLA breach 0 (disabled)
Restrict Technicians When enabled, technicians only see tickets assigned to them Off
Portal Theme Auto follows prefers-color-scheme; Force light mode pins the portal to light Auto

Tab 2: Assignment & Routing

Setting Description
Default Assignee Technician automatically assigned to every new ticket
Fallback Alert Email Receives new-ticket and client-reply notifications when no assignee is set
Helpdesk Page The page clients land on when clicking their portal link. Use the [helpdesk_portal] page if you have a dedicated portal, or the [submit_ticket] page for a combined layout. All portal links in emails point here.

Auto-assignment rules let you route tickets to specific technicians based on category. Add one or more rules mapping a Category to an Assignee. The first matching rule wins; if no rule matches, the default assignee is used.

Email routing priority (when sending admin notifications):

  1. The ticket’s assigned technician
  2. The default assignee (if set)
  3. The fallback alert email (if set)
  4. The site admin email

Tab 3: Email Templates

Customize the subject line and body of every email the plugin sends. Click Reset to default below any template to restore the original text.

Available placeholders:

Placeholder Value
{name} Client’s name
{email} Client’s email address
{ticket_id} Unique ticket ID (e.g. TKT-0001)
{title} Ticket title / summary
{status} Current ticket status
{priority} Current priority level
{message} Message body
{ticket_url} Secure client portal link
{admin_url} WordPress admin edit link (technicians only)
{autoclose_days} Configured auto-close threshold

Conditional blocks:

Wrap any template section in {if key}...{endif key} to include it only when that placeholder has a non-empty value:

{if message}
Message: {message}
{endif message}

Unreplaced placeholders are automatically removed from the final output.

Email events (14 templates, 8 client-facing + 6 admin-facing):

Sent to client:

  • New ticket received (confirmation)
  • Technician replied
  • Status changed (no reply)
  • Technician replied + status changed (combined)
  • Ticket resolved
  • Ticket re-opened
  • Ticket auto-closed
  • Ticket closed by client (confirmation)

Sent to technician/admin:

  • New ticket submitted
  • Client replied
  • Client re-opened ticket
  • Client closed ticket
  • Ticket assigned to technician
  • Ticket auto-closed (admin copy)

Email branding: The header band displays your site logo (configured via Logo URL in Tab 3) and site name. If no logo URL is set, the site icon is used as a fallback (at 32×32 px). All CSS is inlined for email client compatibility.

Send Test Email: Click Send Test Email to send a sample message to the currently logged-in admin. The result is shown inline without a page reload.

Tab 4: Messages

Customize the front-end text shown to clients after form actions:

Message Key When Shown
Success — New Ticket After a ticket is successfully submitted
Success — Reply Sent After a client reply is sent
Success — Ticket Closed After a client closes a resolved ticket
Success — Ticket Re-Opened After a client re-opens a closed ticket
Error — Spam Check Failed Anti-spam validation failed
Error — Invalid Token Ticket portal URL is invalid or expired
Error — General Catch-all for unexpected errors

Tab 5: Anti-Spam

Method Description
None No anti-spam protection
Honeypot Invisible hidden field; catches basic bots with no user friction
Google reCAPTCHA v2 “I’m not a robot” checkbox; requires Site Key + Secret Key
Cloudflare Turnstile Privacy-friendly CAPTCHA alternative; requires Site Key + Secret Key

For reCAPTCHA and Turnstile, paste your public Site Key and private Secret Key into the respective fields. The widget renders automatically on the frontend form.

Protection applies to: the ticket submission form, the ticket lookup form, and the portal reply/close/reopen forms.

Tab 6: Canned Responses

Pre-written reply templates that speed up ticket responses.

  • Click + Add Response to create a new template.
  • Enter a Title (visible only in the selector) and a Body (inserted into the reply field).
  • Save via the main Save Changes button.

To use a canned response in a ticket, open the ticket editor, click the Canned Response picker in the conversation section, and select a template. The body is inserted into the active reply field.

Tab 7: Templates

Pre-configured submission types that pre-fill the ticket description field when a client selects them on the frontend form.

  • Click + Add Template to create a new request type.
  • Enter a Label (shown as the option name in the dropdown) and a Description (the pre-filled text).
  • Save via the main Save Changes button.

When templates are configured, the submission form displays a Request Type dropdown. Selecting an option populates the description field with the corresponding template body, which the client can then edit before submitting.

Tab 8: Tools

Automated Data Retention

Setting Description Default
Attachment Retention Days Delete physical files older than N days (0 = disabled) 0
Ticket Retention Days Delete entire tickets inactive for N days (0 = disabled) 0

Retention jobs run hourly in micro-batches to avoid server timeouts.

Uninstallation

Check Delete all plugin data on uninstall to permanently remove all tickets, attachments, and settings when the plugin is deleted from WordPress.

Danger Zone

Action Effect
Purge All Tickets Permanently deletes every ticket and its attachments
GDPR Email Purge Deletes all tickets, replies, and files associated with a specific email address
Factory Reset Resets all settings to defaults; does not delete tickets

Toast Notifications

After saving settings, a toast notification slides in from the bottom-right corner confirming the save. It auto-dismisses after ~4 seconds and can be closed immediately with the × button.

The swhToast(message, type, duration) function is available globally on any page that loads swh-admin.js:

Parameter Type Default Description
message string — Text to display
type 'success' | 'error' | 'info' 'success' Visual variant
duration number 4000 Auto-dismiss delay in ms

The ?swh_notice=saved redirect query parameter triggers the toast on page load. The parameter is removed from the URL via history.replaceState() so a page refresh does not re-trigger the notification.

Dark Mode (v3.6.0)

Simple WP Helpdesk renders cleanly in dark mode in three places:

Frontend (client-facing)

The submission form, client portal, My Tickets dashboard, and lookup form follow prefers-color-scheme: dark. No setting required — the browser/OS preference is honoured automatically.

If your site forces light mode (no theme-level dark support, brand reasons, etc.), set Settings → General → Frontend Portal Theme to Force light mode. This emits data-swh-theme="light" on every .swh-helpdesk-wrapper and overrides the dark media query.

Admin (staff-facing)

Admin pages now follow each user’s WordPress Profile → Color Scheme preference. Three of the built-in WP schemes are treated as dark and trigger SWH dark mode:

  • Midnight
  • Modern
  • Ectoplasm

All other schemes (Default, Light, Blue, Coffee, Sunrise) render SWH admin in light mode, matching the surrounding chrome. There is no plugin-level setting — switching color schemes in the user profile is the single source of truth.

Implementation: swh_admin_color_is_dark() (in includes/helpers.php) inspects get_user_option( 'admin_color' ) and adds swh-admin-theme-dark to <body> on Settings, Reports, and the ticket list. CSS overrides live under body.swh-helpdesk-admin.swh-admin-theme-dark in swh-shared.css (token overrides) and swh-admin.css (component overrides).

Email

Emails opt in to client dark mode via <meta name="color-scheme" content="light dark"> and a @media (prefers-color-scheme: dark) block emitted by swh_wrap_html_email(). Apple Mail (macOS / iOS) honour the directive and recolour backgrounds, text, and accent borders. Webmail clients that strip <style> tags fall back to the inlined light theme — readable in both modes.

Accessibility (v3.6.0)

v3.6.0 closes the WCAG 2.2 AA gaps surfaced during the v3.5.0 audit.

Keyboard navigation

  • Skip-to-content link on Settings and Reports pages — the first focusable element on each page is “Skip to main content”, which jumps over the WP admin chrome.
  • :focus-visible focus rings — the high-contrast --swh-color-focus outline is now only shown for keyboard navigation, not mouse clicks. Mouse users get clean buttons; keyboard users keep clear focus state.

Focus management

  • CSAT widget — submitting a satisfaction rating moves focus to the “Thanks for your feedback” success message so screen-reader users hear confirmation. Pressing Esc dismisses the widget and returns focus to its trigger.
  • Portal token expiry — when a portal link has expired, focus moves to the lookup form so users know where to recover their access without re-tabbing past the error notice.

Live regions

  • SLA badge transitions (none → warn → breach) and KPI card value updates announce via aria-live="polite".

Touch targets (WCAG 2.5.5 AA)

The following controls now meet the 44×44 CSS-pixel minimum:

  • CSAT rating stars
  • Merge ticket toggle — uses a transparent ::before hit-zone overlay so the visible button stays at WP’s 28 px height while the touch zone extends to 44 px.
  • Status filter chips on the admin ticket list — render as inline-flex pills with min-height: 44px.

WP-default subsubsub list views are intentionally unchanged.

Headings

A heading-hierarchy audit eliminated skipped levels and duplicate h1s across portal and admin views. The shared swh_render_empty_state( $title, $desc, $icon_svg_path, $heading_level = 'h2' ) helper in includes/helpers.php lets every “nothing here” surface emit the right heading level for its surrounding context.

Contrast

Internal-note text on the amber background was bumped from AA (4.5:1) to AAA (7:1) per #348.