AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载导读本文围绕 integrations/freshchat/hub.md 展开系统讲解 Botpress 官方 Freshchat 集成v1.5.7的配置与工作原理如何将 Freshchat 作为 Human-in-the-LoopHITL人机协同渠道接入 Botpress让机器人与 Freshchat 的人工坐席协同处理会话。读完本文你将掌握四个配置字段Topic name / Api Key / Domain Name / 默认坐席头像的确切含义、Freshchat 侧 Webhook 的完整配置步骤以及该集成在源码层面如何处理消息、创建会话与移交坐席的底层机制。集成概述Freshchat 在 Botpress 中的角色Freshchat 是 Freshworks 旗下主打实时对话的客服产品。Botpress 的 Freshchat 集成将 Freshchat 定义为一条HITL 渠道——Botpress 机器人负责前端自动应答当机器人判断需要人工介入时通过 HITL 机制将会话移交给 Freshchat 人工坐席坐席在 Freshchat 控制台回复的消息又会通过 Webhook 回流到 Botpress 会话中实现双向闭环。集成声明的核心信息记录在 integration.definition.ts集成名称freshchat版本1.5.7图标为icon.svg说明文档即hub.md通过.extend(hitl, ...)扩展了hitl接口见 interfaces/hitl/interface.definition.ts因此天然具备 HITL 渠道所需的startHitl、stopHitl、createUser等标准动作定义了一个hitlConversation实体客服工单/会话带可选的priority字段取值为Low / Medium / High / Urgent四档用于在创建 Freshchat 会话时设置优先级。⚠️使用前提如 hub.md 所述若要在 Botpress 上使用该集成开展 HITL 场景必须确保HITL 插件已安装plugins/hitl。HITL 插件负责编排机器人 → 人工坐席的会话生命周期Freshchat 集成只负责与 Freshchat 侧完成通道对接。准备工作Freshchat 侧权限配置该集成前你需要在 Freshchat 的Admin Settings页面操作https://YOUR_COMPANY.freshworks.com/crm/sales/settings因此需要具备管理员或相应权限的账号。核心依赖两样东西默认主题Default Topic名称位于 Admin Settings → Channels → Web Chat → Bot Mapping。HITL 会话将投放到这个主题对应的渠道API Key 与 Domain在https://YOUR_COMPANY.freshworks.com/crm/sales/personal-settings/api-settings页面获取。Botpress 侧配置字段详解Botpress 侧的配置 Schema 定义在 schemas.ts共 4 个字段字段标题源码键名必填说明Topic nametopic_name是用于 HITL 的默认主题名称取自 Admin Settings → Channels → Web Chat → Bot MappingApi Keytoken是Freshchat API Key形如eyJgtWQiOiJjdHK0b20tb2G1...JWT 风格长串Domain Namedomain是Freshchat 域名聊天 URL 中freshchat.com之前的部分形如yourcompany-5b321a95b1dfee217185497Default Agent Avatar URLagentAvatarUrl否坐席默认头像 URL未提供时用坐席姓名的首字母生成仅 Web Chat 生效其中agentAvatarUrl为源码扩充的可选字段官方 hub.md 未提及但确实存在于配置 Schema 中对 Web Chat 场景下的人工坐席展示有实际作用。源码视角配置如何生效从 client.ts 可以看到配置在底层的实际用法axios 客户端以https://${domain}.freshchat.com/v2为 baseURL即Domain Name 决定 API 访问地址每个请求通过请求拦截器自动附加Authorization: Bearer ${token}请求头即Api Key 承担身份认证topic_nameTopic name则被写入集成级 statefreshchat.channelId见 definitions/index.tsstartHitl动作会读取该 state 作为新建 Freshchat 会话的channel_id见 actions/hitl.ts。因此Topic name 与 Domain/Api Key 共同决定了 HITL 会话实际投递到 Freshchat 的哪个渠道三者缺一不可。Freshchat 侧 Webhook 配置双向通信的另一半是 Freshchat → Botpress 的回调。hub.md 给出了明确的 6 步配置流程在 Botpress 集成配置页复制Webhook URL位于配置字段上方形如https://webhook.botpress.cloud/c59a20b8-48t7-407f-82e8-81a66e9e556a打开https://YOUR_COMPANY.freshworks.com/crm/sales/settingsAdmin Settings点击Marketplace and Integrations点击Conversation Webhooks将复制的 Webhook URL 粘贴到Webhook输入框点击Save保存。完成上述 Freshchat 侧配置并在 Botpress 侧填好配置字段后点击Save Configuration即完成整套接线。此后 Freshchat 的会话事件会推送到该 Webhook由集成 handler 统一接收。Webhook 事件分发机制Webhook 入口实现在 handler.ts。集成根据 Freshchat 事件载荷中的action字段做分发action值处理函数职责message_createexecuteMessageCreate坐席消息回流到 Botpress 会话conversation_assignmentexecuteConversationAssignment坐席被分配会话时通知 Botpressconversation_resolutionexecuteConversationResolution会话在 Freshchat 侧被解决时同步状态其他记录警告日志忽略未知事件类型这正是 Freshchat 官方 Webhook 载荷结构actiondata在 Botpress 端的落地映射。HITL 生命周期三个关键动作的底层实现HITL 接口为集成规定了三个标准动作见 actions/hitl.ts完整支撑创建用户 → 发起会话 → 结束会话的生命周期1. createUser跨平台用户映射createUser 依次完成用email作为 tag 在 Botpress 侧getOrCreateUser调用 FreshchatgetOrCreateUser先按 Botpress userId 的reference_id查再按 email 查均无则新建见 client.ts将 Freshchat 返回的id写回 Botpress 用户的tags.id建立Botpress User ↔ Freshchat User 的一对一映射。2. startHitl创建人工会话并附带上下文startHitl 是移交人工的核心动作校验用户已具备 Freshchat User Id否则抛出RuntimeError从集成 state 读取channelId即配置的 Topic name向 Freshchat 发送两条引导消息第一条携带会话Title / Description第二条通过buildConversationTranscript来自botpress/common拼接机器人接手前的完整对话转写让坐席无痛接管上下文调用createConversation创建 Freshchat 会话并携带可选priority对应hitlConversation实体的 Low/Medium/High/Urgent用返回的conversation_id在 Botpress 侧getOrCreateConversationchannel 为hitltag 为 Freshchat 会话 ID返回 Botpress conversationId 给 HITL 插件。底层 API 调用可见 client.tsPOST /v2/conversations载荷包含channel_id、messages、users与可选的properties.priority。3. stopHitl会话解决与状态同步stopHitl 从 Botpress 会话的tags.id取回 Freshchat conversation_id调用PUT /v2/conversations/{id}将状态置为resolved见 client.ts从而在 Freshchat 侧正式关闭人工会话异常时仅记录错误日志而不中断流程。坐席消息回流message_create 的处理细节坐席在 Freshchat 回复后Webhook 触发 executeMessageCreate其处理逻辑很有代表性过滤规则忽略actor_type user的消息只接受坐席/bot 消息忽略message_type private的私密消息会话/用户映射按 Freshchat conversation_id 创建或复用 Botpress 会话channelhitl按 actor_id 创建或复用 Botpress 用户消息体转换遍历message_parts把 Freshchat 的多种内容块文本text、图片image、文件file转换为 Botpress 的bloc消息——文本映射为text块image/*映射为图片块audio/*映射为音频块video/*映射为视频块其余按文件处理坐席资料补全调用updateAgentUser见 util.ts从 Freshchat 拉取坐席的first_name、last_name与头像 URL回填到 Botpress 用户资料未配置agentAvatarUrl时还会作为兜底头像。这套转换机制保证了坐席在 Freshchat 端发出的富媒体内容能在 Botpress 会话中完整呈现。在 Botpress 中使用该集成集成安装并完成上述双向配置后即可搭配HITL AgentBotpress 文档中的 HITL Agent 方案使用在 Botpress Studio 中创建 HITL Agent将其作为 Freshchat 渠道背后的处理者机器人对话与人工坐席介入即可自动衔接。本地构建与验证可选仓库为每个集成提供了标准 npm scripts见 package.json可用于本地开发验证# 安装 bp 依赖并构建集成 bp add -y bp build # 类型检查与 lint npm run check:type # tsc --noEmit npm run check:bplint # bp lint # 运行单元测试 npm run test # vitest --run依赖方面集成基于botpress/sdk、botpress/common、botpress/client与axios并以bpDependencies.hitl显式声明了对interfaces/hitl接口的依赖见 package.json。小结Botpress Freshchat 集成是一条典型的 HITL 渠道实现Botpress 侧四个配置字段 Freshchat 侧一个 Webhook即可打通机器人自动应答 Freshchat 坐席人工接管的完整闭环。其源码结构actions/handler/events/client清晰展示了 HITL 接口的标准实践用户双端映射createUser、会话创建与上下文移交startHitl、会话解决stopHitl、坐席消息回流与富媒体转换message_create。如需进一步研究可对照阅读 集成定义、配置 Schema 与 HITL 接口定义。赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Botpress Vonage 集成实战指南用 SMS 渠道构建 AI 客服与通知机器人Botpress Vonage 集成实战指南用 SMS 渠道构建 AI 客服与通知机器人 本篇指南围绕 Botpress 仓库中的 Vonage 官方集成AI 应用后端CopilotKit 中人机协同HITL的 useHumanInTheLoop 与 useInterrupt 怎么选CopilotKit 中人机协同HITL的 useHumanInTheLoop 与 useInterrupt 怎么选 在 CopilotKit 中做“人机人工智能AI AgentAgent 框架前端后端Botpress Hunter.io 集成实战在聊天机器人中管理 Hunter 客户线索LeadsBotpress Hunter.io 集成实战在聊天机器人中管理 Hunter 客户线索Leads 导读 本指南围绕 Botpress 开源仓库中 HunAI 应用后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考