AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载Botpress Freshdesk 集成hub.md当前版本 0.1.1允许你将 Botpress 机器人接入 Freshdesk 支持工单系统通过 9 个内置动作创建、查询、更新、删除和搜索工单与联系人并通过 Freshdesk 的 Automation Rules 触发 Webhook让机器人实时响应工单的创建、更新与回复事件。读完本文你将掌握该集成的配置方式、状态与优先级的字符串枚举映射规则、三个生命周期事件对应的 Webhook 路径与请求体模板以及每个动作的完整输入输出参数可直接在 Botpress Studio 或聊天机器人流程中落地工单自动化场景。集成概览与安装配置Freshdesk 集成位于仓库的 integrations/freshdesk 目录其定义见 integration.definition.tsname为freshdesk包名为botpresshub/freshdesk见 package.json归类于 Customer Support 类别。集成声明了一个用户标签freshdeskRequesterId用于将 Freshdesk 工单请求者与 Botpress 用户绑定integration.definition.ts。安装并配置该集成时需要填写三个配置项其定义见 definitions/configuration.ts配置项类型是否必填说明domainstring必填Freshdesk 子域名。例如yourcompany.freshdesk.com中的yourcompanyapiKeystringsecret必填Freshdesk API 密钥位于 Freshdesk 的 Profile Settings 中webhookSecretstringsecret可选用于校验传入 Webhook 的共享密钥。设置后需要在每个 Freshdesk Automation Webhook 动作中将其作为X-Webhook-Secret请求头发送安装时集成会立即校验凭据从源码看src/index.ts 的register阶段会调用FreshdeskClient.validateCredentials()其实现为请求GET /tickets?per_page1FreshdeskClient.ts。校验失败时集成会抛出Invalid Freshdesk configuration的运行时错误因此在安装面板中即可确认密钥是否正确。底层 API 客户端FreshdeskClient.ts将所有请求指向https://{domain}.freshdesk.com/api/v2采用 HTTP Basic Auth密码位固定为XFreshdesk API Key 的标准用法。遇到 429 限流时抛出的错误消息为Freshdesk rate limit reached其余非 2xx 响应则抛出带 Freshdesk 返回description与errors详情的运行时错误。工单属性字符串枚举与内部数值的映射Freshdesk 的status与priority在 Botpress 侧统一表示为字符串枚举集成负责将其转换为 Freshdesk API 使用的内部数值。该转换关系在 hub.md 中以表格形式给出同时也在 mappers.ts 和 const.ts 的源码中有完全一致的映射常量作为实现证据Status字符串值数值Openopen2Pendingpending3Resolvedresolved4Closedclosed5Priority字符串值数值Lowlow1Mediummedium2Highhigh3Urgenturgent4这条映射贯穿集成所有方向的数据流动作输出与事件负载Freshdesk API 返回的数值型status/priority会被NUM_TO_STATUS/NUM_TO_PRIORITY反向映射为字符串保证 Botpress 侧永远面向稳定的字符串枚举动作输入创建或更新工单时字符串枚举会通过STATUS_TO_NUM/PRIORITY_TO_NUM转为数值后调用 Freshdesk API见 createTicket.ts 与 updateTicket.ts。因此在 Botpress 流程中你永远不需要手写数值直接用open、urgent这类语义化字符串即可。事件体系与 Webhook 配置集成通过三个事件响应工单生命周期ticketCreated新工单创建、ticketUpdated工单状态、优先级或指派变化、ticketReplied客户新增回复。事件的完整负载结构定义在 definitions/events.tsticketCreated与ticketUpdated携带ticket对象ticketReplied额外携带reply对象含 HTML 正文body、纯文本bodyText、客户邮箱customerEmail。重要前提这些事件不是集成自动订阅的而是由你在 Freshdesk 后台手动创建的 Automation Rules 触发的。每个事件对应一个独立的 Webhook 路径Freshdesk 的 Webhook 动作按路径将请求投递到集成。Webhook 配置步骤按官方文档进入 Freshdesk 控制台打开Admin → Automations为每个希望接收的事件分别创建一条规则在规则的Actions中添加Trigger Webhook动作将Request Type设为POSTencoding设为json使用以下 URL将{webhook-url}替换为 Botpress 中安装集成后显示的 Webhook URL事件Webhook URLticketCreated{webhook-url}/ticket-createdticketUpdated{webhook-url}/ticket-updatedticketReplied{webhook-url}/ticket-replied推荐安全加固如果集成的webhookSecret配置项已设置请在每条 Freshdesk Automation Webhook 动作中添加名为X-Webhook-Secret的自定义请求头值为同一密钥。集成会拒绝所有缺失或不匹配密钥的 Webhook详见下文“Webhook 安全校验”一节Webhook 请求体至少需要包含机器人所需的工单字段其中ticket.id为必填——缺失该字段的 Webhook 会被拒绝其余工单字段均为可选。ticketCreated / ticketUpdated 的请求体模板{ ticket: { id: {{ticket.id}}, subject: {{ticket.subject}}, status: {{ticket.status_id}}, priority: {{ticket.priority_id}}, requester_id: {{ticket.requester.id}}, responder_id: {{ticket.agent.id}}, group_id: {{ticket.group.id}}, type: {{ticket.ticket_type}} } }ticketReplied 的请求体模板ticketReplied除工单字段外还需包含回复字段其中reply.body为必填{ ticket: { id: {{ticket.id}}, status: {{ticket.status_id}}, requester_id: {{ticket.requester.id}} }, reply: { body: {{ticket.latest_public_comment_html}}, body_text: {{ticket.latest_public_comment}}, customer_email: {{ticket.contact.email}} } }Webhook 安全校验的源码实现在 handler.ts 中可以看到安全校验的实现细节当webhookSecret配置存在时集成从请求头读取x-webhook-secret并与配置中的密钥通过 Node.js 的timingSafeEqual进行恒定时间比较先比较字节长度再比较内容从而避免时序侧信道攻击。校验不通过或请求体为空/非法 JSON 时Webhook 会被静默忽略并记录告警日志不会触发任何事件。事件触发链路从 Webhook 到 Botpress 事件收到合法请求后handler 按路径分发handler.ts/ticket-created→executeTicketCreated/ticket-updated→executeTicketUpdated/ticket-replied→executeTicketReplied以 ticketCreated.ts 为例完整链路为用ticketCreatedBodySchema.safeParse校验请求体schemas.ts。值得注意Freshdesk 模板值全部以字符串形式发送因此 schema 中所有数值字段id、status、priority等都通过z.coerce.number()做了字符串到数值的强制转换检查requester_id是否存在缺失则跳过事件通过client.getOrCreateUser({ tags: { freshdeskRequesterId } })将 Freshdesk 请求者关联为 Botpress 用户这正是集成声明freshdeskRequesterId用户标签的用途调用createEvent触发ticketCreated事件负载由 mappers.ts 的mapTicket完成数值到字符串枚举的转换。动作Actions完整参考集成共提供 9 个动作输入输出 schema 均定义在 definitions/actions.ts底层实现位于 src/freshdesk-client/actions/implementations。以下按使用场景分组给出完整参数说明。工单操作createTicket创建工单必填参数subject标题、descriptionHTML 描述、email请求者邮箱。可选参数参数类型默认值说明priorityenummedium优先级low/medium/high/urgentstatusenumopen状态open/pending/resolved/closedtagsstring[]—关联工单标签custom_fieldsrecord—自定义字段键值对输出包含id、subject、status、priority、createdAtISO 8601、url形如https://{domain}.freshdesk.com/helpdesk/tickets/{id}见 createTicket.ts。getTicket按 ID 查询工单输入ticketId正整数输出工单详情包括descriptionHTML、requesterId、responderId、groupId、tags、customFields、createdAt、updatedAt等。listTickets列出工单参数类型说明filterstring预定义过滤器new_and_my_open、watching、spam、deletedorder_bystring排序字段created_at、due_by、updated_at、statusorder_typeenumasc/desc默认descper_pagenumber每页数量最大 100默认 30nextTokenstring上一页返回的分页令牌用于获取后续页输出为tickets数组与可选nextToken无更多结果时缺省。updateTicket更新工单输入ticketId与以下可选字段status、priority、responderId指派代理、groupId指派分组、custom_fields。从实现看updateTicket.tsresponderId与groupId只有大于 0 时才会被提交避免误清空指派。deleteTicket删除工单输入ticketId输出为空对象。删除的工单可在 Freshdesk UI 的回收站trash中查看并在 30 天内恢复。addNote添加工单备注参数类型默认值说明ticketIdnumber—目标工单 IDbodystring—备注的 HTML 内容privatebooleantrue设为false时备注对请求者可见searchTickets搜索工单参数类型默认值说明agent_idnumber—按指派代理过滤tagstring—按标签过滤statusenum—按状态过滤priorityenum—按优先级过滤limitnumber20最多返回数量上限 100nextTokenstring—分页令牌实现searchTickets.ts会把过滤条件拼成 Freshdesk 搜索语法如agent_id:123 AND tag:vip AND status:2优先走/search/tickets接口无过滤条件时退化为listTickets。联系人操作getContact查询联系人输入contactId输出name、email、phone、mobile、companyId、tags、createdAt。searchContacts搜索联系人参数类型说明emailstring按邮箱精确过滤namestring按姓名前缀搜索不区分大小写nextTokenstring分页令牌输出为contacts数组含id、name、email、phone、companyId与可选nextToken。实现上邮箱搜索走GET /contacts?email姓名搜索走GET /contacts/autocomplete?termFreshdeskClient.ts。典型自动化场景示例新工单自动欢迎与信息补全ticketCreated事件触发后用getTicket拉取工单详情通过searchContacts/getContact获取请求者信息再以addNote写入内部备注供人工客服参考工单升级与 SLA 跟进ticketUpdated事件中检测到status变为open或priority升为urgent时调用updateTicket调整分组/指派并通过createTicket生成关联跟进工单客户回复自动响应ticketReplied事件携带回复正文机器人可据此在流程中生成答复草稿再通过addNoteprivate: false或后续的回复能力同步给客户。已知限制官方文档hub.md明确列出的限制如下搜索页数上限Search Tickets 动作最多扫描 4 页120 条结果Freshdesk 搜索结果之后才会应用limit上限Webhook 需手动配置Freshdesk 的 Webhook 必须通过 Automation Rules 手动创建集成无法自动生成删除工单可恢复被删除的工单位于 Freshdesk UI 的回收站中可在 30 天内恢复不支持附件本集成不处理工单附件。此外从 integration.definition.ts 的 TODO 注释可以推断目前版本尚未开放工单线程ticket channel通道机器人暂时不能直接向工单会话内发送消息replyToTicket动作也尚在 TODO 阶段definitions/actions.ts。如需在工单线程内回复客户可结合addNoteprivate: false等现有能力实现。变更记录Changelog0.1.0首次发布包含createTicket、getTicket、listTickets、updateTicket、deleteTicket、addNote、searchTickets、searchContacts、getContact共 9 个动作以及ticketCreated、ticketUpdated、ticketReplied三个事件。当前仓库中集成的version为 0.1.1见 integration.definition.ts。构建与校验命令可参考 package.jsonbp add -y bp build构建集成tsc --noEmit做类型检查bp lint做集成规范检查。赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Agentic Awesome Skills 的 changelog-updates 技能实战写出开发者真正会读的发布说明与产品更新Agentic Awesome Skills 的 changelog updates 技能实战写出开发者真正会读的发布说明与产品更新 导读 本文围绕开源仓库AI 应用后端OneUptime × Jira 双向集成实战用 Workflow 打通事故工单的完整生命周期OneUptime × Jira 双向集成实战用 Workflow 打通事故工单的完整生命周期 本文基于 packages/App/FeatureSet/Do可观测性后端运维前端云原生微服务AI AgentBotpress Zoom 转录集成实战从 Webhook 配置到 transcriptReceived 事件消费的完整指南Botpress Zoom 转录集成实战从 Webhook 配置到 transcriptReceived 事件消费的完整指南 本指南以 Botpress 开源AI 应用后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考