logo
开发者文档
概述开发空间工作空间API Reference最佳实践更新日志
搜索
简体中文
开发空间 / 智能体 / 集成 / Zoho Sales IQ
Zoho Sales IQ
最新更新：大约 5 小时内

Zoho Sales IQ

您可以将 Agent 服务集成至 Zoho Sales IQ 内，让使用 Zoho Sales IQ 的用户，可以通过 Zoho Sales IQ 与 Agent 沟通。

前期准备

在集成之前，您需要在Zoho中配置一些参数，这将会在GPTBots的集成过程中使用。

创建Client ID

  1. 登录Zoho API 控制台

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

    Data Center Developer Console
    US (United States) https://api-console.zoho.com/add
    EU(Europe) https://api-console.zoho.eu/add
    IN(India) http://api-console.zoho.in/add
    AU(Australia) http://api-console.zoho.com.au/add
    CN(China) http://api-console.zoho.com.cn/add
    JP(Japan) http://api-console.zoho.jp/add

  2. 如果您已有可用的Application，进入相应的Application，点击Client Secret，复制相应的Client ID 和 Client Secret， 这将会在GPTBots集成配置中用到。

    image-20250507153254209

  3. 如果您无可用的Application，点击右上角的ADD CLIENT，根据应用类型创建合适的Client 。

    image-20250507153127149

    image-20250507153459912

  4. 若您创建一个新的Application，在Homepage URL中填写当前服务域名，在Authorized Redirect URIs中，填写当前服务域名 + /api/console/bot/zoho/salesiq/redirect，点击CREATE，创建成功后，系统将生成Client ID和Client Secret，复制相应的Client ID 和 Client Secret， 这将会在GPTBots集成配置中用到。

    image-20250507160039517

注意：一个Client ID最多可同时授权成功20次，若超过20次，第一次授权的智能体的zoho授权将会失效。

集成配置

  1. 登录GPTBots

  2. 进入组织，选择相应的Agent，保存版本后点击Publish，发布成功后，点击Integrations

    image-20250225121541516

  3. 在集成方式中选择Zoho Sales IQ

    image-20250507163753173

  4. 填入相应参数

    • Client ID 和 Client Secret：必填，已在前期准备中获取；
    • Screen Name：必填，取值来自于账号登录的页面，您需要取域名后面的第一个 path 字符串，例如 https://salesiq.zoho.com/gptbos/mychats/000000000000003 地址，Screen Name 就是取 gptbots；
    • Email：必填，Zoho账号个人资料绑定的Email；
    • Server Region：选择Zoho账号的区域；
    • Public Key ：选填，如果您在稍后的 webhook 配置中开启了 Secure your webhook，请先点击Integation后再返回填写；若未开启，则不需要填写。

    image-20250507164140213

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

    image-20250507165858728

  6. 授权成功后，GPTBots将会生成一个Webhook URL地址。这时，您需要进入Setting页面。

    image-20250507172323517

  7. 依次进入 Workflows - Data Workflows，点击右上角 Add（View）

    说明：部分账号版本此入口显示为 Webhooks - Data modifications，两者作用一致。

    alt text

    alt text

    alt text

  8. 填写 webhook 内容：

    • Brand：选择要接收 Workflows（Webhook） 的品牌。必须与访客实际使用的品牌一致——即您嵌入网站的那段小部件安装代码所属的品牌。此处选错品牌时，该会话产生的事件不会触发本条 Workflow，表现为 GPTBots 完全收不到消息。

    • Module：选择 Conversation

    • URL to be invoked：填写从GPTBots集成配置获取的 Webhook URL。请直接从集成配置页复制，不要照抄其它环境的地址，否则消息会被发往另一套环境。

    • Events：必须同时勾选 conversation.created 与 conversation.visitor.replied，缺一不可：

      • conversation.created：新会话创建时通知 GPTBots，GPTBots 据此接管（pick up）该会话；
      • conversation.visitor.replied：访客后续每条消息的通知。GPTBots 处理该事件时会校验会话归属，若因缺少 conversation.created 而未完成接管，访客的后续消息都会被丢弃。

      其余事件类型 GPTBots 不做处理，勾选了也不会生效。

    • Action：选择 Webhook

    填写好后点击Create webhook

    alt text

    ⚠️ 注意：此处Webhook URL必须填写 集成配置页生成的 Webhook URL。它与「人工服务 - Other to Zoho Sales IQ」场景使用的回调地址（/api/console/human/callback/zoho/salesiq/event）不是同一个地址，两者用途不同，混用会导致消息被丢弃。若两个场景都要使用，请分别创建两条 Data Workflow。

  9. Secure your webhook：可选步骤，您可以选择是否要验证 webhook 的安全性（是否来自于官方，而不是伪造的请求），开启后，点击生成 public key，复制有 In Use 标记的 public key，填写到GPTBots的集成配置页面。

    image-20250507173308438

在Zoho Sales IQ中与智能体进行对话

集成配置成功后，您可以在Zoho服务中与智能体进行对话。
image-20250507182819135

常见问题

一、会话无法创建，提示 Live chat has been disabled

Zoho 侧对应品牌的在线聊天功能处于关闭状态时，Zoho 会拒绝创建会话并返回该错误。请检查：

  1. 进入 Settings - Brands，确认目标品牌的状态为 Active（列表最右侧开关为开启状态），品牌被停用时其下所有会话均无法创建；
  2. 进入该品牌的 Configurations - Channels，确认 Live chat 开关已开启；
  3. 确认所选部门（Department）未被停用。

若在 Configurations 中找不到 Live chat 开关，通常是 Zoho 账号套餐层面停用了该能力，需联系 Zoho 官方支持处理。

二、在 Zoho 小部件里发消息，Zoho 客服台能收到，但智能体完全不回复

先理解一个前提：GPTBots 收到 Zoho 的 webhook 后会立即返回成功、再异步处理。因此即使消息在 GPTBots 侧被丢弃，Zoho 的 Data Workflows 列表里 Failures 仍然是 0，不能用 Failures 判断有无问题。唯一有效的判断依据是 Last Triggered 列。

第一步：用 Last Triggered 区分是哪一侧的问题

进入 Settings - Workflows - Data Workflows，找到指向集成 Webhook URL 的那条，查看 Last Triggered。注意该列显示的是 Zoho 账号所在时区的时间，与您本地时间可能相差数小时，请先换算再比对。

  • 为空，或不是您刚才发消息的时间 → Zoho 根本没发出请求，问题在 Zoho 侧（见下方 A）；
  • 正是刚才发消息的时间 → 请求已发出，问题在 GPTBots 侧的处理条件（见下方 B）。

A. Zoho 侧：Workflow 未被触发

  1. 该 Workflow 最右侧的开关处于 ENABLED（绿色）状态；

  2. Brands 包含访客实际使用的品牌——打开该会话，在会话详情页顶部可以看到它所属的品牌名，拿它来比对。这是最常见的原因：小部件装的是 A 品牌，而 Workflow 绑的是 B 品牌，事件永远不会触发；

  3. Module 为 Conversation；

  4. Events 同时包含 conversation.created 与 conversation.visitor.replied。

    注意：「人工服务 - Other to Zoho Sales IQ」场景的 Workflow 勾选的是 conversation.operator.replied / conversation.completed，访客发消息不会触发它。已经有那条 Workflow 并不等于集成场景可用，两个场景需要各自一条。

B. GPTBots 侧：请求已收到但被丢弃

  1. URL 用错了场景：集成场景是 /api/console/bot/integration/chat/zoho/salesiq/{clientId}，人工服务场景是 /api/console/human/callback/zoho/salesiq/event。填反时会因找不到对应配置而丢弃消息，且 Zoho 侧依然显示成功；
  2. URL 指向了别的环境：确认域名与您当前使用的环境一致；
  3. 开启了 Secure your webhook 但未填 Public Key：开启后 Zoho 会对每次回调签名，GPTBots 侧 Public Key 为空时校验必然失败并丢弃请求。调试阶段建议先关闭该选项；
  4. 智能体未发布：集成通道读取的是已发布版本，Agent 从未发布过版本时消息会被丢弃。请先保存版本并点击 Publish；
  5. 会话被其它坐席接管：集成场景要求会话归属于集成配置中填写的那个 Email 对应的 Zoho 账号。若会话被其他坐席手动接管，访客的后续消息将不再转给智能体；
  6. 授权已失效：回到 GPTBots 集成配置页确认授权状态正常。同一个 Client ID 授权成功超过 20 次后，最早授权的智能体会失效（见上文提醒），需重新授权。

三、Zoho 侧能收到消息，但人工客服的回复传不回来

这是典型的「单向通信」现象，原因是 Webhook 未生效。请检查：

  1. 进入 Settings - Workflows - Data Workflows，确认对应的 Workflow 状态为 ENABLED；
  2. 确认 Workflow 中选择的 Brands 与实际使用的品牌一致；
  3. 确认 Events 已勾选所需事件，且 URL 填写的是对应场景的地址（集成场景与人工服务场景的地址不同，详见上文第 8 步的提醒）；
  4. 查看列表中的 Last Triggered 列，若始终为空或时间与本次会话不符，说明事件从未触发，请回查上述配置。Failures 列不可作为判断依据（原因见上一条常见问题）。

四、开启 Secure your webhook 后回调失败

开启该选项后，Zoho 会对每次回调附加签名。若 GPTBots 侧未填写对应的 Public Key，签名校验将失败并拒绝该请求。请将 Zoho 中带 In Use 标记的 public key 复制到 GPTBots 的集成配置页面；调试阶段也可先关闭该选项验证链路连通性。