Freshchat HITL 集成：在 Botpress 中打通 Freshchat 人机协同客服通道

• AI 应用
• 后端

导读

本文围绕 integrations/freshchat/hub.md 展开，系统讲解 Botpress 官方 Freshchat 集成（v1.5.7）的配置与工作原理：如何将 Freshchat 作为 Human-in-the-Loop（HITL，人机协同）渠道接入 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），因此需要具备管理员或相应权限的账号。核心依赖两样东西：

1. 默认主题（Default Topic）名称：位于 Admin Settings → Channels → Web Chat → Bot Mapping。HITL 会话将投放到这个主题对应的渠道；
2. API Key 与 Domain：在https://YOUR_COMPANY.freshworks.com/crm/sales/personal-settings/api-settings页面获取。

Botpress 侧配置字段详解

Botpress 侧的配置 Schema 定义在 schemas.ts，共 4 个字段：

其中agentAvatarUrl为源码扩充的可选字段，官方 hub.md 未提及但确实存在于配置 Schema 中，对 Web Chat 场景下的人工坐席展示有实际作用。

源码视角：配置如何生效

从 client.ts 可以看到配置在底层的实际用法：

• axios 客户端以https://${domain}.freshchat.com/v2为 baseURL，即Domain Name 决定 API 访问地址；
• 每个请求通过请求拦截器自动附加Authorization: Bearer ${token}请求头，即Api Key 承担身份认证；
• topic_name（Topic name）则被写入集成级 statefreshchat.channelId（见 definitions/index.ts），startHitl动作会读取该 state 作为新建 Freshchat 会话的channel_id（见 actions/hitl.ts）。

因此，Topic name 与 Domain/Api Key 共同决定了 HITL 会话实际投递到 Freshchat 的哪个渠道，三者缺一不可。

Freshchat 侧 Webhook 配置

双向通信的另一半是 Freshchat → Botpress 的回调。hub.md 给出了明确的 6 步配置流程：

1. 在 Botpress 集成配置页复制Webhook URL（位于配置字段上方，形如https://webhook.botpress.cloud/c59a20b8-48t7-407f-82e8-81a66e9e556a）；
2. 打开https://YOUR_COMPANY.freshworks.com/crm/sales/settings（Admin Settings）；
3. 点击Marketplace and Integrations；
4. 点击Conversation Webhooks；
5. 将复制的 Webhook URL 粘贴到Webhook输入框；
6. 点击Save保存。

完成上述 Freshchat 侧配置，并在 Botpress 侧填好配置字段后，点击Save Configuration即完成整套接线。此后 Freshchat 的会话事件会推送到该 Webhook，由集成 handler 统一接收。

Webhook 事件分发机制

Webhook 入口实现在 handler.ts。集成根据 Freshchat 事件载荷中的action字段做分发：

这正是 Freshchat 官方 Webhook 载荷结构（action+data）在 Botpress 端的落地映射。

HITL 生命周期：三个关键动作的底层实现

HITL 接口为集成规定了三个标准动作（见 actions/hitl.ts），完整支撑"创建用户 → 发起会话 → 结束会话"的生命周期：

1. createUser：跨平台用户映射

createUser 依次完成：

1. 用email作为 tag 在 Botpress 侧getOrCreateUser；
2. 调用 FreshchatgetOrCreateUser（先按 Botpress userId 的reference_id查，再按 email 查，均无则新建，见 client.ts）；
3. 将 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 侧getOrCreateConversation（channel 为hitl，tag 为 Freshchat 会话 ID），返回 Botpress conversationId 给 HITL 插件。

底层 API 调用可见 client.ts：POST /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 Agent（Botpress 文档中的 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 应用
• 后端