Freshdesk

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

Running Commands

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

Commands

Ticket Status Codes

Ticket Priority Codes

Article Status Codes

Options

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:

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:

Behavior When Encountered

1. Flag it: Mark the action as [REQUIRES HUMAN ACTION] in your response
2. Never promise: Do not tell the customer the action will be taken
3. 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")
4. 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:

1. Run investigate <ticket-id> to get ticket + conversations + contact in one call
2. Extract the Civitai user ID from the contact's unique_external_id field (format: civitai-{userId})
3. Query postgres for user account details:

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

4. Query postgres for subscription info:

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

5. 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;
   

6. 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:

Draft Reply Workflow

Use this when composing a customer-facing response.

Steps:

1. Run investigate <ticket-id> for full context
2. Identify the issue type and current resolution state
3. 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.)
4. Present the draft for human review — never auto-send replies
5. 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:

1. 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
2. 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"
   

3. 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:

1. Identify the pattern (similar error messages, same feature affected, same timeframe)
2. 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

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