toolkit

Helpdesk (FreeScout) · Playbook

FreeScout API — setup & reference (for Helpdesk (FreeScout))

Everything you need to point blissey at your FreeScout helpdesk. You do this once; after that, just ask your agent for the helpdesk overview.

1. Paste the key you were given (your .env)

You’ll be provided a FreeScout API key — you don’t create your own. Add it, with the instance URL, to the toolkit .env (gitignored — your key is never shared or committed):

FREESCOUT_API_URL=https://helpdesk.nkpapps.com   # the instance you log into (no /api, no trailing slash)
FREESCOUT_API_KEY=paste-the-key-you-were-given
  • FREESCOUT_API_URL is just the site you log into. blissey appends /api itself.
  • The key is sent as the X-FreeScout-API-Key header. Treat it like a password.
  • Until both are set, blissey is inert — it exits quietly and does nothing (it never errors on a teammate who hasn’t been set up yet).

Confirm it works:

node skills/ops/blissey/scripts/blissey.mjs ping
# OK — connected to help.yourdomain.com (3 mailbox(es))

2. What blissey reads (read-only)

blissey only ever GETs — it never replies to, edits, or closes a ticket. Endpoints used (base = FREESCOUT_API_URL + /api):

blissey command FreeScout endpoint(s)
blissey (overview) GET /mailboxes, then GET /conversations?mailboxId=&status=&pageSize=1 per mailbox/status for counts, GET /conversations?status=active for the recent list
blissey conversations GET /conversations (filters: mailboxId, status, assignedTo, pageSize)
blissey conversation <id> GET /conversations/{id}?embed=threads
blissey customer <email> GET /customers?email=, then GET /conversations?customerId=
blissey mailboxes · ping GET /mailboxes

Auth header on every request: X-FreeScout-API-Key: <your key>. Responses are HAL JSON — collections come under _embedded.<resource> with a page.totalElements count. Statuses: active, pending, closed.

3. Troubleshooting

  • HTTP 401/403 — check FREESCOUT_API_KEY → the key is wrong or was regenerated; ask for a fresh one.
  • HTTP 404 on everything → FREESCOUT_API_URL is wrong (it should be the site root, not the /api path).
  • Inert / no output → one of the two env vars is missing. Run blissey ping after setting both.
  • Counts look off → some FreeScout versions expect numeric status filters; tell your agent and it can adjust.

Reference