Zendesk

Setup

On first use, read setup.md for API credentials and workspace integration.

When to Use

User needs to interact with Zendesk: create or update tickets, search support history, check user details, or automate support workflows. Agent handles API operations, ticket management, and reporting.

Architecture

Memory at ~/zendesk/. See memory-template.md for structure.

~/zendesk/
├── memory.md        # Credentials + preferences + recent context
├── templates/       # Saved ticket templates and macros
└── exports/         # Report exports and ticket dumps

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md
API operations	api-reference.md
Common issues	troubleshooting.md

Core Rules

1. Authenticate Before Operations

Credentials from environment variables (ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN) or ~/zendesk/memory.md.

# Test auth
curl -u "$ZENDESK_EMAIL/token:$ZENDESK_TOKEN" "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json"

2. Search Before Create

Always search existing tickets before creating new ones to avoid duplicates.

curl -u "$AUTH" "$BASE/search.json?query=type:ticket+subject:issue"

3. Use Views for Efficiency

Don't list all tickets. Use views to get relevant subsets.

View	Use Case
/views/active	Get available views
/views/{id}/tickets	Tickets in specific view
/tickets/recent	Recently updated

4. Preserve Ticket History

When updating, add internal notes explaining changes. Never delete ticket data.

5. Rate Limits

Zendesk limits: 700 requests/minute (Enterprise), 200/minute (others). Add delays for bulk operations.

6. Always Confirm Destructive Actions

Before closing, merging, or deleting tickets, confirm with user and summarize what will happen.

Common Operations

Set auth: AUTH="$ZENDESK_EMAIL/token:$ZENDESK_TOKEN" and BASE="https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2"

Create Ticket

curl -X POST "$BASE/tickets.json" -u "$AUTH" -H "Content-Type: application/json" \
  -d '{"ticket":{"subject":"Issue","comment":{"body":"Description"},"priority":"normal"}}'

Update Ticket Status

curl -X PUT "$BASE/tickets/$ID.json" -u "$AUTH" -H "Content-Type: application/json" \
  -d '{"ticket":{"status":"solved","comment":{"body":"Resolution","public":false}}}'

Search Tickets

curl -u "$AUTH" "$BASE/search.json?query=type:ticket+status:open+priority:urgent"

Get User Details

curl -u "$AUTH" "$BASE/users/search.json?query=email:user@example.com"

Ticket Statuses

Status	Meaning	Next Actions
new	Unassigned	Assign, respond
open	Being worked	Update, solve
pending	Waiting on customer	Follow up, solve
hold	Waiting internally	Unhold, update
solved	Resolution provided	Close (auto after 4 days)
closed	Final	Reopen creates new ticket

Priorities

Priority	SLA Target	Use For
urgent	1 hour	System down, revenue impact
high	4 hours	Major feature broken
normal	8 hours	Standard issues
low	24 hours	Questions, minor bugs

Common Traps

• Auth format wrong → Must be email/token:API_TOKEN, not just token
• Searching with special chars → URL-encode queries
• Bulk updates failing → Check rate limits, add 100ms delay
• Missing ticket fields → Some fields require specific plans
• Pagination ignored → Results capped at 100, use next_page URL

External Endpoints

Endpoint	Data Sent	Purpose
https://{subdomain}.zendesk.com/api/v2/*	Ticket/user data	All operations

No other data is sent externally.

Security & Privacy

Data that leaves your machine:

• Ticket content sent to Zendesk API
• Search queries sent to Zendesk

Data that stays local:

• API credentials in ~/zendesk/memory.md
• Exported reports in ~/zendesk/exports/

This skill does NOT:

• Store credentials in plain text outside ~/zendesk/
• Send data to any service other than Zendesk
• Access tickets without explicit user request

Trust

By using this skill, ticket and user data is sent to Zendesk's API. Only install if you have authorized Zendesk API access.

Related Skills

Install with clawhub install <slug> if user confirms:

• api - REST API patterns
• customer-support - Support best practices
• csv - Export and analyze ticket data

Feedback

• If useful: clawhub star zendesk
• Stay updated: clawhub sync