菜单

一般聊天機器人整合（支援串流訊息）

概述

將一般聊天機器人整合至 CINNOX，可讓您連接任何第三方平台的聊天機器人，並在 CINNOX 生態系統內無縫處理客戶查詢。

除了現有的 JSON 格式回應外，CINNOX 現已支援一般聊天機器人的串流訊息（伺服器發送事件，SSE）。此功能可讓聊天機器人的回覆在對話中逐步渲染（逐個 token），無需等待完整回應一次性返回。

串流訊息為選用功能，且完全向下相容。現有的聊天機器人整合無需任何變更即可繼續運作。

此整合需要在 CINNOX 中設定目的地 URL、請求方法、選用參數及 HTTP 標頭。

何時使用串流訊息

串流訊息適用於以下情況：

您的聊天機器人回應是逐步生成的（例如 AI 或大語言模型回應）
您希望使用者看到即時顯示的回覆
您希望提升感知回應速度及對話體驗

若未啟用或不支援串流功能，CINNOX 將自動切換至標準的非串流 JSON 回應。

啟用串流訊息

先決條件
只有同時滿足以下所有條件時，才會使用串流訊息：

聊天機器人來源為一般聊天機器人
聊天機器人的 HTTP 標頭包含：

json 复制代码

{
  "Accept": "text/event-stream"
}

終端使用者正在使用 CINNOX 原生管道（網頁小工具、工作區或應用程式內訊息）

注意：
外部全渠道（例如 WhatsApp、LINE、WeChat、Facebook 等）不支援串流功能，將永遠使用非串流的 JSON 回應。

一般聊天機器人 - 管理後台設定

聊天機器人來源

建立一般聊天機器人的步驟：

從導覽選單進入 管理>頻道>目的地
點擊聊天機器人分頁
在聊天機器人清單的右上角，點擊創建聊天機器人
在聊天機器人來源下拉選單中，選擇一般聊天機器人

設定聊天機器人連線

填寫必要欄位以連接 CINNOX 與您的聊天機器人端點。
方法

選擇 POST

HTTP 方法固定為 POST，無法變更。
此 HTTP 方法表示 CINNOX 將發送資料至您的伺服器以建立或更新資源。

URL（必填）

輸入您的聊天機器人伺服器端點 URL
範例：https://jsonplaceholder.typicode.com/todos/1
這是 CINNOX 發送查詢及訊息請求的位置

URL 參數（選用）

若您的聊天機器人需要額外參數，請輸入鍵值對
範例："enquiryType": "chat"
這些參數將包含在 CINNOX 發送的請求中

HTTP 標頭（選用）

輸入您的聊天機器人服務所需的任何 HTTP 標頭
範例："Content-Type": "application/json"

啟用串流訊息（選用）

若要啟用串流訊息（SSE），請新增以下標頭：

复制代码

{
  "Accept": "text/event-stream"
}

注意：
移除此標頭將會把聊天機器人轉換為標準的非串流 JSON 回應模式。

聊天機器人基本資訊

填寫一般聊天機器人的基本資訊區段：

名稱：輸入聊天機器人的名稱，此名稱會顯示在聊天機器人清單中
最大長度：50 個字元
範例：「客服聊天機器人」
頭像：上傳代表聊天機器人的頭像圖片
建議使用簡單圖示或符合品牌形象的圖片，以提升使用者辨識度
此為選用項目
描述：輸入簡短說明以解釋聊天機器人的用途
範例：「ABC 網站專用客服聊天機器人」

支援語言

選擇此聊天機器人支援的語言。
CINNOX 會根據選取的語言設定，將查詢路由至對應的聊天機器人。

支援地區

使用此設定控制聊天機器人的可用範圍。
可選擇所有國家 / 地區，或指定個別國家、地區及州省。

將聊天機器人對話轉接至真人坐席

啟用此功能後，聊天機器人可允許網頁訪客將對話從聊天機器人轉接至真人客服坐席。
盲轉接
此選項決定當對話已轉接但沒有坐席可用時的處理方式。
啟用時：無人接聽的轉接查詢將被標記為未接查詢，對話不會返回至聊天機器人。
停用時：若沒有坐席可用，查詢將自動返回至聊天機器人。

注意：
若要使用真人坐席轉接功能，請確保已預先設定服務群組及人員分配。

所有欄位設定完成後，點擊建立。

CINNOX 發出的請求

完成必要欄位設定後，每當聊天機器人需要處理查詢時，CINNOX 就會向目的地聊天機器人發送請求。
請求範例

json 复制代码

{
  "query": "user message text",
  "queryParams": {
    "key": "value"
  },
  "inquiryID": "string",
  "action": "input.unknown"
}

請求欄位說明

欄位	類型	說明
query	字串	訪客發送的訊息
queryParams	物件	在 URL 參數中設定的鍵值參數
inquiryID	字串	當訊息來自查詢聊天室時會顯示此欄位
action	字串	標準訊息永遠為input.unknown

向下相容性
CINNOX 同時支援舊版請求格式：
{"queryResult":{"queryText":"..."}}

串流回應行為（選用）

啟用串流訊息後，聊天機器人可使用伺服器發送事件（SSE）逐步返回回應。
串流文字訊息範例

json 复制代码

  {
    "message": {
      "type": 1,
      "text": "partial text",
      "streamType": "delta"
    }
  }

最終回應：
- 不包含 streamType欄位
- 使用與標準文字訊息回應相同的格式

串流錯誤處理（資訊性）

若串流回應中斷或無法完成，CINNOX 會自動處理此狀況並記錄錯誤。
根據不同情況：

部分回應可能會被最終化並顯示
或者查詢可能在沒有聊天機器人回應的情況下結束
管理員無需進行額外設定。

額外上下文資訊（選用）

根據查詢來源及管道的不同，CINNOX 可能會在請求負載中包含額外的上下文元數據。
此資訊可供您的聊天機器人用於了解查詢上下文，例如來源管道、訪客詳細資料或路由資訊。
可能的上下文欄位範例：

json 复制代码

{
  "tagType": "string",
  "tagId": "string",
  "tagName": "string",

  "channelType": "string",
  "channelId": "string",
  "channelName": "string",
  "channelSourceName": "string",
  "channelPhoneNumber": "string",

  "visitorName": "string",
  "visitorPhone": "string",

  "omniType": "string"
}

注意：
這些欄位僅供上下文參考。它們的存在可能因管道及設定而異，聊天機器人實作不應依賴任何特定欄位為必填項。

回應至 CINNOX

第三方聊天機器人必須將回應返回至 CINNOX，以便 CINNOX 據此回覆查詢。
CINNOX 支援一般聊天機器人的兩種回應類型：

文字訊息
進階訊息

📘 注意：
回應必須以 JSON 格式返回至 CINNOX。
啟用串流訊息時，回應將使用伺服器發送事件（SSE）傳送，但訊息物件結構保持不變。

文字訊息

文字訊息可讓聊天機器人以純文字回覆，或觸發特定動作。

鍵	類型	說明
message.type	數字	必須為 1，表示文字訊息
message.text	字串	文字內容或支援的動作關鍵字

支援的 message.text 值

自訂文字：
CINNOX 在查詢聊天室中顯示的確切訊息
範例："請聯絡我們的客戶服務支援團隊。"
DIRECT_TRANSFER：
將查詢從聊天機器人轉接至真人坐席
需要先啟用「將聊天機器人對話轉接至真人坐席」功能
CLOSE_ENQUIRY：
自動關閉查詢
文字訊息回應範例：

json 复制代码

{
  "message": {
    "type": 1,
    "text": "Please contact our customer service support."
  }
}

文字訊息的串流限制

📘 注意：
啟用串流訊息（SSE）時：

僅支援文字訊息（message.type = 1）

不支援進階訊息

串流回應可使用streamType: "delta"逐步返回

進階訊息

進階訊息可讓聊天機器人回覆豐富的互動內容，例如格式化文字、按鈕及媒體檔案。
進階訊息適用於：

引導式使用者互動
選單式導覽
呈現結構化資訊
號召性工作流程（轉接、連結、關閉查詢）

📘 進階訊息限制：

進階訊息僅支援非串流的 JSON 回應
啟用串流訊息（SSE）時不支援進階訊息
若您的聊天機器人需要發送進階訊息，請確保已停用串流訊息

進階訊息欄位

進階訊息由以下值識別：

鍵	類型	說明
message.type	數字	必須為 5，表示進階訊息
message.advanced	字串	必須為"AdvancedMessage"
基本進階訊息範例（帶文字的氣泡）：

json 复制代码

{
  "message": {
    "type": 5,
    "advanced": "AdvancedMessage",
    "advancedItems": [
      {
        "type": 1,
        "items": [
          {
            "type": 9,
            "title": "Title",
            "text": "Body text",
            "footer": "Footer text"
          }
        ]
      }
    ]
  }
}

📘 進階訊息限制：
進階訊息僅支援非串流的 JSON 回應。

訊息格式

進階訊息支援以下格式：

advanced.type	格式
1	氣泡
2	輪播
3	快速回覆
4	清單
9	文字

📘 顯示順序要求
訊息內容必須按照以下順序顯示：
文字 → 媒體檔案 → 按鈕

訊息元件

文字
進階訊息可包含不同的文字樣式，例如標題、內文及頁尾。

鍵	類型	說明
advanced.type	數字	1 = 氣泡，2 = 輪播
advanced.items.type	數字	必須為 9，表示文字元件
advanced.items.title	字串	顯示在訊息中的標題
advanced.items.text	字串	主要內文內容
advanced.items.footer	字串	頁尾內容

📘 注意：
標題、內文及頁尾欄位最多支援 10,000 個字元。

按鈕
進階訊息可包含具有不同動作的按鈕。

鍵	類型	說明
advanced.items.type	數字	必須為 12，表示按鈕
advanced.items.text	數字	按鈕顯示文字（最多 20 個字元）
advanced.items.action.type	字串	動作類型定義
advanced.items.action.text	字串	回傳文字或動作關鍵字
advanced.items.action.url	字串	當動作類型為 URL 時開啟的網址

支援的按鈕動作

回傳（type = 1）
按下時在聊天室中顯示文字
開啟 URL（type = 2）
將訪客重新導向至指定的 URL
DIRECT_TRANSFER
將查詢轉接至真人坐席（需要先啟用轉接功能）
CLOSE_ENQUIRY
自動關閉查詢

媒體檔案
進階訊息可包含圖片、影片及音訊檔案。

advanced.items.type	媒體類型
10	圖片
11	影片
13	音訊

鍵	類型	說明
advanced.items.fileUrl	字串	可公開存取的媒體檔案 URL

📘 支援的格式

圖片：JPEG、JPG、PNG、WebP

音訊：M4A、W4A、MP3、WAV、MPEG、AAC

影片：MP4、3GPP
最大檔案大小： 20 MB

進階訊息的範例
您現有的範例仍然有效，可以原樣保留：

快速回覆
按鈕清單
清單訊息

每個範例都展示瞭如何結合不同的格式、按鈕和媒體元件來建立自訂的聊天機器人回覆。

1. 快速回覆

範例：快速回覆

json 复制代码

{
  "message": {
    "type": 5,
    "advanced": "AdvancedMessage",
    "advancedItems": [
      {
        "type": 1,
        "items": [
          {
            "type": 9,
            "title": "Good Result Learning Center",
            "text": "Your Exam Expert",
            "footer": "Join us now!"
          },
          {
            "type": 10,
            "fileUrl": "https://www.grlc/teaching.png"
          }
        ]
      },
      {
        "type": 3,
        "items": [
          {
            "type": 12,
            "text": "Website",
            "action": {
              "type": 2,
              "url": "https://www.grlc.com"
            }
          },
          {
            "type": 12,
            "text": "Email",
            "action": {
              "type": 1,
              "text": "[email protected]"
            }
          },
          {
            "type": 12,
            "text": "Address",
            "action": {
              "type": 1,
              "text": "Flat 3, 2/F, ABC Building, Castle Peak Road, Tsuen Wan, N.T."
            }
          }
        ]
      }
    ]
  }
}

下圖是根據上述範例鍵值產生的進階訊息回覆範例。

按鈕清單

範例：氣泡按鈕 1

json 复制代码

{
  "message": {
    "type": 5,
    "advanced": "AdvancedMessage",
    "advancedItems": [
      {
        "type": 1,
        "items": [
          {
            "type": 10,
            "fileUrl": "https://www.grlc/teaching.png"
          },
          {
            "type": 12,
            "text": "Button1",
            "action": {
              "type": 1,
              "text": "123"
            }
          },
          {
            "type": 12,
            "text": "Button2",
            "action": {
              "type": 2,
              "url": "https://www.grlc.com"
            }
          }
        ]
      }
    ]
  }
}

下圖顯示根據上述範例鍵值，進階訊息在諮詢聊天中的呈現方式。

範例：氣泡按鈕 2

json 复制代码

{
  "message": {
    "type": 5,
    "advanced": "AdvancedMessage",
    "advancedItems": [
      {
        "type": 1,
        "items": [
          {
            "type": 9,
            "title": "Title",
            "text": "Body",
            "footer": "Footer"
          },
          {
            "type": 10,
            "fileUrl": "https://www.grlc/teaching.png"
          },
          {
            "type": 12,
            "text": "Button1",
            "action": {
              "type": 1,
              "text": "123"
            }
          },
          {
            "type": 12,
            "text": "Button2",
            "action": {
              "type": 2,
              "url": "https://www.grlc.com"
            }
          }
        ]
      }
    ]
  }
}

下圖顯示根據上述範例鍵值，進階訊息在諮詢聊天中的呈現方式。

清單訊息

範例：清單訊息

json 复制代码

{
  "message": {
    "type": 5,
    "advanced": "AdvancedMessage",
    "advancedItems": [
      {
        "type": 4,
        "items": [
          {
            "type": 9,
            "title": "I am title",
            "text": "I am subtitle"
          },
          {
            "type": 12,
            "title": "I am item title 1",
            "text": "I am item description 1",
            "action": {
              "type": 1,
              "text": "I am info key 1"
            },
            "items": [
              {
                "type": 10,
                "fileUrl": "I am imageUri 1"
              }
            ]
          },
          {
            "type": 12,
            "title": "I am item title 2",
            "text": "I am item description 2",
            "action": {
              "type": 1,
              "text": "I am info key2"
            },
            "items": [
              {
                "type": 10,
                "fileUrl": "I am imageUri 2"
              }
            ]
          }
        ]
      }
    ]
  }
}Click Create after all fields are set.

下圖顯示根據上述範例鍵值，進階訊息在諮詢聊天中的呈現方式。

串流限制

當啟用串流訊息（SSE）時，適用以下限制：

項目	限制
最大總回應時間	120 秒
每個串流事件的最大大小	1 MB
最大累積回應大小	4 MB

如果超過這些限制，CINNOX 可能會停止讀取回應。

向下相容性

未設定 Accept: text/event-stream HTTP 標頭的供應商將繼續使用標準的非串流 JSON 回應。
啟用串流訊息僅為供應商端的變更，無需任何 CINNOX 部署或協調。
若要回復為非串流行為，只需從聊天機器人設定中移除 Accept: text/event-stream 標頭即可。

下一個請求將自動使用標準的 JSON 回應格式。

上一个

聊天機器人自訂提示詞最佳實務

下一个

IVR系統(互動語音回應)

最近修改: 2026-04-27

大纲