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

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.

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

Priorities

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

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