logo
開發者文件
總覽開發空間工作空間API 參考最佳實踐更新日誌
搜尋
繁體中文
開發空間 / 代理 / 整合 / Zoho Sales IQ
Zoho Sales IQ
最新更新：大約 8 小時內

Zoho Sales IQ

您可以將代理服務整合至 Zoho Sales IQ 內，讓使用 Zoho Sales IQ 的用戶，可以透過 Zoho Sales IQ 與代理溝通。

準備工作

在整合之前，您需要在 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. 進入組織，選擇相應的代理，儲存版本後點擊 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，請先點擊 Integration 後再返回填寫；若未開啟，則不需要填寫。

    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. 代理未發布：整合通道讀取的是已發布版本，代理從未發布過版本時訊息會被丟棄。請先儲存版本並點擊 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 的整合設定頁面；除錯階段也可先關閉該選項驗證連線是否暢通。