AgentLayer▸docs
Connect it

Helpdesk

Your support queue in SupportCandy or Pylon, worked the way your team works it. The agent reads, sorts and drafts; a person sends every reply. A queue profile per project holds its own pulse, bug lifecycle, routines and context.

In short

The helpdesk skill reads your SupportCandy or Pylon queue, ranks what needs a person, and drafts replies as private notes that a person sends. Start with the access walk in Switch it on, then ask "what's in the support queue?".

Support is a queue of people waiting on you. The helpdesk skill keeps it moving: a pulse that ranks what needs a person now, the story of any ticket, a reply drafted in your team's voice, and the bugs, feature requests and tasks behind tickets raised where your team tracks them. Ask in plain words ("what's in the support queue?", "pull ticket 318", "draft a reply for 318", "raise 318") or run the helpdesk skill by name.

The agent reads, sorts and drafts. A person sends every reply. It writes two things in the helpdesk:

  • A private note, which agents see and the customer never does, so a draft or a finding waits there for someone to edit and send.
  • A SupportCandy ticket's assignee, so the ticket reaches the person who takes it.

Each waits for your yes unless a routine of yours says otherwise (Routines that don't ask). Nothing replies to a customer, changes a ticket's status or closes it.

What it gives you

AskPlaybookYou get
"What's in the support queue?", helpdesk pulsepulseOpen tickets ranked (unassigned and longest-waiting first), patterns across them, tickets to raise, the replies your raised cards now call for, the app's App Store reviews when the profile names it, and a saved report
"How many tickets came in today?", helpdesk statsstatsCounts of the tickets updated in the last 24 hours (or the window you name): by status, by tag, unassigned and newly opened, for one queue or all of them
"Pull ticket 318", helpdesk ticket 318ticketThe story so far: what the customer asked, what support said, internal notes apart, who's who, what's still open
"What's open for Acme?", helpdesk account acmeaccountOne customer company's tickets (Pylon)
"Draft a reply for 318", helpdesk draft 318draftA reply in your queue's tone, left as a private note once you approve it
"Any App Store bug reports?", helpdesk reviewsreviewsNew App Store reviews read for bugs at every star rating, each bug gathered with its cards, tickets and older reviews into one card, or a comment on the card already open. In a helpdesk queue
"Raise 318", helpdesk raise 318 (helpdesk bug 318 for a bug)raiseThe ticket as a bug, a feature request or a task, wherever your profile sends that kind: a task, or a GitHub card with the repro, a log excerpt and the screenshots
"Set up helpdesk for acme-shop", helpdesk setup acme-shopsetupAccess first when there's no connection it can read, then the interview that writes or tunes its queue profile
A routine your profile defines, helpdesk digestworkflowWhatever that routine's steps produce

Tickets come back with the people on them: the customer, the assignee, and each message's author, with names and emails where the helpdesk gives them. That's how the agent finds the account, reads the history and answers by name. They stay in your home: a GitHub card links the ticket instead of copying anyone's contact details.

The playbooks run on nine helpdesk_* tools, listed on MCP tools. A ticket read tags each message as customer, agent, note or event. An assignment reads the ticket back and fails when the assignee didn't change.

What it needs

HelpdeskNeedsCost
SupportCandy, the WordPress pluginA dedicated WordPress user with an application password, on an HTTPS siteFree; the REST API is in the free plugin
PylonAn API token a Pylon admin creates under Settings → API. It reads the whole workspace, and notes are posted as the token's userPart of your Pylon plan

Raising a ticket as a GitHub card also needs the GitHub pack.

Switch it on

Two steps set a queue up, and either one leads to the other:

configure-skills → Helpdeskhelpdesk setup <project>
Sets upAccess: which helpdesk, a connection for each project's site or workspace (or one for no project), the keys and the tool grantsThe queue: an interview that writes the project's queue profile
How oftenOnce per site or workspaceOnce per project, then again to tune it

Saying "set up helpdesk for acme-shop" starts with setup, which runs the access walk first when there's no connection it can read: none at all, or none for the project and no default.

Run the access walk

Run configure-skills and pick Helpdesk. It asks which helpdesk you use, which project each connection is for, and what the agent may do: read tickets, leave notes and assign (recommended), or read only.

Prepare the site (SupportCandy)

As a WordPress admin, on the site:

  1. SupportCandy → Settings → Advanced → turn on REST API. While it is off, every call returns 404.
  2. Add an agent role that can view tickets and view and add private notes, and nothing else. SupportCandy checks reply and private-note rights separately, so this role can leave notes but cannot answer a customer. For the agent to assign tickets too, tick Assign Agents for the tickets it should hand off (unassigned, and assigned to it).
  3. Add a dedicated WordPress user under SupportCandy → Agents with that role. Never a person's own login: every note is attributed to this user.
  4. Keep the API out of the page cache (below).
  5. Create an application password for the user (Users → the user → Application Passwords).

Add the keys

The walk saves the site address and username for you. The password, or a Pylon token, goes in your editor, never in chat:

# <HOME>/.claude/settings.local.json env
SUPPORTCANDY_URL=https://help.example.com
SUPPORTCANDY_USERNAME=support-assistant
# <HOME>/.state/secrets/.env
SUPPORTCANDY_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
PYLON_API_TOKEN=pylon_...

Relaunch and check

New keys load at the next session, so the rest picks up after a relaunch. Start your host again from the home and ask "list helpdesk tickets from the last day".

Set up each project's queue

Run helpdesk setup <project>. The interview writes the queue profile.

Keep the API out of the page cache

A caching plugin with REST caching on saves the answers to the agent's reads and serves them to anyone who requests the same address, login or not, because the application password travels in a header rather than a cookie. Reads go stale, and the ticket list is readable without a login.

In LiteSpeed Cache, turn off Cache → Cache REST API, or add /wp-json/supportcandy/ to Excludes → Do Not Cache URIs, then purge. To check, request the ticket list with no login: 401 is right, 200 means the cache is serving it.

Several sites or workspaces

A connection is one SupportCandy site or one Pylon workspace, and it usually serves one project's support. The access walk asks which project each connection is for:

  • A project's connection is named after its slug. Every key it uses carries that name as a suffix, in capitals with anything but letters and digits as _.
  • No project is the default connection, on the plain keys above.

The example below shows the suffixed keys, and how a call picks its connection.

A queue profile

Each support queue gets a profile in the project its tickets belong to: projects/<slug>/helpdesk.md. The plugin ships a default workflow. A profile changes it for that queue, and nothing in the plugin needs to change.

The interview writes it for you; open these to see a whole profile, or to look up what a key or a section does.

Rules for every queue go in the home's helpdesk extension, extensions/skills/helpdesk.md (Extending a plugin skill): an organisation's defaults, plus boundaries no profile can loosen.

The interview

You don't write the profile by hand. helpdesk setup interviews you in six rounds, shows the default at each step, and takes "the default" as an answer:

  1. The queue: the project, the connection, which statuses count as open, how often the pulse runs, and the app's App Store link if it has one.
  2. The pulse: what needs a person first, what to collapse into a count, what else to check, who reads it.
  3. Raising: where bugs, feature requests and tasks go, the lifecycle (starting from the default), what a card carries and never carries.
  4. Replies: tone, language, sign-off, what is never promised, what a person writes.
  5. Context: the product and its versions, help links, known issues, the team, escalation.
  6. More routines: a weekly digest, a review sweep, anything else recurring, and whether each one's notes and assignments go ahead without asking.

Run it again to tune one part: it shows what the profile holds and changes only the rounds you pick. A seed bundle carries the profile with the project, so a teammate's agent starts out knowing the queue.

The default bug lifecycle

A raised card moves through six states from triage to closed, and the pulse drafts a reply at each state where support has a part.

Routines that don't ask

Every write waits for your yes by default. A routine can lift that for its own private notes and assignments, so a sweep that reads each new ticket, leaves a note and hands the ticket to a person runs without a yes per ticket:

## Workflow: sweep
1. Every Open ticket that's unassigned gets a private note and is assigned to Ada. Write the notes and assign the tickets without asking.
2. A ticket with no text of its own: read the attached log. The note's first line says "Look at this" or "Safe to archive", and why.
3. End with a summary: how many tickets, the ones to look at, and the ones safe to archive.

The routine's output lists every ticket with what was written. Cards, tasks and comments still wait for a yes, and nothing replies, closes, archives or changes a status.

Assigning needs the agent role's Assign Agents for that kind of ticket (Prepare the site); Pylon tickets can't be assigned yet. SupportCandy's API has no archive call, so archiving stays with a person: a routine lists the tickets to archive, and the list is one bulk action in SupportCandy.

Pulses on a schedule

A routine in schedule shows up in sync's cadence block when it hasn't run in its period, as helpdesk pulse acme or helpdesk digest acme. Sync only nudges: a pulse reads customer text against rate limits that suit a person asking, not an unattended run. Each complete run of a scheduled routine saves a report to reports/helpdesk/ (one cut short by an error saves nothing), and the newest one is what tells sync it ran.

Sync does count every queue itself, in a 🎫 Support block: tickets updated in the last 24 hours by status and tag, unassigned, and newly opened. The count reads no ticket text, so it's safe to run unattended. helpdesk stats shows the same counts on demand.

Which queues the count covers, and the App Store reviews line it adds, are below.

If something's off

Most problems are the REST API switched off, a wrong password, a page cache, or a missing key; find the symptom below.

Where it's used

Five other parts of the agent lean on the helpdesk pack.

On this page