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

Copy .env.example to .env in this skill directory
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.com

# Look up by contact ID
node .claude/skills/freshdesk/query.mjs contact 98765

# Search contacts
node .claude/skills/freshdesk/query.mjs contacts "john"

# Raw JSON
node .claude/skills/freshdesk/query.mjs contact user@example.com --json

Knowledge Base

# List all KB categories
node .claude/skills/freshdesk/query.mjs kb-categories

# List folders in a category
node .claude/skills/freshdesk/query.mjs kb-folders 12345

# List articles in a folder
node .claude/skills/freshdesk/query.mjs kb-articles 67890

# View a single article
node .claude/skills/freshdesk/query.mjs kb-article 111

# Search KB articles
node .claude/skills/freshdesk/query.mjs kb-search "billing"

# Create a new article (draft by default)
node .claude/skills/freshdesk/query.mjs kb-create 67890 "How to Reset Password" --body "<p>Steps to reset your password...</p>"

# Create a published article
node .claude/skills/freshdesk/query.mjs kb-create 67890 "Getting Started" --body "<p>Welcome guide...</p>" --set-article-status 2

# Update an article's title and body
node .claude/skills/freshdesk/query.mjs kb-update 111 --set-title "Updated Title" --body "<p>New content</p>"

# Publish a draft article
node .claude/skills/freshdesk/query.mjs kb-update 111 --set-article-status 2

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

Output Format

Ticket List

ID     | Status  | Priority | Subject                    | Requester
-------|---------|----------|----------------------------|------------------
12345  | Open    | High     | Can't upload models        | user@example.com
12346  | Pending | Medium   | Billing question           | other@example.com

Ticket Detail

Ticket #12345
Subject: Can't upload models
Status: Open | Priority: High | Type: Problem
Requester: user@example.com
Created: 2025-01-15 | Updated: 2025-01-16
Tags: upload, bug
Description:
  I'm trying to upload a model but getting an error...

Conversation

--- Reply by Agent (2025-01-16 10:30) ---
Thanks for reporting this. Can you share the error message?

--- Reply by Customer (2025-01-16 11:45) ---
Sure, it says "File too large"...

--- Note (private) by Agent (2025-01-16 12:00) ---
User is on free tier, file size limit applies.

Freshdesk Search Query Syntax

The search command uses Freshdesk's query language:

Query	Description
`"status:2"`	Open tickets
`"priority:4"`	Urgent tickets
`"agent_id:123"`	Tickets assigned to agent
`"group_id:456"`	Tickets in group
`"tag:'billing'"`	Tickets with tag
`"created_at:>'2025-01-01'"`	Created after date
`"email:'user@example.com'"`	By requester email
`"status:2 AND priority:3"`	Combine with AND/OR

When to Use

Investigating user issues: Look up tickets to understand customer problems
Responding to support: Reply to tickets or add internal notes
Ticket management: Update status, priority, assignments
Customer lookup: Find contact info and ticket history
Support analytics: Search and filter tickets by various criteria
Knowledge Base management: Browse, search, create, and update KB articles

Safety Guardrails

CRITICAL: The following actions require explicit human confirmation and must NEVER be performed automatically.

Forbidden Auto-Actions

These actions must be flagged as [REQUIRES HUMAN ACTION] and never executed without explicit human approval:

Action	Risk	Handling
Refunds (Stripe, Paddle, Buzz)	Financial	Flag and defer to human
Free Buzz grants	Financial	Flag and defer to human
Free subscriptions or upgrades	Financial	Flag and defer to human
Account deletion	Irreversible	Flag and defer to human
Password resets / email changes	Security	Flag and defer to human
Subscription cancellation	Financial	Flag and defer to human
Unbanning users	Safety	Flag and defer to human
Any monetary or financial action	Financial	Flag and defer to human

Behavior When Encountered

Flag it: Mark the action as [REQUIRES HUMAN ACTION] in your response
Never promise: Do not tell the customer the action will be taken
Draft safely: Write reply drafts that acknowledge the request without committing to the action (e.g., "I've escalated your refund request to our team" NOT "Your refund has been processed")
Recommend manual handling: Tell the support agent which team/person should handle it

Safe Actions (OK to perform)

Read-only lookups (tickets, contacts, user data via postgres/clickhouse)
Adding internal notes to tickets
Updating ticket status and priority
Creating ClickUp tasks for engineering issues
Drafting reply text for human review

Cross-Platform Workflows

Investigation Workflow

Use this workflow when a support ticket needs full context before responding.

Steps:

Run investigate <ticket-id> to get ticket + conversations + contact in one call
Extract the Civitai user ID from the contact's unique_external_id field (format: civitai-{userId})

Query postgres for user account details:

# Use /postgres-query skill
SELECT id, username, email, "bannedAt", "muted", "createdAt" FROM "User" WHERE id = {userId};

Query postgres for subscription info:

SELECT * FROM "CustomerSubscription" WHERE "userId" = {userId} ORDER BY "createdAt" DESC LIMIT 1;

Optionally query ClickHouse for recent activity:

# Use /clickhouse-query skill — see "Common ClickHouse Queries" below for real table names
SELECT * FROM views WHERE visitorId = {userId} ORDER BY createdAt DESC LIMIT 20;

Present a unified summary with:
- Issue classification (see Triage table below)
- User account status (active, banned, muted, subscription tier)
- Relevant history from conversations
- Any [REQUIRES HUMAN ACTION] flags for forbidden actions

Triage Workflow

Use this classification table to route tickets appropriately:

Issue Type	Priority	Routing	Notes
Buzz / Payment issues	High	Support (financial)	`[REQUIRES HUMAN ACTION]` for refunds
Upload / Publishing errors	Medium	Engineering if bug confirmed	Create ClickUp task if reproducible
Account Access (login, 2FA)	High	Support	`[REQUIRES HUMAN ACTION]` for password/email changes
Content Moderation (reports, takedowns)	Medium	Moderation team	Check `/mod-actions` for history
Legal / DMCA	Urgent	Legal / Compliance	Never handle directly, escalate immediately
Bug Report	Medium-High	ClickUp + Engineering	Create task with repro steps
Feature Request	Low	ClickUp task	Tag as feature-request

Draft Reply Workflow

Use this when composing a customer-facing response.

Steps:

Run investigate <ticket-id> for full context
Identify the issue type and current resolution state
Draft an empathetic, professional response:
- Acknowledge the user's frustration or question
- Summarize what you found (without exposing internal details)
- Explain next steps clearly
- Never promise forbidden actions (refunds, free Buzz, etc.)
Present the draft for human review — never auto-send replies
Only send with explicit approval from the support agent

ClickUp Integration Workflow

Use when a ticket reveals a bug or engineering issue that needs tracking.

Steps:

Create a ClickUp task using the /clickup skill:
- Title: Brief description of the bug/issue
- Description: Include repro steps from the ticket, Freshdesk ticket number, affected user ID
- Priority: Based on triage severity

Add an internal note to the Freshdesk ticket linking to the ClickUp task:

node .claude/skills/freshdesk/query.mjs note {ticket-id} "ClickUp task created: {task-url} - Tracking as engineering issue"

Optionally assign the ClickUp task to the relevant engineer

Discord Notification Workflow

Use when critical or systemic issues are detected that need team awareness.

When to trigger:

3+ similar tickets received within 1 hour (pattern detected)
Service outage indicators (multiple users reporting same failure)
Payment system issues affecting multiple users

Steps:

Identify the pattern (similar error messages, same feature affected, same timeframe)
Use the /discord skill to send a rich embed to the appropriate channel:
- Ticket count: How many tickets match the pattern
- Sample ticket: Link/ID of a representative ticket
- Affected feature: Which part of the platform is impacted
- Impact description: Brief summary of user impact

Channel routing guidance:

Engineering alerts → service outages, infrastructure issues, critical bugs
Moderation → abuse reports, content policy violations
Support → general ticket volume spikes, payment issues

Civitai User Lookup Reference

Freshdesk → Civitai Mapping

Freshdesk contacts are linked to Civitai accounts via the unique_external_id field:

Format: civitai-{userId} (e.g., civitai-12345 → Civitai user ID 12345)
The investigate command extracts this automatically in the Quick Reference section

Common Postgres Queries

-- Find user by email
SELECT id, username, email, "bannedAt", "muted", "createdAt" FROM "User" WHERE email = 'user@example.com';

-- Find user by ID
SELECT id, username, email, "bannedAt", "muted", "createdAt" FROM "User" WHERE id = 12345;

-- Check active subscription
SELECT cs.*, p.name as "productName"
FROM "CustomerSubscription" cs
LEFT JOIN "Product" p ON cs."productId" = p.id
WHERE cs."userId" = 12345 AND cs."status" = 'active';

-- Check recent purchases
SELECT * FROM "Purchase" WHERE "userId" = 12345 ORDER BY "createdAt" DESC LIMIT 10;

Note: Buzz balances are NOT stored in PostgreSQL. They are managed by an external Buzz microservice. Use the application's Buzz API endpoints or check the user's account via the admin dashboard.

Common ClickHouse Queries

Real ClickHouse tables used in the codebase (use /clickhouse-query skill):

-- Recent page views by a user
SELECT * FROM views WHERE visitorId = 12345 ORDER BY createdAt DESC LIMIT 20;

-- User actions (tips, purchases, etc.)
SELECT * FROM actions WHERE userId = 12345 ORDER BY createdAt DESC LIMIT 20;

-- Model events (downloads, publishes, etc.)
SELECT * FROM modelEvents WHERE userId = 12345 ORDER BY createdAt DESC LIMIT 20;

-- User activities (registration, login, account changes)
SELECT * FROM userActivities WHERE userId = 12345 ORDER BY createdAt DESC LIMIT 20;

Other Skill References

Mod actions: Use /mod-actions to check moderation history or take moderation actions. Banning is a safe action, but unbanning requires [REQUIRES HUMAN ACTION]
Redis debugging: Use /redis-inspect to check session data or cache state
Retool data: Use /retool-query for moderation notes and user notes from the Retool database

Subscription Tier Reference

Tier	Description
Free	Default, no subscription
Supporter	Basic paid tier
Bronze	Mid-level tier
Silver	Higher tier
Gold	Premium tier
Buzz Purchaser	One-time Buzz purchase, not a subscription

Tips

Use search with Freshdesk query syntax for advanced filtering
Always check conversations to see full ticket history before replying
Use note for internal team comments (not visible to customers)
Use reply for customer-facing responses
Combine --set-status with reply workflow: reply first, then update status
Contact lookup by email is the most reliable method