/freshdesk

name: freshdesk
description: Interact with Freshdesk support platform - search/view/update tickets, reply to customers, add notes, look up contacts, and manage Knowledge Base articles. Use when you need to manage support tickets, look up customer information, or work with KB content.
model: claude-sonnet-4-6

Freshdesk

Interact with the Freshdesk customer support platform via the v2 REST API. Search tickets, view conversations, reply to customers, add internal notes, update ticket properties, look up contacts, and manage Knowledge Base articles.

Setup

1. Copy `.env.example` to `.env` in this skill directory 2. Add your Freshdesk API key and domain

cp .claude/skills/freshdesk/.env.example .claude/skills/freshdesk/.env
# Edit .env and add your credentials

Get your API key from: Freshdesk Admin > Profile Settings > Your API Key

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | `FRESHDESK_TOKEN` | Yes | - | Your Freshdesk API key | | `FRESHDESK_DOMAIN` | Yes | - | Your Freshdesk domain (e.g., `https://yourcompany.freshdesk.com`) |

Running Commands

node .claude/skills/freshdesk/query.mjs <command> [options]

Commands

| Command | Description | |---------|-------------| | `tickets` | List recent tickets (default: 30, filterable) | | `ticket <id>` | Get ticket details with requester info | | `search <query>` | Search tickets (Freshdesk query syntax) | | `conversations <id>` | View ticket conversations (replies + notes) | | `investigate <id>` | Full ticket investigation (ticket + conversations + contact in one call) | | `reply <id> <message>` | Reply to a ticket (visible to customer) | | `note <id> <message>` | Add an internal note (not visible to customer) | | `update <id>` | Update ticket properties (status, priority, etc.) | | `contact <id\|email>` | Look up a contact by ID or email | | `contacts <query>` | Search contacts by name, email, or phone | | **Knowledge Base** | | | `kb-categories` | List all KB categories | | `kb-folders <category_id>` | List folders in a category | | `kb-articles <folder_id>` | List articles in a folder | | `kb-article <article_id>` | View a single KB article | | `kb-search <term>` | Search KB articles | | `kb-create <folder_id> <title>` | Create an article in a folder | | `kb-update <article_id>` | Update an article |

Ticket Status Codes

| Code | Status | |------|--------| | `2` | Open | | `3` | Pending | | `4` | Resolved | | `5` | Closed |

Ticket Priority Codes

| Code | Priority | |------|----------| | `1` | Low | | `2` | Medium | | `3` | High | | `4` | Urgent |

Article Status Codes

| Code | Status | |------|--------| | `1` | Draft | | `2` | Published |

Options

| Flag | Description | Applies To | |------|-------------|------------| | `--json` | Output raw JSON response | All commands | | `--status <code>` | Filter by status (2=Open, 3=Pending, 4=Resolved, 5=Closed) | `tickets` | | `--priority <code>` | Filter by priority (1=Low, 2=Medium, 3=High, 4=Urgent) | `tickets` | | `--page <n>` | Page number for paginated results | `tickets` | | `--set-status <code>` | Set ticket status | `update` | | `--set-priority <code>` | Set ticket priority | `update` | | `--set-agent <id>` | Assign ticket to agent ID | `update` | | `--set-group <id>` | Assign ticket to group ID | `update` | | `--set-type <type>` | Set ticket type | `update` | | `--set-tag <tag>` | Set ticket tag (replaces existing tags) | `update` | | `--private` | Make a note private (default for notes) | `note` | | `--body <text>` | Article body/description (HTML supported) | `kb-create`, `kb-update` | | `--set-title <text>` | Set article title | `kb-update` | | `--set-article-status <1\|2>` | Article status: 1=draft, 2=published | `kb-create`, `kb-update` |

Examples

List & Search Tickets

# List recent tickets
node .claude/skills/freshdesk/query.mjs tickets

# Filter by status (open tickets only)
node .claude/skills/freshdesk/query.mjs tickets --status 2

# Filter by priority (urgent)
node .claude/skills/freshdesk/query.mjs tickets --priority 4

# Search tickets with Freshdesk query syntax
node .claude/skills/freshdesk/query.mjs search "status:2 AND priority:4"

# Search by requester email
node .claude/skills/freshdesk/query.mjs search "email:'user@example.com'"

# Search by subject keyword
node .claude/skills/freshdesk/query.mjs search "subject:'payment issue'"

# Get raw JSON
node .claude/skills/freshdesk/query.mjs tickets --json

View Ticket Details

# Get ticket details
node .claude/skills/freshdesk/query.mjs ticket 12345

# View conversation history
node .claude/skills/freshdesk/query.mjs conversations 12345

# Full investigation (ticket + conversations + contact)
node .claude/skills/freshdesk/query.mjs investigate 12345

# Investigation as JSON (returns { ticket, conversations, contact })
node .claude/skills/freshdesk/query.mjs investigate 12345 --json

# Raw JSON output
node .claude/skills/freshdesk/query.mjs ticket 12345 --json

Reply & Notes

# Reply to a ticket (visible to customer)
node .claude/skills/freshdesk/query.mjs reply 12345 "Thanks for reaching out! We're looking into this."

# Add an internal note (not visible to customer)
node .claude/skills/freshdesk/query.mjs note 12345 "Checked user account - subscription is active, issue is with billing sync"

Update Tickets

# Change status to Pending
node .claude/skills/freshdesk/query.mjs update 12345 --set-status 3

# Set priority to High
node .claude/skills/freshdesk/query.mjs update 12345 --set-priority 3

# Assign to agent
node .claude/skills/freshdesk/query.mjs update 12345 --set-agent 67890

# Multiple updates at once
node .claude/skills/freshdesk/query.mjs update 12345 --set-status 2 --set-priority 3 --set-agent 67890

Contact Lookup

# Look up by email
node .claude/skills/freshdesk/query.mjs contact user@example.co