logo
开发者文档
概述开发空间工作空间API Reference最佳实践更新日志
搜索
简体中文
开发空间 / 智能体 / 人工服务
人工服务
最新更新：大约 13 小时前

人工服务

人工服务功能允许 Agent 开发者接入第三方人工客服系统，以响应 Agent 用户的人工服务请求。当前已支持接入 Intercom、Livedesk、Livechat、Zoho Sales IQ、Sobot 等客服系统，也支持通过 Webhook 或 Custom Helpdesk（自建客服系统） 更灵活地接入其他人工服务系统。

如何启用人工服务

  1. 在 Agent 设置-人工服务，点击「启用」按钮，即可启用人工服务。
  2. 选择需要的人工服务系统，支持 Intercom、Webhook、Livedesk、Custom Helpdesk（自建客服系统）等。
  3. 完成所选择三方人工服务系统的鉴权配置，确保消息互通成功（Custom Helpdesk 无需鉴权配置，详见配置「Custom Helpdesk」）。
  4. 根据企业人工服务支持的实际情况，调整设置人工服务相关配置设置
  5. 在 Agent 对话窗口中，发起人工服务请求即可正常调用人工服务

人工服务模式

人工服务功能包含 3 种模式，分别是 Other to 客服系统、客服系统 to 客服系统 和 Custom Helpdesk（自建客服系统）。

模式 用户从哪里发起对话 谁来接待坐席 GPTBots 的角色 适用场景
Other to 客服系统 Agent 集成支持的任意渠道（WhatsApp / iframe / Widget / Share / LINE 等） 选定的第三方客服系统（如 Intercom） 把用户会话转交给客服系统，并双向转发消息 已使用 Intercom、Livedesk 等客服平台，希望多渠道用户统一由该平台接待
客服系统 to 客服系统 该客服系统自己的渠道（如 Intercom 平台） 同一个客服系统 作为该平台内的 AI 机器人，转人工时交回平台坐席 用户本身就在客服平台内对话
Custom Helpdesk（自建客服系统） 客户自建客服系统自己的渠道 客户自建客服系统的坐席 只做 AI 大脑 + 对话归档，转人工时通过 API 返回信号，不代为转接 客户已有自研客服系统，用户渠道与坐席都在客户侧

以客服系统为 Intercom 为例，前两种模式的区别如下：

flowchart TD
    A["人工服务功能"] --> B["Other to 客服系统"] & C["客服系统 to 客服系统"]
    B --> D["用户从 Agent 集成所支持的渠道发起对话"]
    D --> E["WhatsApp/Iframe/Widget/Share/LINE 等平台"] & G["Intercom 平台"]
    E --> F["Intercom 客服系统接收和处理"]
    G --> Q["无法被 Intercom 系统接收和处理"]
    C --> H["用户从客服系统平台发起请求"]
    H --> I["Intercom 平台"] & K["非 Intercom 平台"]
    I --> J["Intercom 客服系统接收并处理"]
    K --> L["无法被 Intercom 系统接收和处理"]
     A:::Peach
     B:::Sky
     C:::Aqua
     D:::Sky
     E:::Sky
     G:::Sky
     F:::Sky
     Q:::Sky
     H:::Aqua
     I:::Aqua
     K:::Aqua
     J:::Aqua
     L:::Aqua
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D

Custom Helpdesk 模式与前两种的根本区别在于：GPTBots 不再替你"转接"会话。用户渠道和坐席本来就都在你的客服系统里，GPTBots 只负责回答问题，并在需要转人工时通过 Send Message API 的响应告诉你"该转人工了"，后续的坐席分配、消息投递全部由你的系统完成。

配置「Other to 客服系统」鉴权

用户可以从 Agent 集成模块支持的所有平台发起人工服务请求，由选定的客服系统接收和处理用户的人工服务请求。如：

  • 用户在 WhatsApp/iframe/Widget/share/LINE 等平台上发起对话和请求人工服务，Intercom 客服系统将收到该人工服务请求并处理。
  • 若用户在 Intercom 平台上发起人工服务请求，此模式下 Intercom 客服系统将无法收到该人工服务请求。

Intercom 鉴权

  1. 创建 APPS
    首先需要在 intercom 注册并按照引导创建完成 workspace 。通过「账号头像-settings-APPS&INTEGRATIOS」访问 Developer-hub页面。在 Developer-hub 点击「New app」创建一个应用。若已创建好 App,直接选择目标 App进入其设置页面。
    alt text
  2. 获取 AccessToken 并填写到 GPTBots
  • 选择「Authentication」菜单项，复制 Access token 信息。
    intercome Access token
  • 将 token信息填写到「人工服务-intercom 鉴权」的 Access token 输入框中
    alt text
  • 将人工服务消息接收地址填写到 Intercom
    复制「GPTBots 消息接收地址」中的URL 地址，并将该 URL 地址填入在 Webhooks 菜单项的 Endpoint URL 中
    alt text
  • 在 Intercom 订阅关键业务事件
    在 Webhooks 菜单项的 Topics 功能区，使用「Select a topic...」选中4个订阅事件，点击「save」按钮保存配置。
    • conversation.admin.closed
    • conversation.admin.replied
    • conversation.admin.snoozed
    • conversation.read
      至此，Intercom 的配置全部完成，你可以在 Agent 对话窗口请求人工服务，Agent 发起人工服务请求成功时，Intercom 的 Help Desk 会接收到用户消息，当人工客服回复该条消息后人工服务连接正式建立。

Livedesk 鉴权

  1. 登录 Livedesk开发者控制台
  2. 进入 Livedesk 产品，选择「项目设置-API管理-API秘钥」页面，复制 API Key 和 API Secret。
    livedesk秘钥
  3. 将项目秘钥填写到「GPTBots - 人工服务 -Other to Livedesk」的Access token 输入框中，并保存既可完成鉴权配置。
    livedesk人工服务鉴权

Webhook 鉴权

通过 Webhook 提供人工服务的完整教程指南

  1. 首先，开发者需要在自己的服务器环境构建一个 Webhook 接收服务，提供以下3个接口用于接收 Agent 发起的人工服务请求和接收消息。详见人工接管服务。

    • 创建会话:/conversation/establish
    • 聊天：/chat
    • 关闭会话：/conversation/close

  2. 然后，开发者需要在 Agent - 人工服务配置中配置 Webhook 接收服务的 URL 地址、用户名和密码，以便 Agent 能够发送消息到 Webhook 接收服务。
    alt text

    URL地址：必填，用于接收 Agent 端用户发送的消息内容
    用户名：非必填，由开发者所构建的 webhook 服务决定
    密码：非必填，由开发者所构建的 webhook 服务决定

  3. 最后，在「Agent-集成-API」 启用 API 功能，再将 GPTBots 消息接收地址配置为 Webhook 端的消息发送 URL 地址，用于将人工回复消息内容发送到 Agent 对话窗口中。详见人工接管服务。
    alt text
    至此，Webhook 鉴权配置全部完成，你可以在 Agent 对话窗口请求人工服务，Agent 发起人工服务请求成功时，Webhook 接收服务会接收到用户消息。

Webhook 与 Custom Helpdesk 的区别：Webhook 模式下，GPTBots 仍然会主动创建人工会话并把用户消息推送到你的 /chat 接口，坐席回复再通过 API 回传到 Agent 对话窗口，等待超时、会话超时等机制均生效，适合"用户在 GPTBots 渠道（Widget / WhatsApp 等）对话，坐席在你自己的系统"的场景。Custom Helpdesk 模式下 GPTBots 不会主动推送任何消息，只在 API 响应里返回转人工信号，适合"用户和坐席都在你自己的系统里"的场景。

Livechat 鉴权

  1. 开发者需要创建自己的livechat账号，获取到organization_id。 创建livechat账号
    image-20241022195543539

  2. 开发者需要创建APP，添加Blocks，选择App Authorization，设置为服务端app。在该页面，能够获取到clientId。创建APP
    image-20241022193210606
    image-20241022193256452
    image-20241022193615741

  3. 添加Blocks，选择APP webhook，将portal端的GPTBots消息接收地址作为webhook url填入。
    image-20241022200242782

  4. 添加Bolcks，选择Chat webhook，将portal端的GPTBots消息接收地址作为webhook url填入。选择incoming_event和chat_deactivated
    image-20241022194444931
    image-20241022200447947

  5. 点击Priveate installation进到页面，install app
    image-20241022200910085

  6. 将前期准备中的 organization_id 和 liveChatClientId 输入到卡片中，点击确定，完成配置。至此，livechat配置完成。
    image-20241022192841076

Sobot 鉴权

请您参考Sobot集成配置来配置相应的人工服务，Sobot人工服务只能在 sobot widget 中才能使用。

Zoho Sales IQ鉴权

  1. 开发者需要登录自己的Zoho账号，进入Zoho API Console

    注意：如果您的账号为非 US 地区账号，需要切换域名，具体请看：Prerequisite - Generate Org OAuth Token

  2. 在Homepage URL中填写当前服务域名，在Authorized Redirect URIs中，填写当前服务域名 + /api/console/bot/zoho/salesiq/org/redirect，点击CREATE，创建成功后，系统将生成Client ID和Client Secret，复制相应的Client ID 和 Client Secret， 这将会在人工服务配置中用到。
    image-20250508145401316

  3. 登录GPTBots，将在Zoho API Console 中获取的 Clinet ID 和 Client Secret 填入，并填入 Screen Name，选择 Server Region。

    • Client ID 和 Client Secret：必填，已在前期准备中获取；
    • Screen Name：必填，取值来自于账号登录的页面，您需要取域名后面的第一个 path 字符串，例如 https://salesiq.zoho.com/gptbos/mychats/000000000000003 地址，Screen Name 就是取 gptbots；
    • Server Region：选择Zoho账号的区域；
      信息配置好后点击Authorize

  4. 点击Authorize后，将会弹出一个授权状态弹窗，请您点击Accept

  5. Public Key ：选填，如果您在稍后的 webhook 配置中开启了 Secure your webhook，则需要填写；若未开启，则不需要填写。配置Webhook请参考：Zoho Sales IQ 集成配置

  6. 请您选择一个合适的Zoho的人工服务分组，选择分组后，该对话将会被对应的人工客服分组接管。
    image-20250508161142022

  7. 在 Zoho 端配置 Webhook（必做）

    完成上述授权后，还需要在 Zoho Sales IQ 后台创建 Webhook，用于把人工客服的回复消息回传给 GPTBots。

    ⚠️ 若不配置此项，会出现「单向通信」现象：Agent 可以正常将用户转接到 Zoho，Zoho 客服台也能收到用户消息，但客服的回复无法回传到 Agent 对话窗口。

    • 登录 Zoho Sales IQ 控制台，点击右上角齿轮图标进入 Settings，依次进入 Workflows - Data Workflows，点击右上角 Add 新建。

    Zoho Sales IQ 后台 Settings - Workflows - Data Workflows 列表页，点击右上角 Add 新建

    • 按下表填写 Webhook 配置：
    配置项 取值
    Brands 选择与人工服务配置中相同的品牌（即第 6 步所选人工服务分组归属的品牌）
    Module 选择 Conversation
    Events 勾选 conversation.operator.replied（人工客服回复消息）和 conversation.completed（人工客服关闭会话）
    Action 选择 Webhook，URL 填写：当前服务域名 + /api/console/human/callback/zoho/salesiq/event
    • 保存后请确认该 Workflow 状态为 ENABLED，否则不会触发。

    alt text

    注意：此处的 Webhook 地址与「Zoho Sales IQ to Zoho Sales IQ」集成场景所使用的地址不是同一个，请勿混用，否则客服回复消息会被丢弃。
    若在创建 Webhook 时开启了 Secure your webhook，请将 Zoho 生成的 public key 填写到第 5 步的 Public Key 中，否则回调会因验签失败被拒绝。

    注意：在该场景下，智能体无法接收来自Zoho端发送的文件，从Zoho端发送的文件将无法在智能体中显示。

    常见问题：若转接人工时提示转接失败，请检查 Zoho Sales IQ 后台对应品牌的 Live Chat 是否处于启用状态（Settings - Brands - 选择品牌 - Configurations - Channels）。品牌被停用或 Live Chat 开关关闭时，Zoho 会拒绝创建会话并返回 Live chat has been disabled。

配置人工服务

  1. 人工服务
    alt text
    服务状态：展示三方人工服务系统的可用性
  • 未配置：当从未填写三方人工服务系统的鉴权信息时
  • 服务可用：当填写鉴权信息且验证通过时
  • 服务不可用：当已填写的鉴权信息在调用时失效/失败时

触发时机：支持自定义触发时机描述，帮助 LLM 正确判断何时调用人工服务。

  1. 超时机制
    等待超时：默认 60 S，用户发起人工服务请求后的最大等待时长，超时将提示用户结束本次请求或继续等待

会话超时：默认 180 S，人工客服最后 1 条消息产生后，若等待 N 秒后一直无用户回复，将自动退出人工服务

  1. 人工服务时段
    alt text
    支持自定义设置最多 10 条人工服务时间段，规则如下：
  • 每周：此模式下，支持选择周一～周日，设定人工服务时间段，每周循环执行
  • 自定义：此模式下，必须选择一个绝对日期，设定人工服务时间段，只执行一次
    当 Agent 存在多条人工服务时段时,人工服务事件生效机制如下：
  • 首先按照自然日维度，筛选出该自然日的所有「人工服务时段」规则
  • 按照最宽时间窗口规则计算所有的重叠时间规则参数，不重叠则不参与计算
  • 若存在多个不重叠的最宽时间窗口，则该自然日存在多个有效的人工服务时间段，

    例如2024.12.12日生效的人工服务时间规则共 4 条，分别如下：09:00 ~ 12:00、10:00 ~ 1 2:00、13:00 ~ 18:00、15:00 ~ 17:00.
    则系统生效的服务时间窗口为：09:00 ~ 12:00、13:00 ~ 18:00
    非服务时段回复：当前人工服务处于「非人工服务时段」，调用人工服务时会自动回复「预置文案」进行回复
    传递对话轮数：当成功调用三方服务系统，将N 轮的聊天记录+用户最新问题一起提交到人工服务系统，以帮助人工客服更好的理解用户需求。

注意：选择 Custom Helpdesk（自建客服系统） 时，由于 GPTBots 不创建人工会话、不投递消息，上述超时机制、人工服务时段和传递对话轮数均不生效；转人工请求会始终返回成功，等待、排队、非服务时段等逻辑需由你的客服系统自行处理。

发起人工服务请求

  1. 当用户希望获得人工服务时，会由 LLM 判断是否唤醒人工服务，若 LLM 决定唤醒人工服务则会调用人工服务 tools 并要求用户提供邮件地址.当系统已有用户的邮箱信息时，则会跳过「输入邮箱」的环节，直接调起人工服务请求流程。
    alt text
    • 用户已登录状态且账号经过邮箱验证时，系统存在用户邮件信息
    • 开发者在气泡部件场景，通过window.ChatBot.setEmail("somebody@mail.com")命令设置用户邮箱时，系统存在用户邮件信息
    • 开发者在 iframe 场景，通过iframe_url+?email=somebody@mail.com的方式设置用户邮箱时，系统存在用户邮件信息
  2. 当三方人工服务系统接收到用户消息，并回复用户第一条消息时，正式进入人工服务环节
  3. 用户可以不限轮数的与人工服务系统互发消息，用户和人工客服人员均可以主动关闭本次人工服务对话

接入intercom 、 webhook、 livechat等 任何三方人工服务系统，上述功能均适用。
Custom Helpdesk（自建客服系统）模式下，第 2、3 步由你的客服系统自行实现，GPTBots 只负责在第 1 步转人工成功时通过 API 返回信号，详见下文。

配置「客服系统 to 客服系统」鉴权

用户仅可从客服系统平台发起人工服务请求，由同个客服系统接收和处理用户的人工服务请求。如：

  • 用户在 Intercom 平台上发起对话和请求人工服务，Intercom 客服系统将收到该人工服务请求并处理。
  • 若用户在非 Intercom 平台上发起人工服务请求，此模式下 Intercom 客服系统将无法接收和处理该人工服务请求。

Intercom to Intercom

请参考Intercom来配置相应的人工服务。

Zoho Sales IQ to Zoho Sales IQ

请参考Zoho Sales IQ 集成配置来配置相应的人工服务。

注意：在该场景下，由于OpenAI-GPT-4o-mini的模型能力问题，会出现无法唤起人工客服的情况，建议您使用其他模型。

Livechat to Livechat

请参考Livechat 集成配置来配置相应的人工服务。

Livedesk to Livedesk

请参考Livedesk 集成配置来配置相应的人工服务。

配置「Custom Helpdesk」（自建客服系统）

适用于已有自研客服系统的企业：终端用户和坐席都在你的系统里，只把「AI 回答」这一环交给 GPTBots。此模式下 GPTBots 不创建人工会话、不主动投递消息，只在需要转人工时通过发送消息 API 的响应返回信号，坐席分配和消息投递由你的系统完成。

配置步骤

  1. 在 Agent 设置-人工服务中点击「启用」，人工服务系统选择 Custom Helpdesk，无需填写鉴权信息，点击「确定」即可。
  2. 在「Agent-集成-API」启用 API 功能并获取 API Key。
  3. 按需配置「触发时机」；FlowAgent 可在人工服务节点中配置「坐席备注模板」，作为交接备注返回给你的系统。

使用流程

所有交互都通过 发送消息 API 完成：

  1. 正常对话：以 role=user 调用发送消息 API，Agent 正常回复。
  2. 接收转人工信号：Agent 触发转人工时，响应中返回 human_trigger: true 和交接备注 handoff.note（流式为 code 36 / 107 帧）。你的系统据此把会话分配给坐席，备注仅供坐席参考，请勿展示给用户。
  3. 归档消息：人工接管期间，坐席回复以 role=human_agent（可附 human_agent_info 坐席信息）提交，用户消息传 ai_response: false 或不传即可。这类消息只归档、不触发 AI、不消耗积分。
  4. 交回 AI：坐席结束服务后，在下一条用户消息中传 ai_response: true，会话恢复 AI 正常响应。

注意：

  • 此模式下超时机制、人工服务时段、传递对话轮数均不生效，转人工请求始终返回成功。
  • 若坐席结束后忘记传 ai_response: true，该会话会一直停留在「仅归档」状态，用户得不到 AI 回复。
  • 若用户在 GPTBots 的渠道（Widget / iframe / WhatsApp 等）对话、只是坐席在你的系统里，请使用 Webhook 鉴权。