Agent UI

better-helpdesk/admin exports the agent UI, HelpdeskAdmin, and two constants. The module starts with 'use client'. The UI calls the agent/* routes, which answer only an agent. Related guide: Theme the widget and the agent UI.

import { HelpdeskAdmin } from 'better-helpdesk/admin';

export default function Page() {
  return <HelpdeskAdmin api="/api/helpdesk" basePath="/helpdesk" locale="en" />;
}

PropsCopy Anchor Link

ExportsCopy Anchor Link

Sections and URLsCopy Anchor Link

Each screen is a path under basePath; inbox filters are in the query string.

A section that features switched off has no tab, and a link into it lands on the inbox. The same goes for audit when the agent may not read the log: once any agent has the supervisor role, only supervisors see it. A host that renders its own tabs from HELPDESK_SECTIONS can hide that tab by the auditLog field of GET agent/me.

The inbox list reads inbox, status, assignee, q, tag, tier, channel, sort, priority and days from the query string. status is one of the statuses, any, snoozed, rated-good or rated-bad; assignee is me, none or an agent id; sort is empty for longest waiting, priority, or sla for the nearest deadline, which the tray offers once the config has service levels. A row shows its tier and how long until its deadline, or how far past it. days is 7, 30 or 90, the Statistics periods: it keeps conversations resolved in that time for status=resolved, rated in it for rated-good and rated-bad, and opened, resolved or rated in it otherwise, so each figure on Statistics opens the conversations it counts. The All, Assigned to me and Unassigned counts are of the list the other filters give. Changing a filter keeps the open conversation open.

The bar above the list is one line: the assignee tabs, the search with the High and urgent switch beside it, which keeps the two highest of your priorities, a Filters button and New conversation. Saved views are a second row of tabs under the bar, styled like the assignee tabs, each with its count. The button opens a tray with the status, inbox, assignee, tag, tier, channel and sort filters and the period, and a footer with the work-the-queue switch on the left and, on the right, Reset view once any filter is set, the link to save the current filters as a view, the default Open list included, and Rename and Delete for the active view. The tray opens only from the button; a filter set elsewhere, by a saved view or a tag on a row, shows as a count on it. The bulk bar under a selection also offers Reply to all and Note on all, one text written to each selected conversation, with the same formatting toolbar as a reply; a reply to all assigns each unassigned conversation to the agent. A viewer sees a line at the top saying they can change nothing: no checkboxes and no bulk bar, no New conversation button, and in a conversation the properties as text instead of controls and no composer. Beside an open conversation the search and High and urgent move into the tray too. On a wide screen the list and the thread each scroll inside their own pane, so opening another conversation never moves the page, the two panes fill the window below whatever your app shows above them, so the reply box stays in view, and the list keeps its width when the side panel opens or closes; on a narrow one a conversation opened from deep in the list scrolls into view by the least amount. Agent emails link to {adminUrl}/conversations/{id}/, which opens the agent UI when adminUrl is the URL that basePath is mounted at.

Keyboard shortcutsCopy Anchor Link

? opens the list of shortcuts in the UI. Single-key shortcuts, ? among them, do not fire while focus is in a text field, while a dialog is open, during IME composition, with Cmd, Ctrl or Alt held, or when they are switched off. Mod is Cmd on a Mac and Ctrl elsewhere.

PreferencesCopy Anchor Link

Each agent's switches are kept in that browser's localStorage.

CSS custom propertiesCopy Anchor Link

The agent UI renders into the host page, not a shadow root, and inherits the host's font. It reads these properties from any ancestor.

The widget's own properties are on Widget.