zendesk-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zendesk Automation via Rube MCP

通过Rube MCP实现Zendesk自动化

Automate Zendesk operations through Composio's Zendesk toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/zendesk

通过Composio的Zendesk工具包，借助Rube MCP实现Zendesk操作自动化。

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

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Zendesk connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
zendesk
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需具备RUBE_SEARCH_TOOLS功能）
通过
```
RUBE_MANAGE_CONNECTIONS
```
连接Zendesk，且工具包为
```
zendesk
```
，连接状态为活跃
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
zendesk
```
If connection is not ACTIVE, follow the returned auth link to complete Zendesk auth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
可正常响应，以此验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
，指定工具包为
```
zendesk
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Zendesk授权
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. List and Search Tickets

1. 列出与搜索工单

When to use: User wants to view, filter, or search support tickets

Tool sequence:

```
ZENDESK_LIST_ZENDESK_TICKETS
```
- List all tickets with pagination [Required]
```
ZENDESK_GET_ZENDESK_TICKET_BY_ID
```
- Get specific ticket details [Optional]

Key parameters:

```
page
```
: Page number (1-based)
```
per_page
```
: Results per page (max 100)
```
sort_by
```
: Sort field ('created_at', 'updated_at', 'priority', 'status')
```
sort_order
```
: 'asc' or 'desc'
```
ticket_id
```
: Ticket ID for single retrieval

Pitfalls:

LIST uses
```
page
```
/
```
per_page
```
pagination, NOT offset-based; check
```
next_page
```
in response
Maximum 100 results per page; iterate with page numbers until
```
next_page
```
is null
Deleted tickets are not returned by LIST; use GET_BY_ID which returns status 'deleted'
Ticket comments and audits are included in GET_BY_ID but not in LIST responses

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

工具执行顺序:

```
ZENDESK_LIST_ZENDESK_TICKETS
```
- 分页列出所有工单 [必填]
```
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
```
分页，而非基于偏移量的分页；请在响应中检查
```
next_page
```
字段
每页最多返回100条结果；需逐页迭代，直到
```
next_page
```
为null
LIST接口不会返回已删除的工单；使用GET_BY_ID接口可返回状态为'deleted'的工单
GET_BY_ID接口会包含工单的评论和审核记录，但LIST接口的响应中不包含这些内容

2. Create and Update Tickets

2. 创建与更新工单

When to use: User wants to create new tickets or modify existing ones

Tool sequence:

```
ZENDESK_SEARCH_ZENDESK_USERS
```
- Find requester/assignee [Prerequisite]
```
ZENDESK_CREATE_ZENDESK_TICKET
```
- Create a new ticket [Required]
```
ZENDESK_UPDATE_ZENDESK_TICKET
```
- Update ticket fields [Optional]
```
ZENDESK_DELETE_ZENDESK_TICKET
```
- Delete a ticket [Optional]

Key parameters:

```
subject
```
: Ticket subject line
```
description
```
: Ticket body (for creation; becomes first comment)
```
priority
```
: 'urgent', 'high', 'normal', 'low'
```
status
```
: 'new', 'open', 'pending', 'hold', 'solved', 'closed'
```
type
```
: 'problem', 'incident', 'question', 'task'
```
assignee_id
```
: Agent user ID to assign
```
requester_id
```
: Requester user ID
```
tags
```
: Array of tag strings
```
ticket_id
```
: Ticket ID (for update/delete)

Pitfalls:

Tags on UPDATE REPLACE existing tags entirely; merge with current tags to preserve them
Use
```
safe_update
```
with
```
updated_stamp
```
to prevent concurrent modification conflicts
DELETE is permanent and irreversible; tickets cannot be recovered
```
description
```
is only used on creation; use REPLY_ZENDESK_TICKET to add comments after creation
Closed tickets cannot be updated; create a follow-up ticket instead

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

工具执行顺序:

```
ZENDESK_SEARCH_ZENDESK_USERS
```
- 查找请求人/经办人 [前置步骤]
```
ZENDESK_CREATE_ZENDESK_TICKET
```
- 创建新工单 [必填]
```
ZENDESK_UPDATE_ZENDESK_TICKET
```
- 更新工单字段 [可选]
```
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（用于更新/删除操作）

注意事项:

更新工单时，标签会替换所有现有标签；若要保留原有标签，请先获取当前标签并合并后再更新
使用
```
safe_update
```
参数配合
```
updated_stamp
```
（ISO 8601格式）可防止并发修改冲突
删除操作是永久性且不可撤销的；工单删除后无法恢复
```
description
```
仅在创建工单时使用；创建后如需添加评论，请使用REPLY_ZENDESK_TICKET接口
已关闭的工单无法更新；如需修改，请创建跟进工单

3. Reply to Tickets

3. 回复工单

When to use: User wants to add comments or replies to tickets

Tool sequence:

```
ZENDESK_GET_ZENDESK_TICKET_BY_ID
```
- Get current ticket state [Prerequisite]
```
ZENDESK_REPLY_ZENDESK_TICKET
```
- Add a reply/comment [Required]

Key parameters:

```
ticket_id
```
: Ticket ID to reply to
```
body
```
: Reply text content
```
public
```
: Boolean; true for public reply, false for internal note
```
author_id
```
: Author user ID (defaults to authenticated user)

Pitfalls:

Set
```
public: false
```
for internal notes visible only to agents
Default is public reply which sends email to requester
HTML is supported in body text
Replying can also update ticket status simultaneously

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

工具执行顺序:

```
ZENDESK_GET_ZENDESK_TICKET_BY_ID
```
- 获取工单当前状态 [前置步骤]
```
ZENDESK_REPLY_ZENDESK_TICKET
```
- 添加回复/评论 [必填]

关键参数:

```
ticket_id
```
: 要回复的工单ID
```
body
```
: 回复文本内容
```
public
```
: 布尔值；true表示公开回复（会发送邮件给请求人），false表示内部备注
```
author_id
```
: 作者的用户ID（默认为已认证用户）

注意事项:

设置
```
public: false
```
可添加仅Agent可见的内部备注
默认是公开回复，会向请求人发送邮件
回复内容支持HTML格式
回复工单的同时也可更新工单状态

4. Manage Users

4. 用户管理

When to use: User wants to find or create Zendesk users (agents, end-users)

Tool sequence:

```
ZENDESK_SEARCH_ZENDESK_USERS
```
- Search for users [Required]
```
ZENDESK_CREATE_ZENDESK_USER
```
- Create a new user [Optional]
```
ZENDESK_GET_ABOUT_ME
```
- Get authenticated user info [Optional]

Key parameters:

```
query
```
: Search string (matches name, email, phone, etc.)
```
name
```
: User's full name (required for creation)
```
email
```
: User's email address
```
role
```
: 'end-user', 'agent', or 'admin'
```
verified
```
: Whether email is verified

Pitfalls:

User search is fuzzy; may return partial matches
Creating a user with an existing email returns the existing user (upsert behavior)
Agent and admin roles may require specific plan features

适用场景：用户想要查找或创建Zendesk用户（Agent、终端用户）

工具执行顺序:

```
ZENDESK_SEARCH_ZENDESK_USERS
```
- 搜索用户 [必填]
```
ZENDESK_CREATE_ZENDESK_USER
```
- 创建新用户 [可选]
```
ZENDESK_GET_ABOUT_ME
```
- 获取已认证用户的信息 [可选]

关键参数:

```
query
```
: 搜索字符串（匹配姓名、邮箱、电话等）
```
name
```
: 用户全名（创建用户时必填）
```
email
```
: 用户邮箱地址
```
role
```
: 用户角色（'end-user'、'agent'、'admin'）
```
verified
```
: 邮箱是否已验证

注意事项:

用户搜索为模糊搜索；可能返回部分匹配的结果
使用已存在的邮箱创建用户时，会返回已有的用户（即更新插入行为）
Agent和Admin角色可能需要特定的套餐功能支持

5. Manage Organizations

5. 组织管理

When to use: User wants to list, create, or manage organizations

Tool sequence:

```
ZENDESK_GET_ALL_ZENDESK_ORGANIZATIONS
```
- List all organizations [Required]
```
ZENDESK_GET_ZENDESK_ORGANIZATION
```
- Get specific organization [Optional]
```
ZENDESK_CREATE_ZENDESK_ORGANIZATION
```
- Create organization [Optional]
```
ZENDESK_UPDATE_ZENDESK_ORGANIZATION
```
- Update organization [Optional]
```
ZENDESK_COUNT_ZENDESK_ORGANIZATIONS
```
- Get total count [Optional]

Key parameters:

```
name
```
: Organization name (unique, required for creation)
```
organization_id
```
: Organization ID for get/update
```
details
```
: Organization details text
```
notes
```
: Internal notes
```
domain_names
```
: Array of associated domains
```
tags
```
: Array of tag strings

Pitfalls:

Organization names must be unique; duplicate names cause creation errors
Tags on UPDATE REPLACE existing tags (same behavior as tickets)
Domain names can be used for automatic user association

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

工具执行顺序:

```
ZENDESK_GET_ALL_ZENDESK_ORGANIZATIONS
```
- 列出所有组织 [必填]
```
ZENDESK_GET_ZENDESK_ORGANIZATION
```
- 获取特定组织的信息 [可选]
```
ZENDESK_CREATE_ZENDESK_ORGANIZATION
```
- 创建组织 [可选]
```
ZENDESK_UPDATE_ZENDESK_ORGANIZATION
```
- 更新组织信息 [可选]
```
ZENDESK_COUNT_ZENDESK_ORGANIZATIONS
```
- 获取组织总数 [可选]

关键参数:

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

注意事项:

组织名称必须唯一；重复的名称会导致创建失败
更新组织时，标签会替换所有现有标签（与工单的标签行为一致）
域名可用于自动关联用户

Common Patterns

常见模式

Pagination

分页

List endpoints:

Use
```
page
```
(1-based) and
```
per_page
```
(max 100)
Check
```
next_page
```
URL in response; null means last page
```
count
```
field gives total results

列表类端点:

使用
```
page
```
（从1开始）和
```
per_page
```
（最多100）参数
检查响应中的
```
next_page
```
URL；为null表示最后一页
```
count
```
字段给出总结果数

Ticket Lifecycle

工单生命周期

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

```
new
```
: Unassigned ticket
```
open
```
: Assigned, being worked on
```
pending
```
: Waiting for customer response
```
hold
```
: Waiting for internal action
```
solved
```
: Resolved, can be reopened
```
closed
```
: Permanently closed, cannot be modified

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

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

User Search for Assignment

用于分配的用户搜索

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

1. 调用ZENDESK_SEARCH_ZENDESK_USERS接口，传入查询参数（姓名或邮箱）
2. 从结果中提取用户ID
3. 在创建/更新工单时，将该用户ID作为assignee_id参数

Known Pitfalls

已知注意事项

Tags Behavior:

Tags on update REPLACE all existing tags
Always fetch current tags first and merge before updating
Tags are lowercase, no spaces (use underscores)

Safe Updates:

Use
```
safe_update: true
```
with
```
updated_stamp
```
(ISO 8601) to prevent conflicts
Returns 409 if ticket was modified since the stamp

Deletion:

Ticket deletion is permanent and irreversible
Consider setting status to 'closed' instead of deleting
Deleted tickets cannot be recovered via API

Rate Limits:

Default: 400 requests per minute
Varies by plan tier
429 responses include Retry-After header

标签行为:

更新时，标签会替换所有现有标签
请始终先获取当前标签，合并后再进行更新
标签为小写，无空格（使用下划线）

安全更新:

使用
```
safe_update: true
```
配合
```
updated_stamp
```
（ISO 8601格式）可防止冲突
如果工单自该时间戳后已被修改，会返回409错误

删除操作:

工单删除是永久性且不可撤销的
考虑将状态设置为'closed'而非删除
已删除的工单无法通过API恢复

速率限制:

默认限制：每分钟400次请求
限制因套餐层级而异
429响应会包含Retry-After头部

Quick Reference

快速参考

Task	Tool Slug	Key Params
List tickets	ZENDESK_LIST_ZENDESK_TICKETS	page, per_page, sort_by
Get ticket	ZENDESK_GET_ZENDESK_TICKET_BY_ID	ticket_id
Create ticket	ZENDESK_CREATE_ZENDESK_TICKET	subject, description, priority
Update ticket	ZENDESK_UPDATE_ZENDESK_TICKET	ticket_id, status, tags
Reply to ticket	ZENDESK_REPLY_ZENDESK_TICKET	ticket_id, body, public
Delete ticket	ZENDESK_DELETE_ZENDESK_TICKET	ticket_id
Search users	ZENDESK_SEARCH_ZENDESK_USERS	query
Create user	ZENDESK_CREATE_ZENDESK_USER	name, email
My profile	ZENDESK_GET_ABOUT_ME	(none)
List orgs	ZENDESK_GET_ALL_ZENDESK_ORGANIZATIONS	page, per_page
Get org	ZENDESK_GET_ZENDESK_ORGANIZATION	organization_id
Create org	ZENDESK_CREATE_ZENDESK_ORGANIZATION	name
Update org	ZENDESK_UPDATE_ZENDESK_ORGANIZATION	organization_id, name
Count orgs	ZENDESK_COUNT_ZENDESK_ORGANIZATIONS	(none)

Powered by Composio

任务	工具标识	关键参数
列出工单	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	(无)
列出组织	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	(无)

由 Composio 提供支持