mobieusKnow mobieusHelp admin guide History #103

Revision #103

Approved
All revisions
Author
system
Submitted
Jun 4, 2026 7:46am
Reviewed
Jun 4, 2026 7:46am
Summary
mobieusLaw #7 sync 2026-06-04
# mobieusHelp admin guide
The full reference for `/admin/helpdesk` on your tenant. Every nav section, every surface, and how to use them. Sign in as a tenant administrator and open `/admin/helpdesk` to follow along.
## What this is
mobieusHelp is the help desk built into your Mobieus community. It runs at three URLs on every tenant:
- **`/admin/helpdesk`** — the admin plane covered by this guide.
- **`/help/agent`** — where your agents work tickets (queues, ticket detail, reply composer, internal notes).
- **`/help/portal`** — the public-facing portal customers open to file a ticket.
The admin nav at `/admin/helpdesk` groups every capability under seven headings.
+ ## Routing — queues, topics, tags, canned responses
− ## Routing — queues, topics, tags, canned responses, macros
The Routing group decides where new tickets land and how agents recognise them.
+ **Queues** (`/admin/helpdesk/queues`) — departments with their own SLA, agent roster, and assignment policy. Every tenant ships with at least one queue ("Support"). Create more for billing, legal, abuse, sales — whatever splits the work. Each queue chooses round-robin / least-busy / manual assignment.
− **Queues** (`/admin/helpdesk/queues`) — departments with their own SLA, agent roster, and assignment policy. Every tenant ships with at least one queue ("Support"). Create more for billing, legal, abuse, sales — whatever splits the work. Each queue chooses round-robin, fewest-open, or manual assignment; on round-robin or fewest-open, new tickets distribute to agents automatically instead of waiting to be claimed.
**Help topics** (`/admin/helpdesk/help-topics`) — the picker on the public portal. A topic maps a customer's intent ("billing question") to a queue, a default priority, and optional custom fields (text / number / URL / email / date / select). Custom fields render on the portal form, become required if you mark them so, and show up on the ticket detail page.
**Tags** (`/admin/helpdesk/tags`) — colored labels with no inherent meaning. Agents attach them; the rules engine reads them as conditions; queue listings filter by them. Useful for "vip", "regression", "needs-followup".
**Canned responses** (`/admin/helpdesk/canned-responses`) — agent reply templates with ticket-aware placeholders (`{{requester.first_name}}`, `{{ticket.reference}}`, `{{queue.name}}`). The agent picks one in the reply composer; placeholders substitute at insert time. The use-count column tells you which templates earn their keep.
− **Macros** (`/admin/helpdesk/macros`) — one-click bundles of actions. A macro can post a templated reply (same `{{requester.first_name}}` / `{{ticket.reference}}` placeholders as canned responses), change the status and priority, assign the ticket, and add tags — all at once. Build the routine ones ("Resolve with thanks", "Escalate to billing") and agents apply them from a picker on the ticket page instead of doing four things by hand. The reply posts first and the status change applies last, so a "resolve" macro sends its reply before closing; an invalid status transition is skipped and the rest still apply.
## People — agents, notification defaults, email accounts
**Agents** (`/admin/helpdesk/agents`) — grant helpdesk access to specific tenant users. Three roles per queue: admin (everything), supervisor (close, reopen, move queue), agent (reply, internal note, change status). Tenant-wide grants apply to every queue.
**Notification defaults** (`/admin/helpdesk/notification-prefs`) — per-event email defaults for every agent and requester. Set the floor here (e.g., "agents always get on_create unless they opt out"); individuals override on their own preferences page.
+ **Email accounts** (`/admin/helpdesk/email-accounts`) — inbound email accounts the helpdesk monitors. Webhook receivers for Postmark / Mailgun / Amazon SES dedup by Message-ID and parse the ticket reference from the subject or `In-Reply-To` headers. A customer replying to a notification email lands on the ticket within 60 seconds.
− **Email accounts** (`/admin/helpdesk/email-accounts`) — inbound email accounts the helpdesk monitors. Webhook receivers for Postmark, Mailgun, Amazon SES, and a generic JSON format dedup by Message-ID and parse the ticket reference from the subject or `In-Reply-To` headers. A customer replying to a notification email lands back on their ticket within about a minute.
## Automation — SLA, rules engine
+ **SLA** (`/admin/helpdesk/sla`) — first-response and resolve budgets, scoped to business hours. Set a business-hours profile (timezone + weekly schedule + holidays); attach an SLA plan to a queue; a 2-minute worker re-materializes each ticket's SLA state (on-track / warning at 75% consumed / breach past due) and writes an audit row on every transition.
− **SLA** (`/admin/helpdesk/sla`) — first-response and resolve budgets, scoped to business hours. Set a business-hours profile (timezone + weekly schedule + holidays); attach an SLA plan to a queue; a background worker re-materializes each ticket's SLA state (on-track / warning at 75% consumed / breach past due) and writes an audit row on every transition.
**Rules engine** (`/admin/helpdesk/rules`) — condition + action automation on five triggers (`on_create`, `on_reply`, `on_status`, `on_assign`, `on_tag`). Conditions read ticket / queue / topic / tags / requester data; actions can set priority, attach tags, move queues, reassign, swap SLA plans, change status. Every run logs to the audit log; one bad rule never breaks the trigger.
## AI hooks (mobieusAI)
+ Eight AI capabilities ship with mobieusHelp. Each is gated on the tenant AI master switch (an Anthropic API key configured at `/admin/learn/settings` or the platform-wide AI settings page) — turn AI off and the hooks vanish from the agent UI.
− Eight AI capabilities ship with mobieusHelp. They are powered by the tenant's mobieusAI configuration — the master switch and your Anthropic API key at **`/admin/ai`**. Turn AI off there and the hooks vanish from the agent UI. mobieusHelp does not depend on any other product to use these; they share the same one AI control plane the rest of your community uses.
−
− Unlike most mobieusAI helpers, the help-desk hooks are **on by default** once AI is enabled — switch any of them off individually at `/admin/ai`.
The capabilities:
- **Reply suggestions** — drafts a polite, on-tone reply for the current ticket. Agent edits before sending.
- **Ticket summary** — collapses a long ticket thread into 3-5 bullet points.
- **Sentiment scoring** — flags angry / frustrated / urgent requesters before the SLA does.
- **Auto-categorize** — proposes a help topic + queue when the portal categorization is wrong.
- **Resolution prediction** — estimates how long the ticket will take based on the closest historical matches.
- **Knowledge-base gap detection** — finds portal searches that returned nothing useful, so you know which mobieusKnow articles to write next.
- **Audit Q&A** — natural-language search over the audit log.
- **Canned-response generation** — proposes a new canned response from the last reply you wrote.
+ There is no AI nav surface today; the hooks live inline on the agent ticket page and in the canned-responses editor. The full AI configuration lives at `/admin/learn/settings` — same Anthropic key powers AI authoring for mobieusLearn and AI hooks for mobieusHelp.
− There is no separate AI nav surface inside the help desk; the hooks live inline on the agent ticket page and in the canned-responses editor. The master switch, BYOK key, per-feature toggles, and spend caps all live at `/admin/ai`.
−
− ## Reports
−
− **Reports** (`/admin/helpdesk/reports`) — how your support is doing, over the last 7, 30, or 90 days:
−
− - **Volume** — tickets created, resolved, and open right now.
− - **SLA breach rate** — the share of SLA-tracked tickets that breached in the window.
− - **First-response and resolution times** — average, median (p50), and 90th percentile (p90), so a few slow outliers don't hide behind the average.
− - **Satisfaction** — average CSAT and the 1–5 star distribution.
− - **By queue and by agent** — the same numbers broken down, so you can see where the load and the delays sit.
− Switch the window with the buttons at the top, and **Export CSV** to pull any view into a spreadsheet.
## Audit log + Settings
**Audit log** (`/admin/helpdesk/audit`) — every privileged action: queue creates, role grants, status transitions, replies, internal notes, deletes. Filter by event type, paginated 50 per page. Use this when investigating "who changed what when".
**Settings** (`/admin/helpdesk/settings`) — tenant-wide helpdesk config: default queue, default SLA, default notification floor, branding overrides for outbound email.
## Common workflows
**Stand up a new queue for billing**
1. Routing → Queues → New → name "Billing", set the SLA plan and business hours profile.
2. People → Agents → grant a billing-admin role to your bookkeeper.
3. Routing → Help topics → New → "Billing question" → maps to the Billing queue.
4. Routing → Help topics → "Billing question" → Custom fields → add "Invoice number" (text, required).
5. Customer files a billing ticket; portal asks for the invoice number; ticket lands on your bookkeeper.
**Auto-tag VIP tickets**
1. Routing → Tags → New → "vip" with a red color.
2. Automation → Rules engine → New → on_create → if requester.email matches a VIP list → action: attach tag "vip" + set priority "high".
3. Tickets from those email addresses now land tagged and prioritized.
**Catch knowledge-base gaps**
+ 1. Make sure mobieusAI is configured (`/admin/learn/settings`).
+ 2. The AI knowledge-gaps hook surfaces the top 20 portal searches that returned nothing useful.
− 1. Make sure mobieusAI is enabled at `/admin/ai`.
− 2. The AI knowledge-gaps hook surfaces the top portal searches that returned nothing useful.
3. Write a mobieusKnow article addressing each top gap; the portal deflection rate climbs.
## What's NOT in this guide
+ - Agent workflow — how to triage, reply, escalate. That's the [agent playbook](/know/mobieushelp-agent-playbook) (coming).
+ - Public portal experience — the customer-facing flow lives in the portal itself; no admin page exposes it.
− - Agent workflow — how to triage, reply, escalate. See the [mobieusHelp Agent Workspace](/know/mobieushelp-agent) guide.
− - Public portal experience — the customer-facing flow lives in the [mobieusHelp Customer Portal](/know/mobieushelp-portal) guide.
- API access — see the [mobieusCore API helpdesk reference](/know/api-helpdesk).
## Related articles
+ - [mobieusLearn admin guide](/know/mobieuslearn-admin-guide)
− - [mobieusHelp: Agent Workspace](/know/mobieushelp-agent)
− - [mobieusHelp: Customer Portal](/know/mobieushelp-portal)
- [mobieusCore API — Overview](/know/api-overview)

mobieusHelp admin guide

The full reference for /admin/helpdesk on your tenant. Every nav section, every surface, and how to use them. Sign in as a tenant administrator and open /admin/helpdesk to follow along.

What this is

mobieusHelp is the help desk built into your Mobieus community. It runs at three URLs on every tenant:

  • /admin/helpdesk — the admin plane covered by this guide.
  • /help/agent — where your agents work tickets (queues, ticket detail, reply composer, internal notes).
  • /help/portal — the public-facing portal customers open to file a ticket.

The admin nav at /admin/helpdesk groups every capability under seven headings.

Routing — queues, topics, tags, canned responses

The Routing group decides where new tickets land and how agents recognise them.

Queues (/admin/helpdesk/queues) — departments with their own SLA, agent roster, and assignment policy. Every tenant ships with at least one queue ("Support"). Create more for billing, legal, abuse, sales — whatever splits the work. Each queue chooses round-robin / least-busy / manual assignment.

Help topics (/admin/helpdesk/help-topics) — the picker on the public portal. A topic maps a customer's intent ("billing question") to a queue, a default priority, and optional custom fields (text / number / URL / email / date / select). Custom fields render on the portal form, become required if you mark them so, and show up on the ticket detail page.

Tags (/admin/helpdesk/tags) — colored labels with no inherent meaning. Agents attach them; the rules engine reads them as conditions; queue listings filter by them. Useful for "vip", "regression", "needs-followup".

Canned responses (/admin/helpdesk/canned-responses) — agent reply templates with ticket-aware placeholders ({{requester.first_name}}, {{ticket.reference}}, {{queue.name}}). The agent picks one in the reply composer; placeholders substitute at insert time. The use-count column tells you which templates earn their keep.

People — agents, notification defaults, email accounts

Agents (/admin/helpdesk/agents) — grant helpdesk access to specific tenant users. Three roles per queue: admin (everything), supervisor (close, reopen, move queue), agent (reply, internal note, change status). Tenant-wide grants apply to every queue.

Notification defaults (/admin/helpdesk/notification-prefs) — per-event email defaults for every agent and requester. Set the floor here (e.g., "agents always get on_create unless they opt out"); individuals override on their own preferences page.

Email accounts (/admin/helpdesk/email-accounts) — inbound email accounts the helpdesk monitors. Webhook receivers for Postmark / Mailgun / Amazon SES dedup by Message-ID and parse the ticket reference from the subject or In-Reply-To headers. A customer replying to a notification email lands on the ticket within 60 seconds.

Automation — SLA, rules engine

SLA (/admin/helpdesk/sla) — first-response and resolve budgets, scoped to business hours. Set a business-hours profile (timezone + weekly schedule + holidays); attach an SLA plan to a queue; a 2-minute worker re-materializes each ticket's SLA state (on-track / warning at 75% consumed / breach past due) and writes an audit row on every transition.

Rules engine (/admin/helpdesk/rules) — condition + action automation on five triggers (on_create, on_reply, on_status, on_assign, on_tag). Conditions read ticket / queue / topic / tags / requester data; actions can set priority, attach tags, move queues, reassign, swap SLA plans, change status. Every run logs to the audit log; one bad rule never breaks the trigger.

AI hooks (mobieusAI)

Eight AI capabilities ship with mobieusHelp. Each is gated on the tenant AI master switch (an Anthropic API key configured at /admin/learn/settings or the platform-wide AI settings page) — turn AI off and the hooks vanish from the agent UI.

The capabilities:

  • Reply suggestions — drafts a polite, on-tone reply for the current ticket. Agent edits before sending.
  • Ticket summary — collapses a long ticket thread into 3-5 bullet points.
  • Sentiment scoring — flags angry / frustrated / urgent requesters before the SLA does.
  • Auto-categorize — proposes a help topic + queue when the portal categorization is wrong.
  • Resolution prediction — estimates how long the ticket will take based on the closest historical matches.
  • Knowledge-base gap detection — finds portal searches that returned nothing useful, so you know which mobieusKnow articles to write next.
  • Audit Q&A — natural-language search over the audit log.
  • Canned-response generation — proposes a new canned response from the last reply you wrote.

There is no AI nav surface today; the hooks live inline on the agent ticket page and in the canned-responses editor. The full AI configuration lives at /admin/learn/settings — same Anthropic key powers AI authoring for mobieusLearn and AI hooks for mobieusHelp.

Audit log + Settings

Audit log (/admin/helpdesk/audit) — every privileged action: queue creates, role grants, status transitions, replies, internal notes, deletes. Filter by event type, paginated 50 per page. Use this when investigating "who changed what when".

Settings (/admin/helpdesk/settings) — tenant-wide helpdesk config: default queue, default SLA, default notification floor, branding overrides for outbound email.

Common workflows

Stand up a new queue for billing

  1. Routing → Queues → New → name "Billing", set the SLA plan and business hours profile.
  2. People → Agents → grant a billing-admin role to your bookkeeper.
  3. Routing → Help topics → New → "Billing question" → maps to the Billing queue.
  4. Routing → Help topics → "Billing question" → Custom fields → add "Invoice number" (text, required).
  5. Customer files a billing ticket; portal asks for the invoice number; ticket lands on your bookkeeper.

Auto-tag VIP tickets

  1. Routing → Tags → New → "vip" with a red color.
  2. Automation → Rules engine → New → on_create → if requester.email matches a VIP list → action: attach tag "vip" + set priority "high".
  3. Tickets from those email addresses now land tagged and prioritized.

Catch knowledge-base gaps

  1. Make sure mobieusAI is configured (/admin/learn/settings).
  2. The AI knowledge-gaps hook surfaces the top 20 portal searches that returned nothing useful.
  3. Write a mobieusKnow article addressing each top gap; the portal deflection rate climbs.

What's NOT in this guide

  • Agent workflow — how to triage, reply, escalate. That's the agent playbook (coming).
  • Public portal experience — the customer-facing flow lives in the portal itself; no admin page exposes it.
  • API access — see the mobieusCore API helpdesk reference.

Related articles

# mobieusHelp admin guide

The full reference for `/admin/helpdesk` on your tenant. Every nav section, every surface, and how to use them. Sign in as a tenant administrator and open `/admin/helpdesk` to follow along.

## What this is

mobieusHelp is the help desk built into your Mobieus community. It runs at three URLs on every tenant:

- **`/admin/helpdesk`** — the admin plane covered by this guide.
- **`/help/agent`** — where your agents work tickets (queues, ticket detail, reply composer, internal notes).
- **`/help/portal`** — the public-facing portal customers open to file a ticket.

The admin nav at `/admin/helpdesk` groups every capability under seven headings.

## Routing — queues, topics, tags, canned responses

The Routing group decides where new tickets land and how agents recognise them.

**Queues** (`/admin/helpdesk/queues`) — departments with their own SLA, agent roster, and assignment policy. Every tenant ships with at least one queue ("Support"). Create more for billing, legal, abuse, sales — whatever splits the work. Each queue chooses round-robin / least-busy / manual assignment.

**Help topics** (`/admin/helpdesk/help-topics`) — the picker on the public portal. A topic maps a customer's intent ("billing question") to a queue, a default priority, and optional custom fields (text / number / URL / email / date / select). Custom fields render on the portal form, become required if you mark them so, and show up on the ticket detail page.

**Tags** (`/admin/helpdesk/tags`) — colored labels with no inherent meaning. Agents attach them; the rules engine reads them as conditions; queue listings filter by them. Useful for "vip", "regression", "needs-followup".

**Canned responses** (`/admin/helpdesk/canned-responses`) — agent reply templates with ticket-aware placeholders (`{{requester.first_name}}`, `{{ticket.reference}}`, `{{queue.name}}`). The agent picks one in the reply composer; placeholders substitute at insert time. The use-count column tells you which templates earn their keep.

## People — agents, notification defaults, email accounts

**Agents** (`/admin/helpdesk/agents`) — grant helpdesk access to specific tenant users. Three roles per queue: admin (everything), supervisor (close, reopen, move queue), agent (reply, internal note, change status). Tenant-wide grants apply to every queue.

**Notification defaults** (`/admin/helpdesk/notification-prefs`) — per-event email defaults for every agent and requester. Set the floor here (e.g., "agents always get on_create unless they opt out"); individuals override on their own preferences page.

**Email accounts** (`/admin/helpdesk/email-accounts`) — inbound email accounts the helpdesk monitors. Webhook receivers for Postmark / Mailgun / Amazon SES dedup by Message-ID and parse the ticket reference from the subject or `In-Reply-To` headers. A customer replying to a notification email lands on the ticket within 60 seconds.

## Automation — SLA, rules engine

**SLA** (`/admin/helpdesk/sla`) — first-response and resolve budgets, scoped to business hours. Set a business-hours profile (timezone + weekly schedule + holidays); attach an SLA plan to a queue; a 2-minute worker re-materializes each ticket's SLA state (on-track / warning at 75% consumed / breach past due) and writes an audit row on every transition.

**Rules engine** (`/admin/helpdesk/rules`) — condition + action automation on five triggers (`on_create`, `on_reply`, `on_status`, `on_assign`, `on_tag`). Conditions read ticket / queue / topic / tags / requester data; actions can set priority, attach tags, move queues, reassign, swap SLA plans, change status. Every run logs to the audit log; one bad rule never breaks the trigger.

## AI hooks (mobieusAI)

Eight AI capabilities ship with mobieusHelp. Each is gated on the tenant AI master switch (an Anthropic API key configured at `/admin/learn/settings` or the platform-wide AI settings page) — turn AI off and the hooks vanish from the agent UI.

The capabilities:

- **Reply suggestions** — drafts a polite, on-tone reply for the current ticket. Agent edits before sending.
- **Ticket summary** — collapses a long ticket thread into 3-5 bullet points.
- **Sentiment scoring** — flags angry / frustrated / urgent requesters before the SLA does.
- **Auto-categorize** — proposes a help topic + queue when the portal categorization is wrong.
- **Resolution prediction** — estimates how long the ticket will take based on the closest historical matches.
- **Knowledge-base gap detection** — finds portal searches that returned nothing useful, so you know which mobieusKnow articles to write next.
- **Audit Q&A** — natural-language search over the audit log.
- **Canned-response generation** — proposes a new canned response from the last reply you wrote.

There is no AI nav surface today; the hooks live inline on the agent ticket page and in the canned-responses editor. The full AI configuration lives at `/admin/learn/settings` — same Anthropic key powers AI authoring for mobieusLearn and AI hooks for mobieusHelp.

## Audit log + Settings

**Audit log** (`/admin/helpdesk/audit`) — every privileged action: queue creates, role grants, status transitions, replies, internal notes, deletes. Filter by event type, paginated 50 per page. Use this when investigating "who changed what when".

**Settings** (`/admin/helpdesk/settings`) — tenant-wide helpdesk config: default queue, default SLA, default notification floor, branding overrides for outbound email.

## Common workflows

**Stand up a new queue for billing**
1. Routing → Queues → New → name "Billing", set the SLA plan and business hours profile.
2. People → Agents → grant a billing-admin role to your bookkeeper.
3. Routing → Help topics → New → "Billing question" → maps to the Billing queue.
4. Routing → Help topics → "Billing question" → Custom fields → add "Invoice number" (text, required).
5. Customer files a billing ticket; portal asks for the invoice number; ticket lands on your bookkeeper.

**Auto-tag VIP tickets**
1. Routing → Tags → New → "vip" with a red color.
2. Automation → Rules engine → New → on_create → if requester.email matches a VIP list → action: attach tag "vip" + set priority "high".
3. Tickets from those email addresses now land tagged and prioritized.

**Catch knowledge-base gaps**
1. Make sure mobieusAI is configured (`/admin/learn/settings`).
2. The AI knowledge-gaps hook surfaces the top 20 portal searches that returned nothing useful.
3. Write a mobieusKnow article addressing each top gap; the portal deflection rate climbs.

## What's NOT in this guide

- Agent workflow — how to triage, reply, escalate. That's the [agent playbook](/know/mobieushelp-agent-playbook) (coming).
- Public portal experience — the customer-facing flow lives in the portal itself; no admin page exposes it.
- API access — see the [mobieusCore API helpdesk reference](/know/api-helpdesk).

## Related articles

- [mobieusLearn admin guide](/know/mobieuslearn-admin-guide)
- [mobieusCore API — Overview](/know/api-overview)