/ticketing

name: "Freshdesk Ticketing"
description: >
  Freshdesk ticket operations: list, get, search, create, update, reply, notes,
  and conversation threads. Covers status/priority/source integer encodings,
  core requester / assignment / SLA fields, the search query language, and the
  MSP creation, triage, and escalation workflows through the Freshdesk REST
  API v2.
when_to_use: >-
  When listing, searching, creating, updating, replying to, or summarizing Freshdesk tickets and
  their conversations. Use when: freshdesk ticket, freshdesk reply, freshdesk ticket note,
  freshdesk conversation, create ticket freshdesk, search tickets freshdesk, ticket triage
  freshdesk, resolve ticket freshdesk, or ticket status freshdesk.

Freshdesk Ticket Management

Overview

Tickets are the core unit of service delivery in Freshdesk. Every customer request, incident, and task flows through the ticketing system. This skill covers listing, getting, searching, creating, updating, replying, adding notes, and reading conversation threads via the Freshdesk REST API v2, surfaced through tools named `freshdesk_tickets_<action>`.

Anti-triggers

A Freshdesk ticket may carry `type: "Incident"`, which collides with two other meanings of the word. The routing test is what the operator does next: answer a customer under an SLA clock (this skill), page a responder, or approve a remediation on a compromised endpoint.

• **An on-call service incident** — something is broken and a human must

be woken up; the deliverable is acknowledgement and restoration, not a customer reply. Use `pagerduty-incidents` or `rootly-incidents`.

• **A confirmed security incident** — malware or intrusion with a

remediation to approve. Use `huntress-incidents`, or `sentinelone-alerts` for raw EDR detections. Never draft a customer reply about containment from this skill's data alone.

• **Tickets in another helpdesk or PSA** — the vocabulary is nearly

identical but the field models are not (Freshdesk encodes status and priority as integers; the PSAs use instance-configurable IDs). Use `halopsa-tickets`, `connectwise-psa-tickets`, or `autotask-tickets`.

• **Why `due_by` or `fr_due_by` has the value it does** — deadline

computation, business-hours calendars, and breach detection are `freshdesk-sla-business-hours`; this skill only reads the timestamps.

• **Resolving the requester to a person or company** — contact lookup,

creation, and merge are `freshdesk-contacts-companies`.

Status, Priority & Source Encodings

Freshdesk encodes these fields as integers in both the API payloads and the search query language.

Status

| Value | Status | Business Logic | |-------|--------|----------------| | 2 | Open | Default for new tickets; needs action | | 3 | Pending | Waiting on customer or third party; clock may pause | | 4 | Resolved | Issue addressed; awaiting confirmation | | 5 | Closed | Ticket complete; no further action |

Priority

| Value | Priority | Typical Response | |-------|----------|------------------| | 1 | Low | Next business day | | 2 | Medium | Same business day | | 3 | High | 1-2 hours | | 4 | Urgent | Immediate response |

Source

| Value | Source | |-------|--------| | 1 | Email | | 2 | Portal | | 3 | Phone |

(Additional source codes exist for chat, feedback widget, and other channels.)

Key Ticket Fields

Core Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | Integer | System | Auto-generated unique identifier | | `subject` | String | Yes | Brief issue summary | | `description` | String (HTML) | Yes (on create) | Detailed description | | `status` | Integer | No | 2 Open, 3 Pending, 4 Resolved, 5 Closed | | `priority` | Integer | No | 1 Low, 2 Medium, 3 High, 4 Urgent | | `source` | Integer | No | 1 Email, 2 Portal, 3 Phone | | `type` | String | No | Ticket type (e.g. Incident, Service Request) | | `tags` | Array | No | Free-form labels |

Requester & Assignment Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `requester_id` | Integer | One of requester fields | Contact ID of the requester | | `email` | String | One of requester fields | Requester email (creates a contact if new) | | `responder_id` | Integer | No | Assigned agent ID | | `group_id` | Integer | No | Assigned group ID | | `company_id` | Integer | No | Associated company ID |

SLA Fields

| Field | Type | Description | |-------|------|-------------| | `due_by` | Timestamp | Resolution-due deadline (driven by SLA policy + business hours) | | `fr_due_by` | Timestamp | First-response-due deadline |

When creating a ticket you must supply `subject`, `description`, and a requester (`requester_id` **or** `email`). Status defaults to Open (2) and priority to Low (1) if omitted.

Operations

List Tickets

GET /api/v2/tickets?per_page=100&page=1

Common query params: `filter` (e.g. `new_and_my_open`, `watching`, `spam`, `deleted`), `updated_since`, `order_by`, `order_type`. Use `include=requester,stats` to embed related data.

Get a Single Ticket

GET /api/v2/tickets/{id}?include=conversations,requester,company,stats

`include=conversations` embeds the reply/note thread; `include=stats` adds resolution and first-response timestamps useful for SLA checks.

Search Tickets

GET /api/v2/search/tickets?query="status:2 AND priority:4"

The query language wraps the whole expression in double quotes, combines clauses with `AND` / `OR`, and supports fields such as `status`, `priority`, `agent_id`, `group_id`, `type`, `tag`, `created_at`, and `updated_at`. Search returns up to 30 results per page and a maximum of 10 pages (300 records) — narrow the query when a result set would exceed that.

# Unresolved urgent tickets
"status:2 AND priority:4"

# A group's high/urgent backlog created this month
"group_id:7 AND (priority:3 OR priority:4) AND created_at:>'2024-02-01'"