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
