freshdesk

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name FRESHDESK_TOKEN` or `zero doctor check-connector --url https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets --method GET`

## How to Use

All examples assume `FRESHDESK_TOKEN` (API key) and `FRESHDESK_DOMAIN` (your subdomain, e.g. `acme` from `acme.freshdesk.com`) are set.

Base URL: `https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2`

Authentication: HTTP Basic — API key as username, literal `X` as dummy password. The curl `-u` flag handles Base64 encoding for you:

```bash
-u "$FRESHDESK_TOKEN:X"
```

### 1. List Tickets

Get all tickets (default 30 per page):

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, subject, status, priority}'
```

With pagination:

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=1&per_page=100" -u "$FRESHDESK_TOKEN:X"
```

Filter by updated date (tickets updated in last 30 days):

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2026-03-18T00:00:00Z" -u "$FRESHDESK_TOKEN:X"
```

### 2. Get Ticket

Retrieve a specific ticket (replace `<ticket-id>` with the ID from the list response):

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>" -u "$FRESHDESK_TOKEN:X"
```

Include requester, company, and stats:

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>?include=requester,company,stats" -u "$FRESHDESK_TOKEN:X"
```

### 3. Create Ticket

Write to `/tmp/freshdesk_request.json`:

```json
{
  "subject": "Support needed",
  "description": "Customer cannot access their dashboard.",
  "email": "[email protected]",
  "priority": 2,
  "status": 2
}
```

Then run:

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

Priority values: `1` (Low), `2` (Medium), `3` (High), `4` (Urgent)
Status values: `2` (Open), `3` (Pending), `4` (Resolved), `5` (Closed)
Source values: `1` (Email), `2` (Portal), `3` (Phone), `7` (Chat), `9` (Feedback widget), `10` (Outbound email)

### 4. Update Ticket

Write to `/tmp/freshdesk_request.json`:

```json
{
  "status": 4,
  "priority": 3,
  "tags": ["resolved", "billing"]
}
```

Then run (replace `<ticket-id>`):

```bash
curl -s -X PUT "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 5. Delete Ticket

```bash
curl -s -X DELETE "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>" -u "$FRESHDESK_TOKEN:X"
```

### 6. Filter Tickets (Advanced Search)

Freshdesk supports a query DSL. Write the query to `/tmp/freshdesk_query.txt`:

```
"status:2 AND priority:4"
```

Then run:

```bash
curl -s -G "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets" -u "$FRESHDESK_TOKEN:X" --data-urlencode "query@/tmp/freshdesk_query.txt" | jq '.results[] | {id, subject, status, priority}'
```

Common filter operators: `:`, `>`, `<`, `AND`, `OR`. Filterable fields include `status`, `priority`, `agent_id`, `group_id`, `created_at`, `updated_at`, `tag`, and any custom field.

### 7. List Conversations (Notes and Replies) on a Ticket

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>/conversations" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, body_text, private, user_id, created_at}'
```

### 8. Reply to a Ticket

Public reply visible to the requester. Write to `/tmp/freshdesk_request.json`:

```json
{
  "body": "Thanks for reaching out — we are investigating and will update you shortly."
}
```

Then run:

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>/reply" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 9. Add a Private Note to a Ticket

Internal note not visible to the requester. Write to `/tmp/freshdesk_request.json`:

```json
{
  "body": "Escalating to engineering — related to incident #42.",
  "private": true
}
```

Then run:

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>/notes" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 10. List Contacts

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, name, email, company_id}'
```

### 11. Create Contact

Write to `/tmp/freshdesk_request.json`:

```json
{
  "name": "Jane Customer",
  "email": "[email protected]",
  "phone": "+1-555-0100"
}
```

Then run:

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 12. Search Contacts

Write the query to `/tmp/freshdesk_query.txt`:

```
"email:'[email protected]'"
```

Then run:

```bash
curl -s -G "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/contacts" -u "$FRESHDESK_TOKEN:X" --data-urlencode "query@/tmp/freshdesk_query.txt" | jq '.results[] | {id, name, email}'
```

### 13. List Companies

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/companies" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, name, domains}'
```

### 14. Create Company

Write to `/tmp/freshdesk_request.json`:

```json
{
  "name": "Acme Inc",
  "domains": ["acme.com"],
  "description": "Priority customer"
}
```

Then run:

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/companies" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 15. List Agents

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/agents" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, contact: {name: .contact.name, email: .contact.email}, available}'
```

### 16. Get Current Authenticated Agent

Useful to verify the API key works and see your own agent ID:

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/agents/me" -u "$FRESHDESK_TOKEN:X"
```

### 17. List Groups

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/groups" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, name, agent_ids}'
```

### 18. Assign Ticket to an Agent and Group

Write to `/tmp/freshdesk_request.json` (replace agent/group IDs with values from the previous list endpoints):

```json
{
  "responder_id": <agent-id>,
  "group_id": <group-id>,
  "status": 2
}
```

Then run:

```bash
curl -s -X PUT "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/<ticket-id>" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

### 19. List Solution Categories (Knowledge Base)

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/solutions/categories" -u "$FRESHDESK_TOKEN:X" | jq '.[] | {id, name, description}'
```

List folders in a category:

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/solutions/categories/<category-id>/folders" -u "$FRESHDESK_TOKEN:X"
```

List articles in a folder:

```bash
curl -s "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/solutions/folders/<folder-id>/articles" -u "$FRESHDESK_TOKEN:X"
```

### 20. Create a Solution Article

Write to `/tmp/freshdesk_request.json`:

```json
{
  "title": "How to reset your password",
  "description": "<p>Follow these steps to reset your password...</p>",
  "status": 2
}
```

Status values for articles: `1` (Draft), `2` (Published).

Then run (replace `<folder-id>`):

```bash
curl -s -X POST "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/solutions/folders/<folder-id>/articles" --header "Content-Type: application/json" -u "$FRESHDESK_TOKEN:X" -d @/tmp/freshdesk_request.json
```

## Common Workflows

### Triage: Find all urgent unassigned tickets

Write to `/tmp/freshdesk_query.txt`:

```
"priority:4 A