Frappe Helpdesk
A Helpdesk site is a set of documents. A ticket (HD Ticket) is raised by a contact (Contact; raised_by is their email), who may belong to a customer (HD Customer). The emails on a ticket are Communication rows, and the agents' internal notes are Comment rows with comment_type Comment. Both point back with reference_doctype "HD Ticket" and reference_name.
A ticket belongs to a team (agent_group, an HD Team) and is assigned to agents (HD Agent), stored as a JSON list in _assign. Its status (an HD Ticket Status) falls in one of three categories, kept in status_category: Open, Paused or Resolved. An SLA (HD Service Level Agreement) sets when the first response and the resolution are due.
Read and change these documents with frappectl. Use the app's own methods where this file names one, because they send the email, thread the reply and keep assignment correct. Use plain document calls for the rest.
1. Connect
Ask the human for a frappectl profile, and pass it as -s <p>. Check it with frappectl -s <p> method call helpdesk.api.auth.get_user: it returns is_agent, is_manager and user_teams.
- Agent works tickets: reads, replies, comments, assigns, tags, merges and splits. Agents also manage teams and saved replies, and read contacts and customers.
- Agent Manager also manages contacts, customers, SLAs, assignment rules, email accounts and other agents, and sees every agent's numbers.
- A customer (
is_agent false) is a contact working their own tickets. Read reference/customer.md and use only the calls there; the rest of this file is for agents.
- Administrator counts as an agent. A deactivated agent (
HD Agent is_active 0) is not one, whatever its roles.
A call refused with "does not have doctype access" needs a role the profile lacks. Tell the human; do not look for a way around it.
- Ticket names are strings:
0320 by default, though a site can change the naming rule. In method call, pass them with -f, which always sends a string; doc get takes the name as is. -F can send a name that looks like a number as an integer, and the method refuses it.
- Some methods accept only GET. Call those with
method call -X GET. This file marks them.
doc create and doc update read stdin when it is not a terminal, and hang in an agent's shell. Pass --input <file>, or < /dev/null with --set.
- Send dict and list arguments as JSON:
-F 'filters:={"agent":"<user>"}'.
- Sites add their own fields to
HD Ticket. The ticket template, HD Ticket Template "Default", says which ones the app uses, in the order it shows them, and which are required: method call helpdesk.helpdesk.doctype.hd_ticket_template.api.get_one -f name=Default. frappectl -s <p> doctype show "HD Ticket" lists every field. Check one of them before you guess a field name.
2. Find tickets and their data
frappectl -s <p> doc list "HD Ticket" -f status_category=Open -f agent_group=<team> \
--fields name,subject,status,priority,_assign,customer,response_by,agreement_status
frappectl -s <p> method call helpdesk.api.search.search -F query=<words> # subjects, descriptions, emails and comments
frappectl -s <p> doc get "HD Ticket" <ticket> # the ticket's fields
frappectl -s <p> method call frappe.desk.form.activity.get_activity_timeline -f doctype="HD Ticket" -f name=<ticket> # its emails, notes and changes
frappectl -s <p> method call helpdesk.helpdesk.doctype.hd_ticket.api.get_recent_similar_tickets -f ticket=<ticket>
frappectl -s <p> method call -X GET helpdesk.api.contact.get_contact_info -f name=<contact>
The timeline lists everything that happened on the ticket, oldest first. Each activity has a type, an author, a timestamp and its data:
email: an email, with its name, sender, subject and content.
comment: an internal note, with its content.
version: a field change, with fieldname, from and to.
log: the ticket was created, assigned or given an attachment.
To keep only the conversation and the status changes, add -F 'visible_types:=["email", "comment", {"version": ["status"]}]'. It holds the latest 20 emails. When has_more_emails is true, method call frappe.desk.form.activity.get_more_email_activities -f doctype="HD Ticket" -f name=<ticket> -F start=20 gives the 20 before them.
Read emails and notes through the timeline: doc list Communication returns nothing for an agent.
Common filters (mine, unassigned, overdue, a customer's, a date range): reference/tickets.md.
For numbers across many tickets (counts, average response and resolution time, SLA breaches, ratings), use the methods in reference/reports.md. They count working hours the way the SLA does, which a doc list loop cannot.
3. SLA: when is it due, why is it late
method call helpdesk.helpdesk.doctype.hd_ticket.api.get_one -f name=<ticket> returns overdue_by, with response and resolution in working seconds past due. It is empty while the ticket is paused. get_one also marks the ticket as seen by the caller. The ticket itself has sla, agreement_status (First Response Due, Resolution Due, Paused, Failed or Fulfilled), response_by, resolution_by, first_responded_on, on_hold_since, total_hold_time, first_response_failed_by and resolution_failed_by.
To explain a date, read the SLA named in sla with doc get "HD Service Level Agreement" <sla> (Agent Manager only): its priorities, working hours, breaks and holiday list. Without that role, get_ticket_analytics (reference/tickets.md) still gives each target and how far it was missed. reference/sla.md explains how the SLA is picked and the dates are worked out.
4. Common tasks
| Task |
Call |
| Pick what to work on next |
doc list "HD Ticket" -f status_category=Open -f '_assign like %<user>%' --fields name,subject,priority,response_by,resolution_by,first_responded_on. Each ticket is next due by its response_by, or by its resolution_by once first_responded_on is set. Sort on that and put the earliest first. With none of their own, offer their team's unassigned tickets (reference/tickets.md). |
| Reply to the customer |
Before you write one, list the saved replies with doc list "HD Saved Reply" --fields name,title; when one fits, use "Reply with a saved reply". Show the human the draft and ask before you send it. Then method call reply_via_agent --doctype "HD Ticket" --name <t> -F message="<html>". It emails the ticket's raised_by. Pass to (comma-separated) to send it elsewhere; with only cc or bcc, the customer is left out. Add cc, bcc or attachments (File names) when needed. A reply changes the status only when HD Settings auto_update_status is on. Read the ticket after sending, tell the human its status, and offer to change it: a Paused status such as Replied stops the SLA clock while you wait for the customer. When the reply, or what you changed on the ticket, repeats one you already did this session, also offer to save it ("Save a repeated reply"). |
| Add an internal note |
method call new_comment --doctype "HD Ticket" --name <t> -F content="<html>" |
| Assign an agent |
method call assign_agent --doctype "HD Ticket" --name <t> -f agent=<user>. It adds to the current assignees and notifies the agent. |
| Change status, priority, team or type |
doc update "HD Ticket" <t> --set status=<status> < /dev/null. List the statuses with doc list "HD Ticket Status" --fields name,category. |
| Reply with a saved reply |
method call helpdesk.api.saved_replies.get_rendered_saved_reply -f ticket_id=<t> -f saved_reply_id=<name>, change anything in its message that doesn't fit this ticket or that you can't confirm, send it with reply_via_agent, then pass its actions to apply_saved_reply_actions -f ticket_id=<t> -F 'actions:=<actions>' |
| Save a repeated reply |
Offer it once a session, the second time you send much the same reply or make the same changes. Show the draft: a title, the message with the ticket's details replaced by fields such as {{ subject }}, using only fields doctype show "HD Ticket" lists, since any other renders empty (see the saved reply trap), the changes as actions, and scope Personal. Create it only on a yes, as reference/setup.md shows. Ask before making it Team or Global: it shows in other agents' lists. |
| Tag a ticket |
method call helpdesk.api.tags.update_tags -f doctype="HD Ticket" -f name=<t> -F 'added:=[{"name": "<tag>"}]'. A new tag is created. To remove one, send -F 'removed:=["<tag>"]' instead. |
| Create a ticket for a contact |
doc create "HD Ticket" --input <file> with subject, description (HTML), raised_by (their email), contact and, when they have one, customer. See reference/tickets.md. |
| Merge two tickets |
method call helpdesk.helpdesk.doctype.hd_ticket.api.merge_ticket -f source=<t> -f target=<t>. It returns {}; doc get the source to see merged_with. |
| Split a ticket |
method call helpdesk.helpdesk.doctype.hd_ticket.api.split_ticket -f subject=<s> -f communication_id=<email>. The email and every email and comment after it move to a new ticket. |
| Find a contact |
method call -X GET helpdesk.api.contact.search_contacts -f txt=<text> |
| Create a contact |
method call helpdesk.api.contact.create_contact -F 'doc:={"first_name": "...", "last_name": "...", "email": "..."}'. Put "customer": "<c>" in doc to add them to that customer. Nobody is emailed unless you add -F invite:=true, which invites them to the portal instead. |
| Create a customer |
method call helpdesk.api.customer.create_customer -F 'customer:={"customer_name": "...", "domain": "..."}'. Add -F 'primary_contact:={"email": "...", "first_name": "..."}' to create and invite its first contact. |
| Add contacts to a customer |
method call add_contacts --doctype "HD Customer" --name <c> -F 'contacts:=["<contact or email>"]'. A contact with a user is added. One without a user is emailed an invite instead, and comes back under invite_result, not added. With -F invite:=false, every contact is added and nobody is emailed; a missing contact can be created with its customer in one step ("Create a contact"). |
| Set up the helpdesk |
reference/setup.md |
For anything this file doesn't cover, find the method: frappectl -s <p> method search -q "<one or two words>" (every word must match), then method show <path> for its arguments, who may call it, what it returns and its code. Read that before you call it, and still mind the traps below. When nothing matches, the task is usually a field change: use doctype show and the doc commands. Search is for agents; a customer's profile is refused it, and a site on an older Frappe doesn't have it.
5. Traps
- A reply emails the customer when HD Settings
enable_reply_email_via_agent is on. Show the human the reply and ask before you send it.
- Never insert a
Communication to reply. The ticket still updates, but no email goes out and the reply is not threaded. An agent replies with reply_via_agent; a customer replies with create_communication_via_contact (reference/customer.md).
- A merge cannot be undone. It copies the source's emails, comments and files into the target, closes the source with
merged_with set, and emails the customer on the source that it was merged. doc get both first: when their raised_by or customer differ, tell the human, because the target's contact will see the source's emails. Ask first.
- Deletes can take tickets with them.
delete_contact and delete_customer with delete_tickets delete every linked ticket. Ask first, and name what will go.
- Every save picks the SLA again and recalculates its dates. Changing the priority, or a field an SLA condition reads, can switch the ticket to another SLA.
- A contact sees a ticket only when they are its
contact, its raised_by or its owner. A customer's managers also see every ticket of that customer. Set these right on a ticket you create.
- A ticket you create records your user, not the contact, as the sender of its first email.
- Team restrictions hide tickets. With HD Settings
restrict_tickets_by_agent_group on, an agent sees only their teams' tickets. A ticket that "does not exist" may be in another team.
- Saved reply templates see the ticket's fields and the signed-in user's
User fields. Where both have a field (name, owner, creation), the user's wins: {{ name }} is the agent's user, not the ticket. Use {{ subject }} and other ticket-only fields.
Reference
reference/tickets.md: ticket fields, filters, the conversation, history, feedback, creating, merging and splitting.
reference/sla.md: which SLA applies and how its due dates, pauses and breaches are worked out.
reference/reports.md: ticket volume, response and resolution times, SLA breaches and ratings, for an agent, a team, a customer or a contact.
reference/customer.md: everything a customer's profile can do, and the rules the portal enforces.
reference/setup.md: agents, teams and assignment, SLAs and holiday lists, ticket types and priorities, saved replies and email accounts.
1---2name: frappe-helpdesk3description: Manage a Frappe Helpdesk site from outside the app, through frappectl. Use to find tickets and read their conversations, explain a ticket's SLA, reply, comment, assign, tag, change status or priority, merge or split tickets, look up or create contacts and customers, answer questions about ticket volume, response and resolution times, SLA breaches and feedback, set up agents, teams, SLAs, saved replies and email accounts, or, for a customer's profile, raise, reply to, close and rate their own tickets, when the site runs the Helpdesk app.4metadata:5 source: https://skillmd.com/skills/frappe/frappe-helpdesk6---78# Frappe Helpdesk910A Helpdesk site is a set of documents. A ticket (`HD Ticket`) is raised by a contact (`Contact`; `raised_by` is their email), who may belong to a customer (`HD Customer`). The emails on a ticket are `Communication` rows, and the agents' internal notes are `Comment` rows with `comment_type` Comment. Both point back with `reference_doctype` "HD Ticket" and `reference_name`.1112A ticket belongs to a team (`agent_group`, an `HD Team`) and is assigned to agents (`HD Agent`), stored as a JSON list in `_assign`. Its `status` (an `HD Ticket Status`) falls in one of three categories, kept in `status_category`: Open, Paused or Resolved. An SLA (`HD Service Level Agreement`) sets when the first response and the resolution are due.1314Read and change these documents with `frappectl`. Use the app's own methods where this file names one, because they send the email, thread the reply and keep assignment correct. Use plain document calls for the rest.1516## 1. Connect1718Ask the human for a frappectl profile, and pass it as `-s <p>`. Check it with `frappectl -s <p> method call helpdesk.api.auth.get_user`: it returns `is_agent`, `is_manager` and `user_teams`.1920- **Agent** works tickets: reads, replies, comments, assigns, tags, merges and splits. Agents also manage teams and saved replies, and read contacts and customers.21- **Agent Manager** also manages contacts, customers, SLAs, assignment rules, email accounts and other agents, and sees every agent's numbers.22- **A customer** (`is_agent` false) is a contact working their own tickets. Read `reference/customer.md` and use only the calls there; the rest of this file is for agents.23- Administrator counts as an agent. A deactivated agent (`HD Agent` `is_active` 0) is not one, whatever its roles.2425A call refused with "does not have doctype access" needs a role the profile lacks. Tell the human; do not look for a way around it.2627- Ticket names are strings: `0320` by default, though a site can change the naming rule. In `method call`, pass them with `-f`, which always sends a string; `doc get` takes the name as is. `-F` can send a name that looks like a number as an integer, and the method refuses it.28- Some methods accept only GET. Call those with `method call -X GET`. This file marks them.29- `doc create` and `doc update` read stdin when it is not a terminal, and hang in an agent's shell. Pass `--input <file>`, or `< /dev/null` with `--set`.30- Send dict and list arguments as JSON: `-F 'filters:={"agent":"<user>"}'`.31- Sites add their own fields to `HD Ticket`. The ticket template, `HD Ticket Template` "Default", says which ones the app uses, in the order it shows them, and which are required: `method call helpdesk.helpdesk.doctype.hd_ticket_template.api.get_one -f name=Default`. `frappectl -s <p> doctype show "HD Ticket"` lists every field. Check one of them before you guess a field name.3233## 2. Find tickets and their data3435```sh36frappectl -s <p> doc list "HD Ticket" -f status_category=Open -f agent_group=<team> \37 --fields name,subject,status,priority,_assign,customer,response_by,agreement_status38frappectl -s <p> method call helpdesk.api.search.search -F query=<words> # subjects, descriptions, emails and comments39frappectl -s <p> doc get "HD Ticket" <ticket> # the ticket's fields40frappectl -s <p> method call frappe.desk.form.activity.get_activity_timeline -f doctype="HD Ticket" -f name=<ticket> # its emails, notes and changes41frappectl -s <p> method call helpdesk.helpdesk.doctype.hd_ticket.api.get_recent_similar_tickets -f ticket=<ticket>42frappectl -s <p> method call -X GET helpdesk.api.contact.get_contact_info -f name=<contact>43```4445The timeline lists everything that happened on the ticket, oldest first. Each activity has a `type`, an `author`, a `timestamp` and its `data`:4647- `email`: an email, with its `name`, `sender`, `subject` and `content`.48- `comment`: an internal note, with its `content`.49- `version`: a field change, with `fieldname`, `from` and `to`.50- `log`: the ticket was created, assigned or given an attachment.5152To keep only the conversation and the status changes, add `-F 'visible_types:=["email", "comment", {"version": ["status"]}]'`. It holds the latest 20 emails. When `has_more_emails` is true, `method call frappe.desk.form.activity.get_more_email_activities -f doctype="HD Ticket" -f name=<ticket> -F start=20` gives the 20 before them.5354Read emails and notes through the timeline: `doc list Communication` returns nothing for an agent.5556Common filters (mine, unassigned, overdue, a customer's, a date range): `reference/tickets.md`.5758For numbers across many tickets (counts, average response and resolution time, SLA breaches, ratings), use the methods in `reference/reports.md`. They count working hours the way the SLA does, which a `doc list` loop cannot.5960## 3. SLA: when is it due, why is it late6162`method call helpdesk.helpdesk.doctype.hd_ticket.api.get_one -f name=<ticket>` returns `overdue_by`, with `response` and `resolution` in working seconds past due. It is empty while the ticket is paused. `get_one` also marks the ticket as seen by the caller. The ticket itself has `sla`, `agreement_status` (First Response Due, Resolution Due, Paused, Failed or Fulfilled), `response_by`, `resolution_by`, `first_responded_on`, `on_hold_since`, `total_hold_time`, `first_response_failed_by` and `resolution_failed_by`.6364To explain a date, read the SLA named in `sla` with `doc get "HD Service Level Agreement" <sla>` (Agent Manager only): its priorities, working hours, breaks and holiday list. Without that role, `get_ticket_analytics` (`reference/tickets.md`) still gives each target and how far it was missed. `reference/sla.md` explains how the SLA is picked and the dates are worked out.6566## 4. Common tasks6768| Task | Call |69|---|---|70| Pick what to work on next | `doc list "HD Ticket" -f status_category=Open -f '_assign like %<user>%' --fields name,subject,priority,response_by,resolution_by,first_responded_on`. Each ticket is next due by its `response_by`, or by its `resolution_by` once `first_responded_on` is set. Sort on that and put the earliest first. With none of their own, offer their team's unassigned tickets (`reference/tickets.md`). |71| Reply to the customer | Before you write one, list the saved replies with `doc list "HD Saved Reply" --fields name,title`; when one fits, use "Reply with a saved reply". Show the human the draft and ask before you send it. Then `method call reply_via_agent --doctype "HD Ticket" --name <t> -F message="<html>"`. It emails the ticket's `raised_by`. Pass `to` (comma-separated) to send it elsewhere; with only `cc` or `bcc`, the customer is left out. Add `cc`, `bcc` or `attachments` (File names) when needed. A reply changes the status only when HD Settings `auto_update_status` is on. Read the ticket after sending, tell the human its status, and offer to change it: a Paused status such as Replied stops the SLA clock while you wait for the customer. When the reply, or what you changed on the ticket, repeats one you already did this session, also offer to save it ("Save a repeated reply"). |72| Add an internal note | `method call new_comment --doctype "HD Ticket" --name <t> -F content="<html>"` |73| Assign an agent | `method call assign_agent --doctype "HD Ticket" --name <t> -f agent=<user>`. It adds to the current assignees and notifies the agent. |74| Change status, priority, team or type | `doc update "HD Ticket" <t> --set status=<status> < /dev/null`. List the statuses with `doc list "HD Ticket Status" --fields name,category`. |75| Reply with a saved reply | `method call helpdesk.api.saved_replies.get_rendered_saved_reply -f ticket_id=<t> -f saved_reply_id=<name>`, change anything in its `message` that doesn't fit this ticket or that you can't confirm, send it with `reply_via_agent`, then pass its `actions` to `apply_saved_reply_actions -f ticket_id=<t> -F 'actions:=<actions>'` |76| Save a repeated reply | Offer it once a session, the second time you send much the same reply or make the same changes. Show the draft: a `title`, the `message` with the ticket's details replaced by fields such as `{{ subject }}`, using only fields `doctype show "HD Ticket"` lists, since any other renders empty (see the saved reply trap), the changes as `actions`, and `scope` Personal. Create it only on a yes, as `reference/setup.md` shows. Ask before making it Team or Global: it shows in other agents' lists. |77| Tag a ticket | `method call helpdesk.api.tags.update_tags -f doctype="HD Ticket" -f name=<t> -F 'added:=[{"name": "<tag>"}]'`. A new tag is created. To remove one, send `-F 'removed:=["<tag>"]'` instead. |78| Create a ticket for a contact | `doc create "HD Ticket" --input <file>` with `subject`, `description` (HTML), `raised_by` (their email), `contact` and, when they have one, `customer`. See `reference/tickets.md`. |79| Merge two tickets | `method call helpdesk.helpdesk.doctype.hd_ticket.api.merge_ticket -f source=<t> -f target=<t>`. It returns `{}`; `doc get` the source to see `merged_with`. |80| Split a ticket | `method call helpdesk.helpdesk.doctype.hd_ticket.api.split_ticket -f subject=<s> -f communication_id=<email>`. The email and every email and comment after it move to a new ticket. |81| Find a contact | `method call -X GET helpdesk.api.contact.search_contacts -f txt=<text>` |82| Create a contact | `method call helpdesk.api.contact.create_contact -F 'doc:={"first_name": "...", "last_name": "...", "email": "..."}'`. Put `"customer": "<c>"` in `doc` to add them to that customer. Nobody is emailed unless you add `-F invite:=true`, which invites them to the portal instead. |83| Create a customer | `method call helpdesk.api.customer.create_customer -F 'customer:={"customer_name": "...", "domain": "..."}'`. Add `-F 'primary_contact:={"email": "...", "first_name": "..."}'` to create and invite its first contact. |84| Add contacts to a customer | `method call add_contacts --doctype "HD Customer" --name <c> -F 'contacts:=["<contact or email>"]'`. A contact with a user is added. One without a user is emailed an invite instead, and comes back under `invite_result`, not `added`. With `-F invite:=false`, every contact is added and nobody is emailed; a missing contact can be created with its customer in one step ("Create a contact"). |85| Set up the helpdesk | `reference/setup.md` |8687For anything this file doesn't cover, find the method: `frappectl -s <p> method search -q "<one or two words>"` (every word must match), then `method show <path>` for its arguments, who may call it, what it returns and its code. Read that before you call it, and still mind the traps below. When nothing matches, the task is usually a field change: use `doctype show` and the `doc` commands. Search is for agents; a customer's profile is refused it, and a site on an older Frappe doesn't have it.8889## 5. Traps9091- **A reply emails the customer** when HD Settings `enable_reply_email_via_agent` is on. Show the human the reply and ask before you send it.92- **Never insert a `Communication` to reply.** The ticket still updates, but no email goes out and the reply is not threaded. An agent replies with `reply_via_agent`; a customer replies with `create_communication_via_contact` (`reference/customer.md`).93- **A merge cannot be undone.** It copies the source's emails, comments and files into the target, closes the source with `merged_with` set, and emails the customer on the source that it was merged. `doc get` both first: when their `raised_by` or `customer` differ, tell the human, because the target's contact will see the source's emails. Ask first.94- **Deletes can take tickets with them.** `delete_contact` and `delete_customer` with `delete_tickets` delete every linked ticket. Ask first, and name what will go.95- **Every save picks the SLA again and recalculates its dates.** Changing the priority, or a field an SLA condition reads, can switch the ticket to another SLA.96- **A contact sees a ticket** only when they are its `contact`, its `raised_by` or its owner. A customer's managers also see every ticket of that `customer`. Set these right on a ticket you create.97- **A ticket you create** records your user, not the contact, as the sender of its first email.98- **Team restrictions hide tickets.** With HD Settings `restrict_tickets_by_agent_group` on, an agent sees only their teams' tickets. A ticket that "does not exist" may be in another team.99- **Saved reply templates** see the ticket's fields and the signed-in user's `User` fields. Where both have a field (`name`, `owner`, `creation`), the user's wins: `{{ name }}` is the agent's user, not the ticket. Use `{{ subject }}` and other ticket-only fields.100101## Reference102103- `reference/tickets.md`: ticket fields, filters, the conversation, history, feedback, creating, merging and splitting.104- `reference/sla.md`: which SLA applies and how its due dates, pauses and breaches are worked out.105- `reference/reports.md`: ticket volume, response and resolution times, SLA breaches and ratings, for an agent, a team, a customer or a contact.106- `reference/customer.md`: everything a customer's profile can do, and the rules the portal enforces.107- `reference/setup.md`: agents, teams and assignment, SLAs and holiday lists, ticket types and priorities, saved replies and email accounts.