freshdesk-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFreshdesk Automation via Rube MCP
通过Rube MCP实现Freshdesk自动化
Automate Freshdesk customer support workflows including ticket management, contact and company operations, notes, replies, and ticket search through Composio's Freshdesk toolkit.
借助Composio的Freshdesk工具包,自动化Freshdesk客户支持工作流,包括工单管理、联系人与公司操作、备注、回复及工单搜索。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Freshdesk connection via with toolkit
RUBE_MANAGE_CONNECTIONSfreshdesk - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 已连接Rube MCP(可使用RUBE_SEARCH_TOOLS)
- 通过使用
RUBE_MANAGE_CONNECTIONS工具包建立有效的Freshdesk连接freshdesk - 请始终先调用以获取最新的工具架构
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONSfreshdesk - If connection is not ACTIVE, follow the returned auth link to complete Freshdesk authentication
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥,只需添加该端点即可使用。
https://rube.app/mcp- 确认可正常响应,以此验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包为
RUBE_MANAGE_CONNECTIONSfreshdesk - 如果连接状态未显示为ACTIVE,请按照返回的认证链接完成Freshdesk认证
- 在运行任何工作流之前,确认连接状态为ACTIVE
Core Workflows
核心工作流
1. Create and Manage Tickets
1. 创建与管理工单
When to use: User wants to create a new support ticket, update an existing ticket, or view ticket details.
Tool sequence:
- - Find requester by email to get requester_id [Optional]
FRESHDESK_SEARCH_CONTACTS - - Check available custom fields and statuses [Optional]
FRESHDESK_LIST_TICKET_FIELDS - - Create a new ticket with subject, description, requester info [Required]
FRESHDESK_CREATE_TICKET - - Modify ticket status, priority, assignee, or other fields [Optional]
FRESHDESK_UPDATE_TICKET - - Retrieve full ticket details by ID [Optional]
FRESHDESK_VIEW_TICKET
Key parameters for FRESHDESK_CREATE_TICKET:
- : Ticket subject (required)
subject - : HTML content of the ticket (required)
description - : Requester email (at least one requester identifier required)
email - : User ID of requester (alternative to email)
requester_id - : 2=Open, 3=Pending, 4=Resolved, 5=Closed (default 2)
status - : 1=Low, 2=Medium, 3=High, 4=Urgent (default 1)
priority - : 1=Email, 2=Portal, 3=Phone, 7=Chat (default 2)
source - : Agent ID to assign the ticket to
responder_id - : Group to assign the ticket to
group_id - : Array of tag strings
tags - : Object with
custom_fieldskeyscf_<field_name>
Pitfalls:
- At least one requester identifier is required: ,
requester_id,email,phone,facebook_id, ortwitter_idunique_external_id - If is provided without
phone, thenemailbecomes mandatoryname - supports HTML formatting
description - field expects multipart/form-data format, not file paths or URLs
attachments - Custom field keys must be prefixed with (e.g.,
cf_)cf_reference_number - Status and priority are integers, not strings
适用场景:用户需要创建新的支持工单、更新现有工单或查看工单详情。
工具序列:
- - 通过邮箱查找请求者以获取requester_id [可选]
FRESHDESK_SEARCH_CONTACTS - - 查看可用的自定义字段和状态选项 [可选]
FRESHDESK_LIST_TICKET_FIELDS - - 使用主题、描述、请求者信息创建新工单 [必填]
FRESHDESK_CREATE_TICKET - - 修改工单状态、优先级、经办人或其他字段 [可选]
FRESHDESK_UPDATE_TICKET - - 通过ID获取完整的工单详情 [可选]
FRESHDESK_VIEW_TICKET
FRESHDESK_CREATE_TICKET关键参数:
- : 工单主题(必填)
subject - : 工单的HTML格式内容(必填)
description - : 请求者邮箱(至少需提供一个请求者标识)
email - : 请求者的用户ID(替代邮箱的选项)
requester_id - : 状态值(2=已打开,3=待处理,4=已解决,5=已关闭,默认值为2)
status - : 优先级(1=低,2=中,3=高,4=紧急,默认值为1)
priority - : 来源(1=邮件,2=门户,3=电话,7=聊天,默认值为2)
source - : 负责工单的Agent ID
responder_id - : 工单分配到的组ID
group_id - : 标签字符串数组
tags - : 以
custom_fields为键的对象cf_<字段名>
常见陷阱:
- 必须提供至少一个请求者标识:、
requester_id、email、phone、facebook_id或twitter_idunique_external_id - 如果仅提供而未提供
phone,则email为必填项name - 支持HTML格式
description - 字段要求multipart/form-data格式,不支持文件路径或URL
attachments - 自定义字段键必须以为前缀(例如
cf_)cf_reference_number - 状态和优先级为整数值,而非字符串
2. Search and Filter Tickets
2. 搜索与筛选工单
When to use: User wants to find tickets by status, priority, date range, agent, or custom fields.
Tool sequence:
- - List tickets with simple filters (status, priority, agent) [Required]
FRESHDESK_GET_TICKETS - - Advanced ticket search with query syntax [Required]
FRESHDESK_GET_SEARCH - - Get full details for specific tickets from results [Optional]
FRESHDESK_VIEW_TICKET - - Check available fields for search queries [Optional]
FRESHDESK_LIST_TICKET_FIELDS
Key parameters for FRESHDESK_GET_TICKETS:
- : Filter by status integer (2=Open, 3=Pending, 4=Resolved, 5=Closed)
status - : Filter by priority integer (1-4)
priority - : Filter by assigned agent
agent_id - : Filter by requester
requester_id - : Filter by requester email
email - : ISO 8601 timestamp
created_since - /
page: Pagination (default 30 per page)per_page - /
sort_by: Sort field and directionsort_order
Key parameters for FRESHDESK_GET_SEARCH:
- : Query string like
queryor"status:2 AND priority:3""(created_at:>'2024-01-01' AND tag:'urgent')" - : Page number (1-10, max 300 total results)
page
Pitfalls:
- query must be enclosed in double quotes
FRESHDESK_GET_SEARCH - Query string limited to 512 characters
- Maximum 10 pages (300 results) from search endpoints
- Date fields in queries use UTC format YYYY-MM-DD
- Use keyword to find tickets with empty fields (e.g.,
null)"agent_id:null" - takes no parameters and returns all tickets (use GET_TICKETS for filtering)
FRESHDESK_LIST_ALL_TICKETS
适用场景:用户需要按状态、优先级、日期范围、Agent或自定义字段查找工单。
工具序列:
- - 使用简单筛选条件(状态、优先级、Agent)列出工单 [必填]
FRESHDESK_GET_TICKETS - - 使用查询语法进行高级工单搜索 [必填]
FRESHDESK_GET_SEARCH - - 从搜索结果中获取特定工单的完整详情 [可选]
FRESHDESK_VIEW_TICKET - - 查看可用于搜索查询的字段 [可选]
FRESHDESK_LIST_TICKET_FIELDS
FRESHDESK_GET_TICKETS关键参数:
- : 按状态整数值筛选(2=已打开,3=待处理,4=已解决,5=已关闭)
status - : 按优先级整数值筛选(1-4)
priority - : 按分配的Agent筛选
agent_id - : 按请求者筛选
requester_id - : 按请求者邮箱筛选
email - : ISO 8601时间戳
created_since - /
page: 分页参数(默认每页30条)per_page - /
sort_by: 排序字段和方向sort_order
FRESHDESK_GET_SEARCH关键参数:
- : 查询字符串,例如
query或"status:2 AND priority:3""(created_at:>'2024-01-01' AND tag:'urgent')" - : 页码(1-10,最多返回300条结果)
page
常见陷阱:
- 的查询必须用双引号包裹
FRESHDESK_GET_SEARCH - 查询字符串长度限制为512字符
- 搜索端点最多返回10页(300条结果)
- 查询中的日期字段需使用UTC格式YYYY-MM-DD
- 使用关键字查找字段为空的工单(例如
null)"agent_id:null" - 无参数,返回所有工单(如需筛选请使用GET_TICKETS)
FRESHDESK_LIST_ALL_TICKETS
3. Reply to and Add Notes on Tickets
3. 回复工单与添加备注
When to use: User wants to send a reply to a customer, add internal notes, or view conversation history.
Tool sequence:
- - Verify ticket exists and check current state [Prerequisite]
FRESHDESK_VIEW_TICKET - - Send a public reply to the requester [Required]
FRESHDESK_REPLY_TO_TICKET - - Add a private or public note [Required]
FRESHDESK_ADD_NOTE_TO_TICKET - - View all messages and notes on a ticket [Optional]
FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS - - Edit an existing note [Optional]
FRESHDESK_UPDATE_CONVERSATIONS
Key parameters for FRESHDESK_REPLY_TO_TICKET:
- : Ticket ID (integer, required)
ticket_id - : Reply content, supports HTML (required)
body - /
cc_emails: Additional recipients (max 50 total across to/cc/bcc)bcc_emails - : Override sender email if multiple support emails configured
from_email - : Agent ID to reply on behalf of
user_id
Key parameters for FRESHDESK_ADD_NOTE_TO_TICKET:
- : Ticket ID (integer, required)
ticket_id - : Note content, supports HTML (required)
body - : true for agent-only visibility, false for public (default true)
private - : Only accepts agent email addresses, not external contacts
notify_emails
Pitfalls:
- There are two reply tools: (more features) and
FRESHDESK_REPLY_TO_TICKET(simpler); both workFRESHDESK_REPLY_TICKET - defaults to private (agent-only); set
FRESHDESK_ADD_NOTE_TO_TICKETfor public notesprivate: false - in notes only accepts agent emails, not customer emails
notify_emails - Only notes can be edited via ; incoming replies cannot be edited
FRESHDESK_UPDATE_CONVERSATIONS
适用场景:用户需要向客户发送回复、添加内部备注或查看对话历史。
工具序列:
- - 验证工单存在并查看当前状态 [前置条件]
FRESHDESK_VIEW_TICKET - - 向请求者发送公开回复 [必填]
FRESHDESK_REPLY_TO_TICKET - - 添加私有或公开备注 [必填]
FRESHDESK_ADD_NOTE_TO_TICKET - - 查看工单的所有消息和备注 [可选]
FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS - - 编辑现有备注 [可选]
FRESHDESK_UPDATE_CONVERSATIONS
FRESHDESK_REPLY_TO_TICKET关键参数:
- : 工单ID(整数,必填)
ticket_id - : 回复内容,支持HTML(必填)
body - /
cc_emails: 额外收件人(to/cc/bcc总计最多50个)bcc_emails - : 若配置了多个支持邮箱,可覆盖发件人邮箱
from_email - : 代表该Agent发送回复的ID
user_id
FRESHDESK_ADD_NOTE_TO_TICKET关键参数:
- : 工单ID(整数,必填)
ticket_id - : 备注内容,支持HTML(必填)
body - : true表示仅Agent可见,false表示公开(默认值为true)
private - : 仅接受Agent邮箱地址,不支持外部联系人
notify_emails
常见陷阱:
- 有两个回复工具:(功能更丰富)和
FRESHDESK_REPLY_TO_TICKET(更简洁),两者均可使用FRESHDESK_REPLY_TICKET - 默认是私有(仅Agent可见);若需公开备注请设置
FRESHDESK_ADD_NOTE_TO_TICKETprivate: false - 备注中的仅接受Agent邮箱,不支持客户邮箱
notify_emails - 仅可通过编辑备注;无法编辑 incoming replies(客户发来的回复)
FRESHDESK_UPDATE_CONVERSATIONS
4. Manage Contacts and Companies
4. 管理联系人和公司
When to use: User wants to create, search, or manage customer contacts and company records.
Tool sequence:
- - Search contacts by email, phone, or company [Required]
FRESHDESK_SEARCH_CONTACTS - - List contacts with filters [Optional]
FRESHDESK_GET_CONTACTS - - Bulk import contacts from CSV [Optional]
FRESHDESK_IMPORT_CONTACT - - Search companies by custom fields [Required]
FRESHDESK_SEARCH_COMPANIES - - List all companies [Optional]
FRESHDESK_GET_COMPANIES - - Create a new company [Optional]
FRESHDESK_CREATE_COMPANIES - - Update company details [Optional]
FRESHDESK_UPDATE_COMPANIES - - Check available company fields [Optional]
FRESHDESK_LIST_COMPANY_FIELDS
Key parameters for FRESHDESK_SEARCH_CONTACTS:
- : Search string like
query(required)"email:'user@example.com'" - : Pagination (1-10, max 30 per page)
page
Key parameters for FRESHDESK_CREATE_COMPANIES:
- : Company name (required)
name - : Array of domain strings for auto-association with contacts
domains - : "Happy", "Doing okay", or "At risk"
health_score - : "Basic", "Premium", or "Enterprise"
account_tier - : Standard industry classification
industry
Pitfalls:
- requires exact matches; partial/regex searches are not supported
FRESHDESK_SEARCH_CONTACTS - cannot search by standard
FRESHDESK_SEARCH_COMPANIESfield; use custom fields ornamecreated_at - Company custom fields do NOT use the prefix (unlike ticket custom fields)
cf_ - on companies enables automatic contact-to-company association by email domain
domains - Contact search queries require string values in single quotes inside double-quoted query
适用场景:用户需要创建、搜索或管理客户联系人和公司记录。
工具序列:
- - 按邮箱、电话或公司搜索联系人 [必填]
FRESHDESK_SEARCH_CONTACTS - - 带筛选条件列出联系人 [可选]
FRESHDESK_GET_CONTACTS - - 从CSV批量导入联系人 [可选]
FRESHDESK_IMPORT_CONTACT - - 按自定义字段搜索公司 [必填]
FRESHDESK_SEARCH_COMPANIES - - 列出所有公司 [可选]
FRESHDESK_GET_COMPANIES - - 创建新公司 [可选]
FRESHDESK_CREATE_COMPANIES - - 更新公司详情 [可选]
FRESHDESK_UPDATE_COMPANIES - - 查看可用的公司字段 [可选]
FRESHDESK_LIST_COMPANY_FIELDS
FRESHDESK_SEARCH_CONTACTS关键参数:
- : 搜索字符串,例如
query(必填)"email:'user@example.com'" - : 分页参数(1-10,每页最多30条)
page
FRESHDESK_CREATE_COMPANIES关键参数:
- : 公司名称(必填)
name - : 域名字符串数组,用于自动关联联系人
domains - : 健康评分("Happy"、"Doing okay"或"At risk")
health_score - : 账户等级("Basic"、"Premium"或"Enterprise")
account_tier - : 标准行业分类
industry
常见陷阱:
- 要求精确匹配;不支持部分匹配/正则搜索
FRESHDESK_SEARCH_CONTACTS - 无法按标准
FRESHDESK_SEARCH_COMPANIES字段搜索;请使用自定义字段或namecreated_at - 公司自定义字段不使用前缀(与工单自定义字段不同)
cf_ - 公司的字段可根据邮箱域名自动关联联系人和公司
domains - 联系人搜索查询要求字符串值用单引号包裹,且整个查询用双引号包裹
Common Patterns
常见模式
ID Resolution
ID解析
Always resolve display values to IDs before operations:
- Requester email -> requester_id: with
FRESHDESK_SEARCH_CONTACTS"email:'user@example.com'" - Company name -> company_id: and match by name (search by name not supported)
FRESHDESK_GET_COMPANIES - Agent name -> agent_id: Not directly available; use agent_id from ticket responses or admin configuration
在执行操作前,请始终将显示值解析为ID:
- 请求者邮箱 -> requester_id:使用并传入
FRESHDESK_SEARCH_CONTACTS"email:'user@example.com'" - 公司名称 -> company_id:使用并按名称匹配(不支持按名称搜索)
FRESHDESK_GET_COMPANIES - Agent名称 -> agent_id:无法直接获取;可从工单响应或管理员配置中获取agent_id
Pagination
分页
Freshdesk uses page-based pagination:
- :
FRESHDESK_GET_TICKETS(starting at 1) andpage(max 100)per_page - :
FRESHDESK_GET_SEARCH(1-10, 30 results per page, max 300 total)page - :
FRESHDESK_SEARCH_CONTACTS(1-10, 30 per page)page - :
FRESHDESK_LIST_ALL_TICKET_CONVERSATIONSandpage(max 100)per_page
Freshdesk使用基于页码的分页:
- :
FRESHDESK_GET_TICKETS(从1开始)和page(最多100条)per_page - :
FRESHDESK_GET_SEARCH(1-10,每页30条,最多300条结果)page - :
FRESHDESK_SEARCH_CONTACTS(1-10,每页30条)page - :
FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS和page(最多100条)per_page
Known Pitfalls
已知陷阱
ID Formats
ID格式
- Ticket IDs, contact IDs, company IDs, agent IDs, and group IDs are all integers
- There are no string-based IDs in Freshdesk
- 工单ID、联系人ID、公司ID、Agent ID和组ID均为整数
- Freshdesk中无基于字符串的ID
Rate Limits
速率限制
- Freshdesk enforces per-account API rate limits based on plan tier
- Bulk operations should be paced to avoid 429 responses
- Search endpoints are limited to 300 total results (10 pages of 30)
- Freshdesk根据套餐等级对每个账户设置API速率限制
- 批量操作需控制频率,避免收到429响应
- 搜索端点最多返回300条结果(10页,每页30条)
Parameter Quirks
参数特性
- Status values: 2=Open, 3=Pending, 4=Resolved, 5=Closed (integers, not strings)
- Priority values: 1=Low, 2=Medium, 3=High, 4=Urgent (integers, not strings)
- Source values: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email
- Ticket custom fields use prefix; company custom fields do NOT
cf_ - in tickets supports HTML formatting
description - Search query strings must be in double quotes with string values in single quotes
- returns all tickets with no filter parameters
FRESHDESK_LIST_ALL_TICKETS
- 状态值:2=已打开,3=待处理,4=已解决,5=已关闭(整数,非字符串)
- 优先级值:1=低,2=中,3=高,4=紧急(整数,非字符串)
- 来源值:1=邮件,2=门户,3=电话,7=聊天,9=反馈组件,10=外发邮件
- 工单自定义字段使用前缀;公司自定义字段不使用
cf_ - 工单的支持HTML格式
description - 搜索查询字符串必须用双引号包裹,其中的字符串值用单引号包裹
- 无参数,返回所有工单
FRESHDESK_LIST_ALL_TICKETS
Response Structure
响应结构
- Ticket details include nested objects for requester, assignee, and conversation data
- Search results are paginated with a maximum of 300 results across 10 pages
- Conversation lists include both replies and notes in chronological order
- 工单详情包含请求者、经办人及对话数据的嵌套对象
- 搜索结果为分页格式,最多返回10页共300条结果
- 对话列表按时间顺序包含回复和备注
Quick Reference
速查表
| Task | Tool Slug | Key Params |
|---|---|---|
| Create ticket | | |
| Update ticket | | |
| View ticket | | |
| List tickets | | |
| List all tickets | | (none) |
| Search tickets | | |
| Reply to ticket | | |
| Reply (simple) | | |
| Add note | | |
| List conversations | | |
| Update note | | |
| Search contacts | | |
| List contacts | | |
| Import contacts | | |
| Create company | | |
| Update company | | |
| Search companies | | |
| List companies | | |
| List ticket fields | | (none) |
| List company fields | | (none) |
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 创建工单 | | |
| 更新工单 | | |
| 查看工单 | | |
| 列出工单 | | |
| 列出所有工单 | | (无) |
| 搜索工单 | | |
| 回复工单 | | |
| 简单回复 | | |
| 添加备注 | | |
| 列出对话 | | |
| 更新备注 | | |
| 搜索联系人 | | |
| 列出联系人 | | |
| 导入联系人 | | |
| 创建公司 | | |
| 更新公司 | | |
| 搜索公司 | | |
| 列出公司 | | |
| 列出工单字段 | | (无) |
| 列出公司字段 | | (无) |