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.
CODEBLOCK0
Quick Reference
| Topic | File |
|---|
| Setup process | INLINECODE3 |
| 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, ZENDESKEMAIL, ZENDESK_TOKEN) or
~/zendesk/memory.md.
CODEBLOCK1
2. Search Before Create
Always search existing tickets before creating new ones to avoid duplicates.
CODEBLOCK2
3. Use Views for Efficiency
Don't list all tickets. Use views to get relevant subsets.
| View | Use Case |
|---|
| INLINECODE8 | Get available views |
| INLINECODE9 |
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 INLINECODE12
Create Ticket
CODEBLOCK3
Update Ticket Status
CODEBLOCK4
Search Tickets
CODEBLOCK5
Get User Details
CODEBLOCK6
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 |
|---|
| INLINECODE15 | 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 - INLINECODE18 - Support best practices
- INLINECODE19 - Export and analyze ticket data
Feedback
- - If useful: INLINECODE20
- Stay updated: INLINECODE21
设置
首次使用时，请阅读 setup.md 获取API凭证和工作区集成信息。
使用时机
用户需要与Zendesk交互时：创建或更新工单、搜索支持历史、查看用户详情或自动化支持工作流程。代理负责处理API操作、工单管理和报告生成。
架构
内存目录位于 ~/zendesk/。结构参考 memory-template.md。
~/zendesk/
├── memory.md # 凭证 + 偏好设置 + 近期上下文
├── templates/ # 保存的工单模板和宏
└── exports/ # 报告导出和工单数据导出
快速参考
memory-template.md |
| API操作 | api-reference.md |
| 常见问题 | troubleshooting.md |
核心规则
1. 操作前先认证
凭证来自环境变量（ZENDESK
SUBDOMAIN、ZENDESKEMAIL、ZENDESK_TOKEN）或 ~/zendesk/memory.md。
bash
测试认证
curl -u $ZENDESK
EMAIL/token:$ZENDESKTOKEN https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json
2. 创建前先搜索
创建新工单前务必先搜索现有工单，避免重复。
bash
curl -u $AUTH $BASE/search.json?query=type:ticket+subject:issue
3. 使用视图提高效率
不要列出所有工单。使用视图获取相关子集。
| 视图 | 使用场景 |
|---|
| /views/active | 获取可用视图 |
| /views/{id}/tickets |
特定视图中的工单 |
| /tickets/recent | 最近更新的工单 |
4. 保留工单历史
更新时添加内部备注说明变更原因。切勿删除工单数据。
5. 速率限制
Zendesk限制：企业版700次/分钟，其他版本200次/分钟。批量操作需添加延迟。
6. 破坏性操作需确认
关闭、合并或删除工单前，需向用户确认并说明操作后果。
常用操作
设置认证：AUTH=$ZENDESKEMAIL/token:$ZENDESKTOKEN 和 BASE=https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2
创建工单
bash
curl -X POST $BASE/tickets.json -u $AUTH -H Content-Type: application/json \
-d {ticket:{subject:问题,comment:{body:描述},priority:normal}}
更新工单状态
bash
curl -X PUT $BASE/tickets/$ID.json -u $AUTH -H Content-Type: application/json \
-d {ticket:{status:solved,comment:{body:解决方案,public:false}}}
搜索工单
bash
curl -u $AUTH $BASE/search.json?query=type:ticket+status:open+priority:urgent
获取用户详情
bash
curl -u $AUTH $BASE/users/search.json?query=email:user@example.com
工单状态
正在处理 | 更新、解决 |
| pending | 等待客户 | 跟进、解决 |
| hold | 等待内部处理 | 解除等待、更新 |
| solved | 已提供解决方案 | 关闭（4天后自动关闭） |
| closed | 最终状态 | 重新打开会创建新工单 |
优先级
| 优先级 | SLA目标 | 适用场景 |
|---|
| urgent | 1小时 | 系统宕机、影响收入 |
| high |
4小时 | 主要功能故障 |
| normal | 8小时 | 标准问题 |
| low | 24小时 | 咨询、小问题 |
常见陷阱
- - 认证格式错误 → 必须使用 email/token:APITOKEN，不能仅使用token
- 搜索含特殊字符 → 对查询进行URL编码
- 批量更新失败 → 检查速率限制，添加100ms延迟
- 缺少工单字段 → 某些字段需要特定套餐
- 忽略分页 → 结果上限为100条，使用 nextpage URL
外部端点
| 端点 | 发送数据 | 用途 |
|---|
| https://{subdomain}.zendesk.com/api/v2/* | 工单/用户数据 | 所有操作 |
不向其他外部发送数据。
安全与隐私
离开您设备的数据：
- - 发送至Zendesk API的工单内容
- 发送至Zendesk的搜索查询
保留在本地设备的数据：
- - ~/zendesk/memory.md中的API凭证
- ~/zendesk/exports/中的导出报告
此技能不会：
- - 在~/zendesk/目录外以明文存储凭证
- 向Zendesk以外的任何服务发送数据
- 未经用户明确请求访问工单
信任声明
使用此技能即表示工单和用户数据将被发送至Zendesk的API。
仅在您已授权Zendesk API访问权限时安装。
相关技能
如果用户确认，使用 clawhub install 安装：
- - api - REST API模式
- customer-support - 支持最佳实践
- csv - 导出和分析工单数据
反馈
- - 如果觉得有用：clawhub star zendesk
- 保持更新：clawhub sync
