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.

通过Composio的Zendesk工具包，借助Rube MCP自动化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
```
：经办人用户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
```
默认是公开回复，会向请求人发送邮件
正文中支持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用户（客服、终端用户）

工具执行顺序：

```
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)

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