freshdesk-automation

通过 Rube MCP 自动化 Freshdesk

通过 Composio 的 Freshdesk 工具包，自动化 Freshdesk 客户支持工作流，包括工单管理、联系人和公司操作、备注、回复以及工单搜索。

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

前提条件

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

设置

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

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 已可用
2. 调用 RUBE_MANAGE_CONNECTIONS，工具包设为 freshdesk
3. 如果连接状态不是 ACTIVE，请按照返回的身份验证链接完成 Freshdesk 身份验证
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 创建和管理工单

适用场景：用户想要创建新的支持工单、更新现有工单或查看工单详情。

工具调用顺序：

1. FRESHDESK_SEARCH_CONTACTS - 通过电子邮件查找请求者，以获取 requester_id [可选]
2. FRESHDESK_LIST_TICKET_FIELDS - 查看可用的自定义字段和状态 [可选]
3. FRESHDESK_CREATE_TICKET - 使用主题、描述和请求者信息创建新工单 [必需]
4. FRESHDESK_UPDATE_TICKET - 修改工单状态、优先级、受理人或其他字段 [可选]
5. FRESHDESK_VIEW_TICKET - 按 ID 获取完整工单详情 [可选]

FRESHDESK_CREATE_TICKET 的关键参数：

• subject：工单主题（必需）
• description：工单的 HTML 内容（必需）
• email：请求者电子邮件（至少需要一个请求者标识符）
• requester_id：请求者的用户 ID（可替代电子邮件）
• status：2=待处理，3=等待中，4=已解决，5=已关闭（默认值为 2）
• priority：1=低，2=中，3=高，4=紧急（默认值为 1）
• source：1=电子邮件，2=门户，3=电话，7=聊天（默认值为 2）
• responder_id：要分配工单的 Agent ID
• group_id：要分配工单的组
• tags：标签字符串数组
• custom_fields：包含 cf_<field_name> 键的对象

注意事项：

• 至少需要一个请求者标识符：requester_id、email、phone、facebook_id、twitter_id 或 unique_external_id
• 如果提供了 phone 但未提供 email，则必须提供 name
• description 支持 HTML 格式
• attachments 字段要求使用 multipart/form-data 格式，不能使用文件路径或 URL
• 自定义字段键必须以 cf_ 为前缀（例如 cf_reference_number）
• 状态和优先级必须是整数，不能是字符串

2. 搜索和筛选工单

适用场景：用户想按状态、优先级、日期范围、Agent 或自定义字段查找工单。

工具调用顺序：

1. FRESHDESK_GET_TICKETS - 使用简单筛选条件（状态、优先级、Agent）列出工单［必需］
2. FRESHDESK_GET_SEARCH - 使用查询语法进行高级工单搜索［必需］
3. FRESHDESK_VIEW_TICKET - 获取搜索结果中指定工单的完整详情［可选］
4. FRESHDESK_LIST_TICKET_FIELDS - 查看查询中可用的字段［可选］

FRESHDESK_GET_TICKETS 的关键参数：

• status：按状态整数筛选（2=Open，3=Pending，4=Resolved，5=Closed）
• priority：按优先级整数筛选（1-4）
• agent_id：按已分配的 Agent 筛选
• requester_id：按请求者筛选
• email：按请求者邮箱筛选
• created_since：ISO 8601 时间戳
• page / per_page：分页（默认每页 30 条）
• sort_by / sort_order：排序字段和顺序

FRESHDESK_GET_SEARCH 的关键参数：

• query：查询字符串，例如 "status:2 AND priority:3" 或 "(created_at:>'2024-01-01' AND tag:'urgent')"
• page：页码（1-10，最多 300 条结果）

注意事项：

• FRESHDESK_GET_SEARCH 查询必须用双引号括起来
• 查询字符串最多 512 个字符
• 搜索接口最多返回 10 页（300 条结果）
• 查询中的日期字段使用 UTC 格式 YYYY-MM-DD
• 使用 null 关键字查找字段为空的工单（例如，"agent_id:null"）
• FRESHDESK_LIST_ALL_TICKETS 不接受任何参数，会返回所有工单（筛选时请使用 GET_TICKETS）

3. 回复工单并添加备注

适用场景：用户想回复客户、添加内部备注或查看对话历史记录。

工具调用顺序：

1. FRESHDESK_VIEW_TICKET - 确认工单存在并检查当前状态［前置条件］
2. FRESHDESK_REPLY_TO_TICKET - 向请求者发送公开回复［必需］
3. FRESHDESK_ADD_NOTE_TO_TICKET - 添加私密或公开备注［必需］
4. FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS - 查看工单上的所有消息和备注［可选］
5. FRESHDESK_UPDATE_CONVERSATIONS - 编辑现有备注［可选］

FRESHDESK_REPLY_TO_TICKET 的关键参数：

• ticket_id：工单 ID（整数，必需）
• body：回复内容，支持 HTML（必需）
• cc_emails / bcc_emails：其他收件人（to/cc/bcc 总计最多 50 人）
• from_email：配置了多个支持邮箱时，用于覆盖发件人邮箱
• user_id：代表其进行回复的 Agent ID

FRESHDESK_ADD_NOTE_TO_TICKET 的关键参数：

• ticket_id：工单 ID（整数，必需）
• body：备注内容，支持 HTML（必需）
• private：true 表示仅 Agent 可见，false 表示公开（默认值为 true）
• notify_emails：仅接受 Agent 邮箱地址，不接受外部联系人邮箱

注意事项：

• 有两个回复工具：FRESHDESK_REPLY_TO_TICKET（功能更多）和 FRESHDESK_REPLY_TICKET（更简单）；两者都可用
• FRESHDESK_ADD_NOTE_TO_TICKET 默认添加私密备注（仅 Agent 可见）；将 private: false 设为公开备注
• 备注中的 notify_emails 仅接受 Agent 邮箱，不接受客户邮箱
• 只能通过 FRESHDESK_UPDATE_CONVERSATIONS 编辑备注；无法编辑收到的回复

4. 管理联系人和公司

使用场景：用户想要创建、搜索或管理客户联系人和公司记录。

工具调用顺序：

1. FRESHDESK_SEARCH_CONTACTS - 按电子邮件、电话或公司搜索联系人 [必需]
2. FRESHDESK_GET_CONTACTS - 使用筛选条件列出联系人 [可选]
3. FRESHDESK_IMPORT_CONTACT - 从 CSV 批量导入联系人 [可选]
4. FRESHDESK_SEARCH_COMPANIES - 按自定义字段搜索公司 [必需]
5. FRESHDESK_GET_COMPANIES - 列出所有公司 [可选]
6. FRESHDESK_CREATE_COMPANIES - 创建新公司 [可选]
7. FRESHDESK_UPDATE_COMPANIES - 更新公司详情 [可选]
8. FRESHDESK_LIST_COMPANY_FIELDS - 查看可用的公司字段 [可选]

FRESHDESK_SEARCH_CONTACTS 的关键参数：

• query：搜索字符串，例如 "email:'[email protected]'"（必需）
• page：分页（1-10，每页最多 30 条）

FRESHDESK_CREATE_COMPANIES 的关键参数：

• name：公司名称（必需）
• domains：域名字符串数组，用于自动关联联系人
• health_score："Happy"、"Doing okay" 或 "At risk"
• account_tier："Basic"、"Premium" 或 "Enterprise"
• industry：标准行业分类

注意事项：

• FRESHDESK_SEARCH_CONTACTS 需要精确匹配；不支持部分匹配或正则表达式搜索
• FRESHDESK_SEARCH_COMPANIES 无法按标准的 name 字段搜索；请使用自定义字段或 created_at
• 公司自定义字段不使用 cf_ 前缀（与工单自定义字段不同）
• 公司上的 domains 可根据电子邮件域名自动将联系人关联到公司
• 联系人搜索查询要求在双引号括起的查询中，将字符串值放在单引号内

常见模式

ID 解析

执行操作前，始终先将显示值解析为 ID：

• 请求者电子邮件 -> requester_id：使用 "email:'[email protected]'" 调用 FRESHDESK_SEARCH_CONTACTS
• 公司名称 -> company_id：调用 FRESHDESK_GET_COMPANIES 并按名称匹配（不支持按名称搜索）
• Agent 名称 -> agent_id：无法直接获取；请使用工单响应或管理员配置中的 agent_id

分页

Freshdesk 使用基于页码的分页：

• FRESHDESK_GET_TICKETS：page（从 1 开始）和 per_page（最多 100）
• FRESHDESK_GET_SEARCH：page（1-10，每页 30 条，最多 300 条）
• FRESHDESK_SEARCH_CONTACTS：page（1-10，每页 30 条）
• FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS：page 和 per_page（最多 100）

已知注意事项

ID 格式

• 工单 ID、联系人 ID、公司 ID、Agent ID 和群组 ID 都是整数
• Freshdesk 中没有基于字符串的 ID

速率限制

• Freshdesk 根据套餐等级对每个账户实施 API 速率限制
• 批量操作应控制调用频率，以避免收到 429 响应
• 搜索端点最多返回 300 条结果（10 页，每页 30 条）

参数注意事项

• 状态值：2=Open、3=Pending、4=Resolved、5=Closed（整数，而非字符串）
• 优先级值：1=Low、2=Medium、3=High、4=Urgent（整数，而非字符串）
• 来源值：1=Email、2=Portal、3=Phone、7=Chat、9=Feedback Widget、10=Outbound Email
• 工单自定义字段使用 cf_ 前缀；公司自定义字段不使用
• 工单中的 description 支持 HTML 格式
• 搜索查询字符串必须用双引号括起，字符串值必须用单引号括起
• FRESHDESK_LIST_ALL_TICKETS 会返回所有工单，不接受筛选参数

响应结构

• 工单详情包含请求者、受理人和对话数据等嵌套对象
• 搜索结果采用分页形式，10 页总计最多 300 条
• 对话列表按时间顺序包含回复和备注

Quick Reference

Task	Tool Slug	Key Params
Create ticket	FRESHDESK_CREATE_TICKET	subject, description, email, priority
Update ticket	FRESHDESK_UPDATE_TICKET	ticket_id, status, priority
View ticket	FRESHDESK_VIEW_TICKET	ticket_id
List tickets	FRESHDESK_GET_TICKETS	status, priority, page, per_page
List all tickets	FRESHDESK_LIST_ALL_TICKETS	(none)
Search tickets	FRESHDESK_GET_SEARCH	query, page
Reply to ticket	FRESHDESK_REPLY_TO_TICKET	ticket_id, body, cc_emails
Reply (simple)	FRESHDESK_REPLY_TICKET	ticket_id, body
Add note	FRESHDESK_ADD_NOTE_TO_TICKET	ticket_id, body, private
List conversations	FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS	ticket_id, page
Update note	FRESHDESK_UPDATE_CONVERSATIONS	conversation_id, body
Search contacts	FRESHDESK_SEARCH_CONTACTS	query, page
List contacts	FRESHDESK_GET_CONTACTS	email, company_id, page
Import contacts	FRESHDESK_IMPORT_CONTACT	file, name_column_index, email_column_index
Create company	FRESHDESK_CREATE_COMPANIES	name, domains, industry
Update company	FRESHDESK_UPDATE_COMPANIES	company_id, name, domains
Search companies	FRESHDESK_SEARCH_COMPANIES	query, page
List companies	FRESHDESK_GET_COMPANIES	page
List ticket fields	FRESHDESK_LIST_TICKET_FIELDS	(none)
List company fields	FRESHDESK_LIST_COMPANY_FIELDS	(none)

---

Powered by Composio