zendesk-automation

通过 Rube MCP 自动化 Zendesk

通过 Rube MCP 使用 Composio 的 Zendesk 工具包自动化 Zendesk 操作。

工具包文档：composio.dev/toolkits/zendesk

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Zendesk 连接，并指定工具包 zendesk
• 始终先调用 RUBE_SEARCH_TOOLS，以获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥，只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 zendesk
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Zendesk 授权
4. 在运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 列出和搜索工单

适用场景：用户想查看、筛选或搜索支持工单

工具调用顺序：

1. ZENDESK_LIST_ZENDESK_TICKETS - 分页列出所有工单 [必需]
2. ZENDESK_GET_ZENDESK_TICKET_BY_ID - 获取指定工单的详细信息 [可选]

关键参数：

• page：页码（从 1 开始）
• per_page：每页结果数（最多 100）
• sort_by：排序字段（'created_at'、'updated_at'、'priority'、'status'）
• sort_order：'asc' 或 'desc'
• ticket_id：要单独获取的工单 ID

注意事项：

• LIST 使用 page/per_page 分页，而非基于 offset 的分页；请检查响应中的 next_page
• 每页最多返回 100 条结果；请按页码迭代，直到 next_page 为 null
• LIST 不会返回已删除的工单；请使用 GET_BY_ID，该工具会返回状态为 'deleted' 的工单
• GET_BY_ID 会包含工单评论和审计记录，但 LIST 响应中不包含这些内容

2. 创建和更新工单

适用场景：用户想创建新工单或修改现有工单

工具调用顺序：

1. ZENDESK_SEARCH_ZENDESK_USERS - 查找请求者/受派人 [前置条件]
2. ZENDESK_CREATE_ZENDESK_TICKET - 创建新工单 [必需]
3. ZENDESK_UPDATE_ZENDESK_TICKET - 更新工单字段 [可选]
4. ZENDESK_DELETE_ZENDESK_TICKET - 删除工单 [可选]

关键参数：

• subject：工单主题
• description：工单正文（用于创建；会成为第一条评论）
• priority：'urgent'、'high'、'normal'、'low'
• status：'new'、'open'、'pending'、'hold'、'solved'、'closed'
• type：'problem'、'incident'、'question'、'task'
• assignee_id：受派 Agent 的用户 ID
• requester_id：请求者的用户 ID
• tags：标签字符串数组
• ticket_id：工单 ID（用于更新/删除）

注意事项：

• UPDATE 中的标签会完全替换现有标签；若要保留现有标签，请与当前标签合并
• 使用 safe_update 和 updated_stamp，以避免并发修改冲突
• DELETE 是永久且不可逆的；工单无法恢复
• description 仅用于创建工单；创建后请使用 REPLY_ZENDESK_TICKET 添加评论
• 已关闭的工单无法更新；请改为创建后续工单

3. 回复工单

适用场景：用户想向工单添加评论或回复

工具调用顺序：

1. ZENDESK_GET_ZENDESK_TICKET_BY_ID - 获取当前工单状态 [前置条件]
2. ZENDESK_REPLY_ZENDESK_TICKET - 添加回复/评论 [必需]

关键参数：

• ticket_id：要回复的工单 ID
• body：回复文本内容
• public：布尔值；true 表示公开回复，false 表示内部备注
• author_id：作者的用户 ID（默认为已通过身份验证的用户）

注意事项：

• 将 public: false 设置为仅 Agent 可见的内部备注
• 默认情况下回复是公开的，并会向请求者发送电子邮件
• 正文支持 HTML
• 回复时也可以同时更新工单状态

4. 管理用户

适用场景：用户想要查找或创建 Zendesk 用户（客服人员、最终用户）

工具调用顺序：

1. ZENDESK_SEARCH_ZENDESK_USERS - 搜索用户［必需］
2. ZENDESK_CREATE_ZENDESK_USER - 创建新用户［可选］
3. ZENDESK_GET_ABOUT_ME - 获取已验证身份的用户信息［可选］

关键参数：

• query：搜索字符串（匹配姓名、电子邮件、电话等）
• name：用户全名（创建时必填）
• email：用户的电子邮件地址
• role：'end-user'、'agent' 或 'admin'
• verified：电子邮件是否已验证

注意事项：

• 用户搜索采用模糊匹配；可能会返回部分匹配结果
• 使用已存在的电子邮件创建用户时，会返回现有用户（更新或插入行为）
• Agent 和管理员角色可能需要特定套餐功能

5. 管理组织

适用场景：用户想要列出、创建或管理组织

工具调用顺序：

1. ZENDESK_GET_ALL_ZENDESK_ORGANIZATIONS - 列出所有组织［必需］
2. ZENDESK_GET_ZENDESK_ORGANIZATION - 获取指定组织［可选］
3. ZENDESK_CREATE_ZENDESK_ORGANIZATION - 创建组织［可选］
4. ZENDESK_UPDATE_ZENDESK_ORGANIZATION - 更新组织［可选］
5. ZENDESK_COUNT_ZENDESK_ORGANIZATIONS - 获取总数［可选］

关键参数：

• name：组织名称（唯一，创建时必填）
• organization_id：用于获取或更新的组织 ID
• details：组织详情文本
• notes：内部备注
• domain_names：关联域名数组
• tags：标签字符串数组

注意事项：

• 组织名称必须唯一；重复名称会导致创建错误
• UPDATE 时的标签会替换现有标签（与工单的行为相同）
• 域名可用于自动关联用户

常见模式

分页

列表接口：

• 使用 page（从 1 开始）和 per_page（最大值为 100）
• 检查响应中的 next_page URL；值为 null 表示最后一页
• count 字段提供结果总数

工单生命周期

new -> open -> pending -> solved -> closed
                  |          ^
                  v          |
                hold --------+

• new：未分配的工单
• open：已分配，正在处理中
• pending：等待客户回复
• hold：等待内部处理
• solved：已解决，可以重新打开
• closed：已永久关闭，无法修改

用于分配的用户搜索

1. Call ZENDESK_SEARCH_ZENDESK_USERS with query (name or email)
2. Extract user ID from results
3. Use user ID as assignee_id in ticket creation/update

已知注意事项

标签行为：

• 更新时的标签会替换所有现有标签
• 更新前始终先获取当前标签并合并
• 标签使用小写，不含空格（使用下划线）

安全更新：

• 使用 safe_update: true 和 updated_stamp（ISO 8601）以避免冲突
• 如果工单在该时间戳之后已被修改，则返回 409

删除：

• 删除工单是永久且不可逆的
• 考虑将状态设为 'closed'，而不是删除
• 已删除的工单无法通过 API 恢复

速率限制：

• 默认：每分钟 400 个请求
• 具体限制因套餐等级而异
• 429 响应包含 Retry-After 标头

快速参考

任务	工具标识	关键参数
列出工单	ZENDESK_LIST_ZENDESK_TICKETS	page, per_page, sort_by
获取工单	ZENDESK_GET_ZENDESK_TICKET_BY_ID	ticket_id
创建工单	ZENDESK_CREATE_ZENDESK_TICKET	subject, description, priority
更新工单	ZENDESK_UPDATE_ZENDESK_TICKET	ticket_id, status, tags
回复工单	ZENDESK_REPLY_ZENDESK_TICKET	ticket_id, body, public
删除工单	ZENDESK_DELETE_ZENDESK_TICKET	ticket_id
搜索用户	ZENDESK_SEARCH_ZENDESK_USERS	query
创建用户	ZENDESK_CREATE_ZENDESK_USER	name, email
我的个人资料	ZENDESK_GET_ABOUT_ME	(none)
列出组织	ZENDESK_GET_ALL_ZENDESK_ORGANIZATIONS	page, per_page
获取组织	ZENDESK_GET_ZENDESK_ORGANIZATION	organization_id
创建组织	ZENDESK_CREATE_ZENDESK_ORGANIZATION	name
更新组织	ZENDESK_UPDATE_ZENDESK_ORGANIZATION	organization_id, name
统计组织数量	ZENDESK_COUNT_ZENDESK_ORGANIZATIONS	(none)

---

由 Composio 提供支持