> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/choose-channel/web-chat.md).

# Web Chat 介紹總覽

本篇將介紹 Web Chat 互動功能及自定義介面，讓您打造符合企業風格的 Web Chat 服務

本頁內容：[一、Web Chat 是什麼？](#what-is-webchat)｜[二、打造企業風格的 Web Chat 服務](#branding)｜[三、訊息客製化](#messages)｜[中止正在產生的回覆](#stop-generating)｜[四、多樣性問答內容](#multimodal-qa)｜[五、歷程記憶與對話分享](#memory-and-sharing)｜[六、選擇是否顯示使用工具、引用文件列表](#display-tools-and-citations)｜[七、對話權限保障 - 安全可控的對話環境](#access-control)｜[八、資料收集（Pre-chat 表單）](#pre-chat-form)｜[連線失敗時如何處理？](#connection-failure)｜[生成回覆時回看前文](#review-during-generation)

## <mark style="color:blue;">一、Web Chat 是什麼？</mark> <a href="#what-is-webchat" id="what-is-webchat"></a>

您可以將在 MaiAgent 創建的 Agent 嵌入您的網站，提供即時客服或其他對話。且 Web Chat 為**響應式設計，能在桌面、平板、手機完美適應。**

目前 MaiAgent 提供以下三種嵌入方式：

### 1. 網站右下角嵌入 <a href="#embed-widget" id="embed-widget"></a>

* 嵌入官網服務中，成為官網內建的智能助手
* 不干擾用戶正常瀏覽，需要時隨時可用
* 適合一般客服和諮詢服務

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3880f664a77d58888b950e5e5612652da2b1fbcc%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20125237.png?alt=media" alt=""><figcaption><p>右下角嵌入(可拖移視窗)</p></figcaption></figure>

### 2. 全螢幕嵌入 <a href="#embed-fullscreen" id="embed-fullscreen"></a>

* 提供完整的對話體驗
* 適合複雜的諮詢和服務流程
* 可客製化設計，符合企業需求

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-84b25bce62e614b0545b739650995c0f8fc43225%2Fimage%20(116).png?alt=media" alt=""><figcaption><p>全螢幕嵌入示範</p></figcaption></figure>

### 3. MaiGPT 視窗模式嵌入 <a href="#embed-maigpt" id="embed-maigpt"></a>

* ChatGPT 風格的完整對話介面（左側對話歷史列表 + 右側主對話區），可直接嵌入頁面成為主要 UI
* 可常駐顯示於指定容器，或以右下角浮動按鈕點擊後全屏展開
* 適合做為 AI 入口網站、內部知識入口或產品的主要對話介面

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-40da32c6e68a4607ef47a4430950a10cbb1765b5%2Fmaigpt-embed-overview.png?alt=media" alt="MaiGPT 視窗模式嵌入"><figcaption><p>MaiGPT 視窗模式：ChatGPT 風格完整介面</p></figcaption></figure>

{% hint style="info" %}
MaiGPT 視窗模式可於對話平台設定的 「 <mark style="color:blue;">嵌入</mark> 」 視窗選擇；完整設定步驟請見 [MaiGPT 視窗模式嵌入](/build/choose-channel/web-chat/maigpt-embed.md)。
{% endhint %}

### 訪客可以自己切換的視窗模式 <a href="#visitor-window-modes" id="visitor-window-modes"></a>

右下角嵌入的視窗除了預設的 <mark style="color:blue;">浮動視窗</mark>，還可以開放 <mark style="color:blue;">側邊欄</mark> 模式：對話視窗貼齊網頁右側、佔滿整個高度，適合邊看網頁邊問。網站工程師在嵌入程式碼裡同時開放兩種模式後，電腦版訪客的標題列會出現 <mark style="color:blue;">切換視窗模式</mark> 按鈕，點一下即可在兩種模式間切換；側邊欄模式另有 <mark style="color:blue;">收合</mark> 按鈕可暫時收起。另外還有把對話直接鋪在網頁某個區塊裡的 inline 模式、以及不顯示浮動按鈕的模式，都由嵌入程式碼決定，見技術人員手冊的 [Web Chat 嵌入與 SDK：視窗模式](https://docs.maiagent.ai/tech/serve/web-chat-sdk#window-modes)。

這樣的設計將帶來：

* **即時性**：訪客無需等待，立即獲得專業回答，提升用戶體驗
* **便利性**：右下角浮動設計不干擾正常瀏覽，需要時隨時可用
* **成本效益**：Agent 24/7 服務，大幅降低人力成本
* **專業形象**：展現企業的科技實力和服務品質

## <mark style="color:blue;">二、打造企業風格的 Web Chat 服務</mark> <a href="#branding" id="branding"></a>

MaiAgent 提供自訂 LOGO、頭貼、問答主題色彩等自定義功能，協助您打造企業風格的 Web Chat 服務

您可以透過

1. 選擇 Agent 顯示名稱
2. 上傳您的企業 LOGO
3. 選擇 Agent 顯示頭貼
4. 選擇 Web Chat 主題顏色
5. 選擇 Agent 回覆時的訊息背景顏色

等功能打造屬於您的 Web Chat 外觀：

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-98048f7b5e57344d70831936ed727a91a00604c0%2Fimage%20(118).png?alt=media" alt=""><figcaption><p>預設樣式</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-256f1d936b5145c36cf8f1106d1f9dbd1fbd9103%2Fimage%20(119)%20(1).png?alt=media" alt=""><figcaption><p>自定義樣式</p></figcaption></figure></div>

如此，就可以根據您的企業色彩需求，打造符合企業風格的 Web Chat 服務

Web Chat 會在對話輸入區下方顯示平台品牌標誌；登入、註冊與載入畫面也會以一致比例呈現品牌圖像，不會壓縮或放大變形。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-08a452dcf190d99fb18802f136241351607d360a%2Fwebchat-brand-footer.png?alt=media" alt="Web Chat 輸入區下方顯示 Powered by 與 MaiAgent 品牌標誌"><figcaption><p>Web Chat 底部的品牌標誌會保持清楚且等比例顯示</p></figcaption></figure>

### 深色模式優化 <a href="#dark-mode" id="dark-mode"></a>

MaiAgent 的 Web Chat 深色模式經過全面優化，提供更舒適的視覺體驗：

**動態顏色調整**

* 自動調整主題色彩的明暗度，確保在深色背景下清晰可見
* 智能調整文字對比度，保持最佳可讀性
* 優化圖示和按鈕的顏色，在深色模式下更加醒目

**對比色優化**

* 訊息氣泡背景色經過精心設計，避免視覺疲勞
* 連結和重要資訊使用高對比色，確保清晰辨識
* 輸入框和按鈕的邊框顏色優化，提升操作體驗

**無縫切換體驗**

* 使用者可以隨時在淺色和深色模式間切換
* 切換時保持對話內容和操作狀態
* 系統會記憶使用者的主題偏好

深色模式特別適合：

* 夜間使用或低光環境
* 長時間對話，減少眼睛疲勞
* 符合企業品牌的深色系設計風格

## <mark style="color:blue;">三、訊息客製化</mark> <a href="#messages" id="messages"></a>

在第一次進入 Web Chat 服務時，您可以自由根據以下情境等設定屬於您的 Agent 開場白。開場白是固定文案而非 AI 生成，因此訊息上不會出現讚／倒讚回饋按鈕，也不會計入[使用分析](/build/agent/usage.md#user-satisfaction-rate)的使用者滿意度。

### **1. 開場白客製化** <a href="#greeting" id="greeting"></a>

#### **品牌化問候語**

設定：「歡迎來到我們的網站！我是您的專屬客服小助手」，展現企業專業形象和親切服務態度

#### **引導式開場**

設定：「我可以幫您查詢產品資訊、解答使用問題、協助訂單處理」，以明確告知用戶可提供的服務範圍，建立用戶對服務能力的信任感

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b21ad3d1aa1d753ca4a0e9b2b73af621c62e8e8c%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20152318.png?alt=media" alt=""><figcaption><p>自定義開場白</p></figcaption></figure>

### 2. 引導性起始問題 <a href="#starter-questions" id="starter-questions"></a>

* 設定 「<mark style="color:blue;">對話開始問題</mark>」 作為快速選項
* 用戶可直接點擊常見問題，無需打字
* **範例問題**：
  * 「如何查看已訂購項目？」
  * 「如何下訂單」
  * 「會員積分規則」
  * 「營業時間」

用戶可透過點按起始問題展開對話，加速問答進程：

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ba6c8e8005961ff727708c56c2df863893c7e59b%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20153127.png?alt=media" alt=""><figcaption><p>起始問題設定範例</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c2847c1a6f8cdbfe8c6066e8d85089987d336d56%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20153719.png?alt=media" alt=""><figcaption><p>用戶點按展開對話</p></figcaption></figure></div>

## 中止正在產生的回覆 <a href="#stop-generating" id="stop-generating"></a>

如果送出問題後才發現內容有誤，不必等待 Agent 完成整段回覆。回覆產生期間，輸入框右側的傳送按鈕會變成方形的<mark style="color:blue;">停止</mark>按鈕；點選後即可中止這次回覆，再輸入修正後的問題。

例如，客服人員原本請 Agent 規劃年度產品發表會，送出後才發現忘了說明活動預算。他可以在 Agent 產生回覆時點選<mark style="color:blue;">停止</mark>，接著補上預算與人數重新提問，避免等待不符合需求的內容產生完畢。

### 中止回覆 <a href="#stop-current-response" id="stop-current-response"></a>

{% stepper %}
{% step %}

### 1. 找到停止按鈕 <a href="#find-stop-button" id="find-stop-button"></a>

送出問題後，等待 Agent 開始產生回覆。此時輸入框右側會顯示方形的<mark style="color:blue;">停止</mark>按鈕。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5b470980c305488984de0c77295cf0ef2ae6f57f%2Fwebchat-stop-response.png?alt=media" alt="Web Chat 回覆產生期間，輸入框右側顯示方形停止按鈕"><figcaption><p>回覆產生期間可點選輸入框右側的停止按鈕</p></figcaption></figure>
{% endstep %}

{% step %}

### 2. 停止並重新提問 <a href="#stop-and-ask-again" id="stop-and-ask-again"></a>

點選<mark style="color:blue;">停止</mark>。被中止的回覆下方會標示「回覆已中斷」，輸入框右側立刻換回傳送按鈕，即可輸入修正後的問題並重新送出。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
停止只會中止目前正在產生的回覆，不會刪除您已送出的問題或先前的對話紀錄。
{% endhint %}

### 用鍵盤中止：按 Esc <a href="#stop-with-esc" id="stop-with-esc"></a>

在電腦上，游標停在輸入框時按鍵盤的 Esc，效果和點選<mark style="color:blue;">停止</mark>相同，不必移動滑鼠。沒有回覆正在產生時按 Esc 不會有任何作用，輸入框裡打到一半的文字也會保留。

### 回覆中繼續送訊息：訊息排隊 <a href="#message-queue" id="message-queue"></a>

Agent 還在回覆時，訪客可以在電腦上繼續輸入，按 Enter 送出。這些訊息不會立刻送給 Agent，而是排在輸入框上方的「回覆完成後將依序送出（N 則）」清單裡，等目前的回覆結束後自動依序送出。回覆期間輸入框右側的按鈕是<mark style="color:blue;">停止</mark>，所以排隊要用 Enter 鍵送出。排隊中的訊息：

* 點一下可放回輸入框修改再送
* 點右側的 <mark style="color:blue;">移除</mark> 可取消
* 排滿時會提示「最多可排 N 則訊息，請等候回覆完成」

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-697fc31a977d189aef4631a049501e43b61e988d%2Fwebchat-message-queue.png?alt=media" alt="輸入框上方顯示「回覆完成後將依序送出（1 則）」與一則排隊中的訊息，右側有移除按鈕，輸入框右側為停止按鈕"><figcaption><p>回覆中按 Enter 送出的訊息會排在輸入框上方</p></figcaption></figure>

想立刻讓 Agent 改處理新的問題，就先按<mark style="color:blue;">停止</mark>或 Esc，再送出。停止時已排隊的訊息會保留，等被中止的回覆收尾後（最多約 10 秒）自動送出。

例如，訪客在官網 Web Chat 請 Agent 詳細介紹平台所有功能，回覆到一半才想到要改成條列式。他在輸入框打「再補充一下，請用條列式整理。」按 Enter，這句先排進清單；接著按 Esc 中止那段冗長的回覆，畫面標示「回覆已中斷」，片刻後排隊的訊息自動送出，Agent 接著回覆這則新訊息。

{% hint style="warning" %}
以下情況不會排隊：

* **帶附件的訊息**：回覆中附加了檔案再送出，畫面會提示「AI 回覆中」，文字和檔案都留在輸入框，等回覆結束後再送；按<mark style="color:blue;">停止</mark>的話，要稍候片刻（最多約 10 秒）等被中止的回覆收尾。
* **手機與平板**：輸入框的 Enter 是換行，回覆期間右側只有<mark style="color:blue;">停止</mark>按鈕，要先停止或等回覆結束才能送出下一則。
  {% endhint %}

## <mark style="color:blue;">四、多樣性問答內容</mark> <a href="#multimodal-qa" id="multimodal-qa"></a>

### 1. 多語言支援 <a href="#multi-language" id="multi-language"></a>

依使用者使用語言回覆，消除溝通障礙。

* **自動偵測**：根據用戶輸入之語言選擇 Agent 回覆語言

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6ddc78047a3aef2815f71e26c3d498588224141c%2Fimage%20(127).png?alt=media" alt=""><figcaption></figcaption></figure>

**手動切換**：

1. 使用 Web Chat 介面選擇使用語言，請見：[多國語言支援：Web Chat 聊天設定](/build/agent/multi-language-support.md#web-chat-language-settings)。
2. 使用 Web Chat 初始化時腳本 (javascript) 指定 Agent 回覆語言，請見：[技術人員手冊—Web Chat 嵌入與 SDK（`locale` 設定）](https://docs.maiagent.ai/tech/serve/web-chat-sdk#config-basic)。

{% hint style="info" %}
支援語言列表，請見：[多國語言支援：支援語言列表](/build/agent/multi-language-support.md#supported-language-list)
{% endhint %}

### 語音輸入與語音播放 <a href="#voice-input-and-playback" id="voice-input-and-playback"></a>

Agent 開啟語音服務後，Web Chat 訪客端會多出三樣東西：

| 位置                                             | 功能                                                                                                                                                                                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 輸入框左側的 <mark style="color:blue;">麥克風</mark> 圖示 | **語音輸入**：點一下開始說話，畫面顯示「正在聆聽」，說完後辨識結果會自動送出成一則訊息                                                                                                                                                                                               |
| 設定選單的 <mark style="color:blue;">語音</mark>      | 選擇語音辨識的語言與供應商：<mark style="color:blue;">微軟 Azure</mark>（國語、簡體中文、英文、日語、韓語、泰語、越南語、印尼語、馬來語、菲律賓語、緬甸語、高棉語、寮國語、新加坡英語）、<mark style="color:blue;">長問 Bronci</mark>（台語）、<mark style="color:blue;">內建</mark>（國語、英文，使用瀏覽器自己的語音辨識）。辨識語言要和訪客說的語言一致，才辨識得準 |
| 設定選單的 <mark style="color:blue;">語音播放</mark>    | 開啟時 Agent 的回覆會自動用語音念出來；關閉就只顯示文字。預設開啟                                                                                                                                                                                                        |

設定選單在電腦版是標題列上的設定列，在手機版是右上角的 <mark style="color:blue;">⋮</mark>。

{% hint style="info" %}
這裡的語音輸入是「說一句、辨識成文字、送出」。若 Agent 開啟了[語音助理](/build/agent/voice-agent.md)，輸入框旁還會多一顆 <mark style="color:blue;">耳機</mark> 圖示，可以進入即時的語音通話，見[語音助理：使用者端怎麼用](/build/agent/voice-agent.md#how-users-talk)。
{% endhint %}

### 2. 多模態問答 <a href="#multimodal" id="multimodal"></a>

除文字問答外，Agent 也可支援不同類型的檔案上傳：

* 試算表：.xls, .xlsx, .csv, .ods
* 文書處理文件：.doc, .docx, .odt, .pdf, .md, .txt
* 簡報文件：.ppt, .pptx, .odp
* 網頁文件：.html, .htm
* 資料格式：.json, .jsonl
* 音訊文件：.wav, .mp3, .m4a, .aac
* 視訊文件：.mp4

{% hint style="info" %}
您可以不允許使用者上傳附件，僅使用文字進行對話，保障對話安全。
{% endhint %}

#### 圖片內容處理

**圖片識別與分析**

* **上傳圖片分析**：用戶可上傳產品圖片，AI 自動識別並提供相關資訊
* **截圖處理**：支援螢幕截圖分析，協助解決使用問題
* **圖片說明**：自動生成圖片內容描述和相關建議

**圖片回覆功能**

* **產品圖片展示**：回覆中包含產品實體圖片
* **操作指引圖**：提供步驟化的操作截圖

範例：

1. 使用者詢問該去哪裡設定 MaiAgent 的 Agent，Agent 以圖片方式回應設定畫面
2. 使用者截圖向 Agent 確認該路徑是否正確，Agent 正確解析後回應

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-71263c2534efc1ba8bb19b493e761d88f0ef2c5f%2Fimage%20(122).png?alt=media" alt=""><figcaption><p>Agent 以圖片回應</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c71336dcd8110e7f04f15a551ff3d4b3fd2dbdb1%2Fimage%20(123).png?alt=media" alt=""><figcaption><p>Agent 解析使用者截圖內容</p></figcaption></figure></div>

#### 文件處理能力

**支援文件格式**

* **PDF 文件**：自動解析 PDF 內容並回答相關問題
* **Word 文件**：處理 .doc/.docx 格式文件
* **Excel 表格**：分析試算表數據並提供洞察
* **PowerPoint 簡報**：提取簡報內容並回答問題
* **郵件檔**：處理 Outlook 的 .msg 與 .eml 郵件，讀取信件資訊、內文與信中夾帶的文件附件

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fb182a0ccc7d4f5fd35c125480e6582808f3dfda%2Fwebchat-email-attachments.png?alt=media" alt="Web Chat 讀取上傳的 EML 郵件，回答 PDF 與 CSV 的檢驗結果、寄件者與日期"><figcaption><p>訪客可從附件入口上傳郵件，詢问信件與文件附件的內容</p></figcaption></figure>

**文件互動功能**

* **文件內容查詢**：基於上傳文件回答特定問題
* **數據分析**：自動分析表格數據並以表格方式提供統計資訊
* **文件摘要**：生成長文件的關鍵內容摘要

***

範例 1：請 Agent 以表格方式呈現資料內容，並給予參考資料連結

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b31d4a6935949e33bd1007689bb0fba9782f730f%2Fimage%20(132).png?alt=media" alt=""><figcaption><p>表格方式整理資訊</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f7cd38de66136fd5b12b73f4f143fff7ae00aa30%2Fimage%20(133).png?alt=media" alt=""><figcaption><p>給予外部連接</p></figcaption></figure></div>

範例 2：請 Agent 分析銷貨內容，並給予表格解析

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-150fb2de65a75b631b5dcb1721f03e2c73ae297d%2Fimage%20(131).png?alt=media" alt=""><figcaption></figcaption></figure>

範例 3：傳入 docx 檔案，請 Agent 協助分析 CV 撰寫上問題

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-4354e35d4f0e524745e7859982782380ca89d980%2Fimage%20(134).png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Agent 在回答時皆使用 Markdown 格式回覆，井然有序編排回應內容。
{% endhint %}

**Agent 交付的檔案**：Agent 用 Code Interpreter 產出檔案交付給使用者時，Web Chat 會在回覆中顯示檔案卡片（檔名、類型與下載按鈕），點卡片可直接預覽；Agent Teams 中由子 Agent 產出的檔案也會以同樣方式呈現。

## <mark style="color:blue;">五、歷程記憶與對話分享</mark> <a href="#memory-and-sharing" id="memory-and-sharing"></a>

### **1. 對話歷史記憶** <a href="#chat-history" id="chat-history"></a>

為提供連續性的服務體驗，Web Chat 會自動記憶用戶的對話歷史，讓每次對話都能建立在之前的基礎上。

**記憶內容範圍**

* **對話內容**：完整的問答記錄，包含文字、圖片、文件等
* **服務狀態**：未完成的查詢、待處理的問題

開啟「顯示對話歷史」後（見[互動設定](/build/conversation-settings/platform-settings/interaction-settings.md#conversation-display)），標題列左側會出現 <mark style="color:blue;">時鐘</mark> 圖示，點開就是歷史對話側欄：

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-516cd7f27f014ac3d1ccd66d011d495c1db67266%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20171142.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e794f1deb35a654a2724917cd732fa298ed7ccb9%2Fimage%20(135).png?alt=media" alt=""><figcaption></figcaption></figure></div>

| 位置                                          | 功能                                                                                                                                                                                                                                                                           |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 側欄上方的 <mark style="color:blue;">搜尋對話</mark> | 開啟搜尋面板，輸入關鍵字即時篩選對話；面板裡也可以直接點 <mark style="color:blue;">新對話</mark>                                                                                                                                                                                                            |
| 側欄上方的 <mark style="color:blue;">新對話</mark>  | 開一段全新的對話                                                                                                                                                                                                                                                                     |
| 側欄上方的 <mark style="color:blue;">編輯對話</mark> | 已登入的訪客才會看到，勾選多則對話一次刪除，見下方[一次刪除多則對話](#history-batch-delete)                                                                                                                                                                                                                   |
| 對話清單                                        | 依 <mark style="color:blue;">今天</mark>／<mark style="color:blue;">昨天</mark>／<mark style="color:blue;">過去 7 天</mark>／<mark style="color:blue;">過去 30 天</mark>／<mark style="color:blue;">更早</mark> 自動分組；用過[對話交接](/work/maigpt/chat/conversation-handoff.md)的對話會標示「已交接至」或「接續自原對話」 |
| 每則對話的 <mark style="color:blue;">⋯</mark>    | <mark style="color:blue;">重新命名</mark>（改標題）、<mark style="color:blue;">刪除</mark>（確認後刪除，無法復原）；平台開啟對話分享時另有 <mark style="color:blue;">分享</mark>，見下方[對話分享](#chat-sharing)                                                                                                          |

未開啟對話歷史時，時鐘圖示的位置改為 <mark style="color:blue;">新對話</mark> 圖示，訪客只能開新對話、看不到過去的紀錄。

#### 一次刪除多則對話 <a href="#history-batch-delete" id="history-batch-delete"></a>

對話平台開啟登入功能（見[網站：登入設定](/build/choose-channel/web-chat/website.md#login-settings)）時，已登入的訪客可以在歷史對話側欄勾選多則自己的對話，一次刪除。未登入的訪客看不到這個入口，仍可用每則對話的 <mark style="color:blue;">⋯</mark> 逐則刪除。

例如，網路商店的會員在客服 Web Chat 問過訂單出貨、退貨文件與發票抬頭三件事，問題都解決後，她想清掉其中兩則、只留訂單那則備查。她打開歷史對話側欄，按 <mark style="color:blue;">編輯對話</mark>，勾選另外兩則後按 <mark style="color:blue;">刪除</mark>，確認後側欄只剩訂單那則。她刪掉的對話裡有一則正開著，畫面也自動換成新對話。

1. 點標題列左側的 <mark style="color:blue;">時鐘</mark> 圖示打開歷史對話側欄，按 <mark style="color:blue;">新對話</mark> 左邊的鉛筆圖示 <mark style="color:blue;">編輯對話</mark>。進入編輯模式後，按鈕會變成勾號圖示 <mark style="color:blue;">完成</mark>，每則對話前面出現勾選框，<mark style="color:blue;">⋯</mark> 選單暫時隱藏。
2. 點對話列選取要刪除的對話；在編輯模式中點對話列只會勾選，不會打開對話。也可以按清單上方的 <mark style="color:blue;">全選</mark>，選取側欄目前已載入的對話，每次最多 100 則；再按一次取消全選。清單上方會顯示「已選 N 則」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-67fcd800c92fa8d2619c5611e3e41c9151c11ab4%2Fweb-chat-history-batch-select.png?alt=media" alt="Web Chat 歷史對話側欄進入編輯模式，三則對話中勾選了兩則，上方顯示全選、已選 2 則與紅色刪除按鈕"><figcaption><p>勾選要刪除的對話後，清單上方會顯示已選取的數量。</p></figcaption></figure>

3. 按 <mark style="color:blue;">刪除</mark>，確認視窗會顯示「刪除 N 則對話？」，核對數量後按 <mark style="color:blue;">刪除</mark>。全部成功時會顯示「已刪除 N 則對話」，並離開編輯模式。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-591662080b4c39ecc5d9866a7e92be769b976202%2Fweb-chat-history-batch-delete-confirm.png?alt=media" alt="確認視窗標題為刪除 2 則對話？，內文說明這些對話中的所有訊息會一起刪除，刪除後無法復原，下方有取消與刪除按鈕"><figcaption><p>確認視窗會列出這次要刪除的則數。</p></figcaption></figure>

{% hint style="warning" %}
對話中的所有訊息會一起刪除，介面不提供復原。
{% endhint %}

* 刪除的對話包含目前開著的那一則時，畫面會自動換成新對話。
* 有幾則沒刪成功時（例如那則對話已在另一個分頁刪掉），會顯示「已刪除 N 則，M 則刪除失敗」：成功的從清單移除，失敗的留在清單上並維持勾選，畫面停在編輯模式，可以再按一次 <mark style="color:blue;">刪除</mark> 重試或按 <mark style="color:blue;">完成</mark> 離開。整批都沒送出（例如網路中斷）時會顯示「刪除失敗，請稍後再試」，清單與勾選都不變。
* 不想刪除時，按 <mark style="color:blue;">完成</mark> 或關閉側欄，就會離開編輯模式，勾選一併清除。
* 側欄還沒有任何對話時，不會出現 <mark style="color:blue;">編輯對話</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fc25fd8d962b878f53f7002f6eaea49f828d5612%2Fweb-chat-history-batch-partial-failed.png?alt=media" alt="部分刪除失敗後，歷史對話側欄仍在編輯模式，只剩一則未刪除的對話並維持勾選，上方顯示已選 1 則"><figcaption><p>沒刪成功的對話會留在清單上並維持勾選。</p></figcaption></figure>

記憶對話功能可使用於：

* **連續諮詢**：用戶詢問「上次推薦的帳篷型號是什麼？」 ，AI 能立即回憶並回答
* **進度追蹤**：用戶說「繼續上次的訂單查詢」，AI 自動調出相關資訊
* **個人化服務**：根據歷史對話提供更精準的推薦和建議

{% hint style="info" %}
同一個對話聊得太長時，可以開啟「對話交接」，讓訪客請 Agent 整理交接摘要、開新對話接著聊。Web Chat 的開啟方式與限制見[對話交接：在 Web Chat 開啟](/work/maigpt/chat/conversation-handoff.md#enable-on-web-chat)；以 API 建立接續對話見技術手冊的[對話交接與接續對話 API](https://docs.maiagent.ai/tech/serve/conversation-handoff-continuation)。
{% endhint %}

### **2. 對話分享** <a href="#chat-sharing" id="chat-sharing"></a>

當諮詢 Agent 後想分享對話給朋友或同事，或內部團隊需要協作討論客戶問題，可使用 MaiAgent 服務產生對話分享連結：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5a43d6523e30f0539424a2d220e71f053420d7df%2Fimage%20(136).png?alt=media" alt=""><figcaption></figcaption></figure>

點擊對話視窗右上角的 <mark style="color:blue;">分享</mark>，在「分享對話的公開連結」視窗按 <mark style="color:blue;">複製連結</mark>，即可傳給對方；歷史對話側欄裡每則對話的 <mark style="color:blue;">⋯</mark> → <mark style="color:blue;">分享</mark> 也能取得同一種連結。

**收到連結的人看到什麼**

* 一個唯讀的對話頁，內容是這段對話到目前為止的所有訊息，包含文字、圖片與附件
* 不需要登入就能開啟，所以請只分享給該看的人
* 只能看，不能在這一頁接著輸入；想繼續問，請回到原本的 Web Chat 開啟對話

{% hint style="info" %}
分享連結只呈現對話紀錄本身，不會另外產生摘要或整理相關資源。
{% endhint %}

對話紀錄分享可使用於：

* **客戶分享**：「這個露營裝備推薦很棒，分享給登山社團」
* **內部協作**：客服人員分享複雜問題給技術支援團隊
* **培訓用途**：分享典型對話案例作為員工培訓教材

### **3. 對話逾時管理** <a href="#chat-timeout" id="chat-timeout"></a>

為確保對話品質和系統效能，Web Chat 具備智能對話逾時管理機制：

**智能過濾機制**

* **自動過濾問候訊息**：系統會識別並過濾開場問候語，不計入對話逾時計算
* **正確重置訊息計數**：當對話重新開始時，訊息計數器會正確重置
* **優化逾時判斷**：只針對實質對話內容進行逾時計算，提供更準確的對話管理

**對話持續性保障**

* 確保使用者在正常對話過程中不會意外逾時
* 長時間思考或暫停後仍可繼續對話
* 系統會智能判斷對話是否仍在進行中

**實際運作方式**

1. **開始對話**：使用者發送問候語（如「你好」），系統不計入逾時
2. **進入對話**：使用者開始詢問實質問題，逾時計時器啟動
3. **對話暫停**：若使用者暫時離開，系統會保持對話狀態
4. **重新開始**：使用者返回繼續對話，訊息計數正確更新

這項優化讓對話體驗更加流暢自然，使用者不需擔心因思考時間過長而中斷對話。

### **4. 訊息操作：編輯、回饋與分岔** <a href="#message-actions" id="message-actions"></a>

滑到訊息上會出現操作圖示，做法與 MaiGPT 相同，完整說明見 [MaiGPT：訊息操作](/work/maigpt/chat.md#message-actions)。Web Chat 的差異在於**哪些訪客看得到**：

| 操作                                                                                                                | 誰能用                               | 說明                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI 回覆的 <mark style="color:blue;">複製</mark>、<mark style="color:blue;">讚</mark>、<mark style="color:blue;">倒讚</mark> | 所有訪客                              | 倒讚會開啟「提供回饋」視窗，勾選原因、補充其他回饋後送出。回饋會進到後台的[對話查看器](/serve/daily-operations/reply/conversation-viewer.md)與[使用分析](/build/agent/usage.md#user-satisfaction-rate)的滿意度統計 |
| 自己訊息的 <mark style="color:blue;">編輯訊息</mark> 與版本切換 <mark style="color:blue;">‹ N / M ›</mark>                      | 已登入的訪客（平台開啟[登入功能](#login-config)） | 編輯會刪除之後的對話並讓 Agent 重新回覆；內容沒有變動時無法送出                                                                                                                           |
| AI 回覆的 <mark style="color:blue;">分岔對話</mark>                                                                      | 已登入的訪客                            | 以這則回覆為止另開一段對話，原對話不受影響                                                                                                                                         |

### **5. 已連接的服務** <a href="#connected-services" id="connected-services"></a>

Agent 需要代訪客存取外部服務（例如用訪客自己的帳號查行事曆）時，會在對話中送出授權卡。訪客授權過的服務可以在標題列的 <mark style="color:blue;">已連接的服務</mark>（鏈結圖示）統一查看、重新授權或解除連接；只有已識別身分的訪客（填過 Pre-chat 表單、已登入，或由網站以 Source ID 帶入身分）才看得到這顆按鈕。完整說明見 [已連接的服務](/build/choose-channel/web-chat/connected-services.md)。

## <mark style="color:blue;">六、選擇是否顯示使用工具、引用文件列表</mark> <a href="#display-tools-and-citations" id="display-tools-and-citations"></a>

### **1. 顯示使用工具列表** <a href="#show-tools" id="show-tools"></a>

您可選擇是否讓使用者看見 Agent 在推理時使用之工具列表，若允許，Agent 在產出回覆時會出現以下畫面：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-397b3d1960642ae0a98c9097422f2fa66f89c543%2Fimage%20(140).png?alt=media" alt=""><figcaption></figcaption></figure>

您可透過此列表追蹤 Agent 使用的工具內容是否正確。

若 Agent 呼叫的 MCP 工具附有互動介面，回覆下方還會出現一張可直接操作的卡片，見 [MCP 互動卡片（MCP Apps）](/build/tools/mcp-apps.md)。

### **2. 顯示引用文件列表** <a href="#show-citations" id="show-citations"></a>

每個 AI 回答都會自動生成引用文件列表，清楚標示資訊來源，提升回答的可信度和可追溯性。

**顯示設定**

企業可根據需求設定是否讓使用者看到引用的工具列表和參考文件名稱內容，若開放顯示，則在 Agent 的回應底部會出現以下列表。點擊「引用節點」，則可以看見參考的文件片段：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-380a3f1aadb6212090fd6ed70f0c93d56a2224e9%2Fimage%20(139).png?alt=media" alt=""><figcaption></figcaption></figure>

依照不同的使用情景，可選擇是否公開引用資訊：

* **公開客服**：顯示所有引用資訊，建立信任感
* **內部支援**：隱藏敏感文件，保護機密資訊
* **教育機構**：顯示學習資源，方便學生查閱

## 回覆旁的面板：畫布與瀏覽器 <a href="#side-panels" id="side-panels"></a>

Agent 的回覆不一定只有文字。產出文件、圖表、網頁或地圖時，桌面版會在對話右側打開一個面板，手機版則覆蓋整個對話畫面；面板可以關閉，訊息裡會留下該次產出的卡片，之後點卡片可以再打開。這一節說明訪客會看到的三種面板。

### 畫布（Canvas） <a href="#web-chat-canvas" id="web-chat-canvas"></a>

Agent 以畫布形式產出 Markdown 文件、Mermaid 圖表、HTML 或 React 互動頁面時，畫布會自動開啟。面板上方的工具列：

| 按鈕                                                                             | 做什麼                                                                                                                                |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">切換到程式碼</mark>／<mark style="color:blue;">切換到預覽</mark> | 在渲染後的畫面與原始內容之間切換                                                                                                                   |
| <mark style="color:blue;">控制台</mark>、<mark style="color:blue;">重置程式碼</mark>    | 只有 React 互動頁面才有：查看執行訊息、把程式碼恢復成 Agent 最初產出的版本                                                                                       |
| <mark style="color:blue;">全螢幕</mark>／<mark style="color:blue;">退出全螢幕</mark>    | 把畫布放大到整個視窗                                                                                                                         |
| <mark style="color:blue;">下載</mark>                                            | <mark style="color:blue;">下載原始檔案</mark>（依類型為 .md、.mmd、.html 或 .jsx）或 <mark style="color:blue;">下載 PDF</mark>；內容還在編譯時會顯示「編譯完成後才能下載」 |
| <mark style="color:blue;">關閉</mark>                                            | 收起面板，訊息中的畫布卡片仍可再打開                                                                                                                 |

桌面版可以拖曳面板左緣調整寬度。畫布的用途、適合的指令與匯出細節與 MaiGPT 相同，見 [Canvas 畫布](/work/maigpt/canvas.md)。

### 地圖畫布 <a href="#map-canvas" id="map-canvas"></a>

Agent 回答地點或行程類問題（例如餐廳推薦、三天兩夜行程）時，可能改用地圖畫布：左側是 Google 地圖與地點標記，右側（手機版為下方）是地點卡清單。

* **篩選**：<mark style="color:blue;">篩選</mark> 下拉可依 <mark style="color:blue;">類別</mark>（餐廳、咖啡廳、住宿、景點、購物、自然、交通、其他）、<mark style="color:blue;">條件</mark>（<mark style="color:blue;">僅顯示營業中</mark>、<mark style="color:blue;">4.5★ 以上</mark>）與 <mark style="color:blue;">顯示</mark>（評分徽章、名稱標籤）過濾；沒有符合的地點時顯示「沒有符合篩選條件的地點」。
* **多天行程**：行程分天時，地圖左上角會出現 <mark style="color:blue;">全部</mark>／<mark style="color:blue;">第 N 天</mark> 切換，清單依上午、下午、晚上、未排定分組。
* **地點詳情**：點地點卡開啟詳情，分為 <mark style="color:blue;">總覽</mark>（地點介紹、地址、網址、電話、營業時間與 <mark style="color:blue;">營業中</mark>／<mark style="color:blue;">休息中</mark>）與 <mark style="color:blue;">評論</mark> 兩個分頁；下方有 <mark style="color:blue;">導航</mark>、<mark style="color:blue;">撥打電話</mark>、<mark style="color:blue;">開啟網站</mark> 與 <mark style="color:blue;">在 Google Maps 中開啟</mark>。詳細資訊取自 Google，載入不到時顯示「無法取得詳細資訊」。

地圖畫布的 <mark style="color:blue;">切換到程式碼</mark> 會顯示地點資料的原始內容，<mark style="color:blue;">下載原始檔案</mark> 會存成 .json。

### 瀏覽器面板 <a href="#browser-panel" id="browser-panel"></a>

Agent 啟用了 [Browser Tool](/build/agent/browser-tool.md) 並開始操作網頁時，右側會出現 <mark style="color:blue;">瀏覽器</mark> 面板，即時顯示 Agent 看到的網頁截圖與目前網址；Agent 動作時標示 <mark style="color:blue;">AI 操作中</mark>，還沒有畫面時顯示「等待瀏覽器畫面…」。

訪客可以在 Agent 停下來時介入操作，例如替 Agent 輸入驗證碼、帳號密碼或選一個選項：

* 直接在截圖上點擊、雙擊、按右鍵或捲動，動作會送到 Agent 操作的網頁。
* 面板底部的輸入框 <mark style="color:blue;">在此輸入文字，按 Enter 送出至瀏覽器</mark>：輸入文字後按 Enter 送出；輸入框空白時按 Enter、Esc 或方向鍵等按鍵也會直接送到網頁。Agent 操作中時輸入框暫時停用。
* 按右上角 <mark style="color:blue;">關閉</mark> 收起面板後，輸入框上方會出現 <mark style="color:blue;">重新開啟瀏覽器畫面</mark>，點它即可再看。

{% hint style="warning" %}
在面板裡輸入的帳號密碼會送進 Agent 正在操作的網頁，請只在信任這個 Agent 與其背後企業的情況下輸入。
{% endhint %}

## <mark style="color:blue;">七、對話權限保障 - 安全可控的對話環境</mark> <a href="#access-control" id="access-control"></a>

### 1. 登入功能設定 <a href="#login-config" id="login-config"></a>

**強制登入機制**

為確保對話內容的安全性和可控性，企業可開啟登入功能，要求用戶必須先登入才能使用 Agent 服務。設定完成後，訪客點擊 Web Chat 時會先進入登入頁面，只有成功登入的用戶才能開始與 Agent 對話

**安全優勢**

* **身分驗證**：確保每個對話用戶都有明確身分
* **權限控制**：根據用戶身分提供對應的服務內容
* **對話追蹤**：完整記錄每個用戶的對話歷史
* **資料保護**：防止未授權用戶存取敏感資訊

### 2. 三種登入方式 <a href="#login-methods" id="login-methods"></a>

**AD (Active Directory) 登入**

* **適用場景**：企業內部員工使用，整合現有 AD 系統
* **特點**：單一登入 (SSO)，無需額外帳號管理
* **設定方式**：配置 AD 伺服器連線資訊和同步規則
* **實際應用**：員工使用公司帳號直接登入，自動獲得對應權限

**Keycloak 登入**

* **適用場景**：需要複雜身分管理的企業，支援多種身分提供者
* **特點**：支援 OAuth2、SAML、OpenID Connect 等標準協議
* **設定方式**：配置 Keycloak 伺服器、用戶池和身分提供者
* **實際應用**：整合多個系統的用戶身分，統一管理權限
* **延伸**：可讓 Agent 呼叫 MCP／API 工具時沿用訪客的 Keycloak 登入身分，見[沿用 Keycloak 登入身分呼叫工具](#keycloak-token-passthrough)

**MaiAgent 登入**

* **適用場景**：簡單的用戶管理需求，快速部署
* **特點**：內建用戶管理系統，操作簡單直觀
* **設定方式**：在 MaiAgent 平台建立用戶帳號和權限
* **實際應用**：為特定用戶群體建立專屬登入系統
* **訪客自行註冊**：登入頁有 <mark style="color:blue;">立即註冊</mark> 與 <mark style="color:blue;">忘記密碼？</mark>。註冊表單與 MaiAgent 後台的申請帳號相同（真實姓名、公司名稱、公司信箱、密碼、邀請碼），建立的是一個 MaiAgent 平台帳號，可以直接回到登入頁登入 Web Chat；這個帳號不會因此成為您組織的成員，也拿不到後台任何權限。頁面受人機驗證保護，見下方[訪客可能看到的其他提示](#other-visitor-prompts)。

開啟後，開始對話前將出現以下畫面要求登入：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-64de17901f8cb6979d092e523f309cbf98c493d2%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-15%20174017.png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. 沿用 Keycloak 登入身分呼叫工具 <a href="#keycloak-token-passthrough" id="keycloak-token-passthrough"></a>

訪客以 Keycloak 登入 Web Chat 後，Agent 替他呼叫 [MCP 工具](/build/tools/mcp-setup.md)或 [API 工具](/build/tools/setup_api_tool.md)時，可以自動帶上**訪客本人的 Keycloak 登入憑證**。您的後端系統收到請求後，就能用同一套 Keycloak 驗證「這是誰」，只回傳他有權看的資料，不必再替每個工具另外設定帳號或要求訪客再登入一次。

本功能預設關閉；關閉時所有工具的呼叫方式完全不變。

#### 使用情境 <a href="#keycloak-token-passthrough-scenario" id="keycloak-token-passthrough-scenario"></a>

某企業的內部服務入口以 Keycloak 管理員工帳號，並把 Web Chat 當成員工專用的 Agent。IT 管理員在對話平台開啟本功能，把公司的請假系統主機加入允許名單。員工登入 Web Chat 後問「我還剩幾天特休？」，Agent 呼叫請假系統的 API 工具，請求上帶著這位員工自己的登入憑證；請假系統依憑證辨識出是他本人，只回傳他的假勤資料。換另一位員工來問，拿到的就是那位員工自己的資料。

#### 使用前的準備 <a href="#keycloak-token-passthrough-prerequisites" id="keycloak-token-passthrough-prerequisites"></a>

* 組織已完成 [Keycloak 整合](/org/sso/sso-keycloak.md)。訪客須是本組織的成員；透過本組織設定的 Keycloak 首次登入時，系統會自動建立帳號並加入組織（見[第三方登入：首次登入](/org/sso.md#first-login)）。
* 對話平台的 「 <mark style="color:blue;">登入設定</mark> 」 已開啟 「 <mark style="color:blue;">啟用登入功能</mark> 」，且 「 <mark style="color:blue;">登入來源</mark> 」 選擇 Keycloak。
* 要接收憑證的 MCP／API 工具已建立並配置給這個對話平台使用的 Agent；對方系統能驗證您 Keycloak Realm 簽發的憑證。

#### 設定步驟 <a href="#keycloak-token-passthrough-steps" id="keycloak-token-passthrough-steps"></a>

設定位置：左側選單 「 <mark style="color:blue;">客服對話 > 對話平台</mark> 」，選擇網站類型的對話平台，進入 「 <mark style="color:blue;">登入設定</mark> 」 分頁。登入來源選擇 Keycloak 後，下方會出現本區塊。

1. 開啟 「 <mark style="color:blue;">沿用 Keycloak 登入身份呼叫工具</mark> 」。
2. 閱讀開關下方的紅色警語 「 <mark style="color:blue;">會把訪客本人的登入憑證轉發到下列主機</mark> 」，確認您了解憑證的去向。
3. 在 「 <mark style="color:blue;">允許收到憑證的工具主機</mark> 」 填入要接收憑證的工具主機，每行一個（也可用逗號分隔）：
   * 只填主機名稱，不含 `https://`、埠號或路徑，例如 `mcp.example.com`。
   * `*.example.com` 代表 `example.com` 本身及其所有子網域；不加 `*.` 的主機名稱只比對完全相同的主機。
   * 主機名稱依工具的 「MCP 伺服器網址」 或 「API URL」 比對。
4. 儲存設定。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-affd050ebc568fa2c5cad82c542d3f53cefe8493%2Fwebchat-keycloak-token-passthrough.png?alt=media" alt="沿用 Keycloak 登入身分呼叫工具開啟後的警語與允許主機名單"><figcaption><p>開啟後顯示憑證轉發警語，並需填入允許收到憑證的工具主機</p></figcaption></figure>

開啟開關時名單至少要填一個主機；名單為空或含不合法的主機名稱時，畫面會顯示 「 <mark style="color:blue;">開啟後至少要填一個允許收到憑證的工具主機</mark> 」 或 「 <mark style="color:blue;">以下不是有效的主機名稱</mark> 」，設定不會送出。

{% hint style="warning" %}
**開啟後，訪客需要重新登入一次。** 平台只在訪客登入時保存 Keycloak 憑證，且僅限有對話平台開啟本功能時才保存。開啟前就已登入的訪客，請他登出後再登入，之後的工具呼叫才會帶上憑證。
{% endhint %}

#### 對方系統會收到什麼 <a href="#keycloak-token-passthrough-request" id="keycloak-token-passthrough-request"></a>

Agent 呼叫名單內主機的 MCP／API 工具時，請求會多帶一個 HTTP 標頭：

```
Authorization: Bearer <訪客的 Keycloak access token>
```

這是您的 Keycloak Realm 簽發給該訪客的標準 access token，負責整合的工程師可用一般驗證 Keycloak token 的方式（驗簽章、檢查有效期限與 Realm）辨識使用者。憑證過期時，平台會先以該訪客的登入狀態向同一個 Keycloak 續期再送出，工具端不需要處理續期。

#### 什麼情況會帶、什麼情況不帶 <a href="#keycloak-token-passthrough-behavior" id="keycloak-token-passthrough-behavior"></a>

| 情況                                                                                                     | 結果                                         |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| 訪客已以 Keycloak 登入、仍在登入狀態，工具主機在名單內                                                                       | 帶上訪客本人的憑證                                  |
| 工具主機不在名單內                                                                                              | 照常呼叫，不帶憑證                                  |
| 工具本身已設定 `Authorization`（OAuth、API 工具的標頭、[聯絡人 MCP 憑證](/build/tools/setup-contacts-mcp-credentials.md)等） | 不覆蓋，維持工具原本的驗證方式                            |
| 訪客已登出，或不是本組織成員                                                                                         | 不帶憑證                                       |
| 訪客以 [Source ID 免登入](/build/choose-channel/web-chat/source-id-access.md)進入對話                            | 不帶憑證；身分以對話建立時綁定的組織成員為準，不採用嵌入端帶入的 Source ID |
| 開關關閉                                                                                                   | 與未開啟本功能時相同                                 |

{% hint style="danger" %}
轉發的是訪客本人的完整登入憑證，拿到的系統可以用訪客的身分存取同一個 Keycloak 保護的其他服務。名單只放您信任且確實需要辨識使用者的主機，避免使用範圍過大的萬用字元。
{% endhint %}

{% hint style="info" %}
訪客登出時，平台會撤銷已保存的憑證。當同一個 Keycloak 站台已經沒有任何對話平台開啟本功能（關閉開關、改用其他登入來源或刪除對話平台），平台會一併清除所有已保存的訪客憑證。
{% endhint %}

## <mark style="color:blue;">八、資料收集（Pre-chat 表單）</mark> <a href="#pre-chat-form" id="pre-chat-form"></a>

開啟資料收集後，訪客在開始對話前會先看到一張表單，填完才能進入對話。填寫的內容會寫入該訪客的[聯絡人](/serve/daily-operations/contact.md)，客服在對話頁面就能直接看到。適合「先知道對方是誰」的場景，例如經銷商服務要收公司名稱與統一編號、活動諮詢要收姓名與 Email。

### 1. 設定資料收集表單 <a href="#pre-chat-config" id="pre-chat-config"></a>

路徑：<mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">對話平台</mark> → 點選 Web Chat 對話平台 → <mark style="color:blue;">資料收集</mark> 分頁。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fa62f86ab7ff682fcd9c0907a8a126acf6672991%2Fweb-chat-prechat-settings.png?alt=media" alt="資料收集分頁"><figcaption><p>「資料收集」分頁：左側設定開關、標題與欄位，右側「即時預覽」同步顯示表單外觀</p></figcaption></figure>

{% stepper %}
{% step %}

### 開啟表單 <a href="#pre-chat-enable-form" id="pre-chat-enable-form"></a>

打開 <mark style="color:blue;">啟用 Pre-chat 表單</mark>。未啟用時，訪客直接進入對話，維持原本流程。
{% endstep %}

{% step %}

### 設定標題與副標題（選填） <a href="#pre-chat-form-title" id="pre-chat-form-title"></a>

* <mark style="color:blue;">表單標題</mark>：顯示於表單頂端。未填寫時使用系統預設文案「開始對話前的小提問」。
* <mark style="color:blue;">表單副標題</mark>：表單的說明文字，可用 `{name}` 代入對話平台名稱。未填寫時使用預設文案「留下您的資料以便 {name} 提供更個人化的服務」。

兩者都支援多語系，切換語言分頁即可分別填寫。
{% endstep %}

{% step %}

### 新增欄位 <a href="#pre-chat-add-fields" id="pre-chat-add-fields"></a>

點 <mark style="color:blue;">新增欄位</mark>，每個欄位可設定：

| 設定項目                                               | 說明                                                                                                                                                                                                                              |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">欄位類型</mark>              | 文字、Email、電話、下拉選單四種                                                                                                                                                                                                              |
| <mark style="color:blue;">欄位標籤</mark>              | 訪客看到的欄位名稱，可依語系分別填寫                                                                                                                                                                                                              |
| <mark style="color:blue;">提示文字（Placeholder）</mark> | 欄位內的灰色提示                                                                                                                                                                                                                        |
| <mark style="color:blue;">必填</mark>                | 勾選後訪客未填不能送出                                                                                                                                                                                                                     |
| <mark style="color:blue;">對應 Contact 欄位</mark>     | 決定資料寫到聯絡人的哪裡：<mark style="color:blue;">姓名（Contact.name）</mark>、<mark style="color:blue;">Email（Contact.email）</mark>、<mark style="color:blue;">電話（Contact.phoneNumber）</mark>，或 <mark style="color:blue;">自訂欄位（Metadata）</mark> |

下拉選單類型另有 <mark style="color:blue;">選項</mark> 清單，並可勾選 <mark style="color:blue;">允許「其他」自訂輸入</mark>，讓訪客選「其他」後自行輸入內容。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6003c1d8c3373fe2ad0ab3686474f5c2d61d442e%2Fweb-chat-prechat-field-editor.png?alt=media" alt="欄位編輯區"><figcaption><p>每個欄位可設定欄位類型、欄位標籤（多語系）、提示文字、對應 Contact 欄位與必填</p></figcaption></figure>

欄位可拖拉調整順序，一張表單最多 10 個欄位。右側預覽區會即時顯示表單外觀，可切換 <mark style="color:blue;">預覽語系</mark> 檢查各語言版本。
{% endstep %}

{% step %}

### 儲存 <a href="#pre-chat-save-form" id="pre-chat-save-form"></a>

確認預覽無誤後儲存，Web Chat 立即生效。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**對應 Contact 欄位的限制**

* 姓名只能對應「文字」類型、Email 只能對應「Email」類型、電話只能對應「電話」類型，類型不符會顯示禁用提示。
* 姓名、Email、電話各只能被一個表單欄位對應；其餘欄位（例如統一編號、公司名稱）請選「自訂欄位（Metadata）」。
  {% endhint %}

### 2. 訪客填寫流程 <a href="#pre-chat-visitor-flow" id="pre-chat-visitor-flow"></a>

訪客開啟 Web Chat 後，會先看到表單畫面：標題、副標題、您設定的欄位，以及右上角的語言切換。填完後按 <mark style="color:blue;">開始對話</mark> 即進入對話。

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-72d96183b2932a7f3a53fa26e25b0c44693d9976%2Fweb-chat-prechat-form.png?alt=media" alt="訪客看到的表單"><figcaption><p>訪客開啟 Web Chat 先看到表單</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-80e055ba2910bb69258325f5f6f23ee481ba7342%2Fweb-chat-prechat-form-filled.png?alt=media" alt="填寫完成"><figcaption><p>填寫完成後按「開始對話」</p></figcaption></figure></div>

* 必填欄位未填、Email 或電話格式不正確時，欄位下方會顯示錯誤，無法送出。
* 同一個瀏覽器填過一次後，之後再開啟同一個 Web Chat 不會再被要求填寫。
* 訪客想更正資料時，可從 Web Chat 右上角的 <mark style="color:blue;">⋮</mark> 選單點 <mark style="color:blue;">重新填寫資料</mark>，表單會再次出現。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-cc226e66c15e542470c95f0dd2b494f604ad81ec%2Fweb-chat-prechat-menu-refill.png?alt=media" alt="重新填寫資料"><figcaption><p>右上角 ⋮ 選單中的「重新填寫資料」</p></figcaption></figure>

### 3. 搭配登入功能：資料對應登入帳號 <a href="#pre-chat-with-login" id="pre-chat-with-login"></a>

若同一個 Web Chat 同時開啟 [登入功能](#login-config) 與資料收集，流程為：**登入 → 填寫表單 → 開始對話**。使用者填的資料會掛在他的登入帳號上，而不是掛在瀏覽器上。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b190160bed2cd104cb0e87160c4a63c047689a70%2Fweb-chat-prechat-login-settings.png?alt=media" alt="登入設定分頁"><figcaption><p>「登入設定」分頁：開啟「啟用登入功能」並選擇登入來源，與「資料收集」分頁各自獨立</p></figcaption></figure>

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f9c71c232b1bbdd9ee1880cf922a6361d2420e5e%2Fweb-chat-prechat-login-page.png?alt=media" alt="登入畫面"><figcaption><p>① 開啟 Web Chat 先看到登入畫面</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-020c77245a78280ffc81ed879bdb2a9613f3cdeb%2Fweb-chat-prechat-login-form.png?alt=media" alt="登入後的表單"><figcaption><p>② 登入後才出現資料收集表單</p></figcaption></figure></div>

| 情況                                              | Web Chat 的行為             |
| ----------------------------------------------- | ------------------------ |
| 帳號第一次使用，還沒填過表單                                  | 登入後跳出表單；送出後建立一筆對應該帳號的聯絡人 |
| 同一帳號換裝置或換瀏覽器登入                                  | 不再跳出表單，直接以帳號既有的資料開始對話    |
| 這台裝置先前以未登入身分填過，帳號本身還沒有資料                        | 出現「這筆資料是您的嗎？」確認畫面（見下方說明） |
| 帳號已有資料，這台裝置另有一筆未登入時填的資料                         | 以帳號資料為準，不詢問、不合併          |
| 已登入使用者點 <mark style="color:blue;">重新填寫資料</mark> | 更新帳號上既有的那筆聯絡人，不會多出一筆     |

**確認畫面：這筆資料是您的嗎？**

當這台裝置先前有人未登入就填過表單、而目前登入的帳號還沒有資料時，登入後不會直接跳表單，而是先出現確認畫面。畫面會列出這台裝置先前填的內容（部分遮蔽），並提供兩個按鈕：

* <mark style="color:blue;">是，這是我的</mark>：把那筆資料掛到目前的帳號。之後同一帳號在任何裝置登入都不必再填。
* <mark style="color:blue;">不是</mark>：不合併，原本那筆資料維持原狀，接著跳出表單請使用者自行填寫一次。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f8d35bfa6b85a7ec60a08eb8e73cc09904338eb6%2Fweb-chat-prechat-claim.png?alt=media" alt="這筆資料是您的嗎？確認畫面"><figcaption><p>確認畫面會遮蔽部分內容，只讓使用者辨認是否為自己留下的資料</p></figcaption></figure>

{% hint style="info" %}

* 未開啟登入功能的 Web Chat 不受影響，仍以瀏覽器判斷是否填過。
* 系統不會從帳號資料自動帶入表單內容。帳號第一次使用時，即使後台已有他的資料，仍會請他填寫一次。
  {% endhint %}

進入對話後，Agent 與客服後台看到的都是這一筆對應帳號的聯絡人：

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f9a99f4c93d7d3395efb4d6f27175d2469857745%2Fweb-chat-prechat-login-chat.png?alt=media" alt="登入後的對話"><figcaption><p>Agent 以表單填寫的姓名稱呼使用者</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3236973f772f1fb9b44df23cb6812d8c0980bac6%2Fweb-chat-prechat-conversation-login.png?alt=media" alt="後台對話頁"><figcaption><p>後台對話頁顯示該聯絡人與表單收到的統一編號</p></figcaption></figure></div>

### 4. 在後台查看收到的資料 <a href="#pre-chat-view-data" id="pre-chat-view-data"></a>

**在對話中查看**：<mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">所有對話</mark> → 點開對話，右側的 <mark style="color:blue;">聯絡人資料</mark> 區塊會逐項列出表單收到的內容。對應到 Email、電話的欄位顯示為「電子郵件」「電話號碼」，自訂欄位則以您設定的欄位標籤顯示。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-efe6eb93e6c245a6c4dd2e98e793cc07bd69668f%2Fweb-chat-prechat-conversation-contact.png?alt=media" alt="對話頁右側的聯絡人資料區塊"><figcaption><p>對話頁右側「聯絡人資料」逐項列出表單收到的內容</p></figcaption></figure>

{% hint style="info" %}
聯絡人列表的「聯絡人」欄顯示的是 Contact 的姓名。若表單的姓名欄位對應為「自訂欄位（Metadata）」而非「姓名（Contact.name）」，未登入訪客的聯絡人會顯示為「匿名」，姓名只出現在自訂屬性中。想在列表直接看到訪客姓名，請把姓名欄位對應到「姓名（Contact.name）」。
{% endhint %}

**在聯絡人頁查看**：<mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">聯絡人</mark> → 點開聯絡人，<mark style="color:blue;">基本資料</mark> 分頁顯示姓名與電話，<mark style="color:blue;">自訂屬性</mark> 分頁顯示其他表單欄位。

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-45f6d1ebb32ce47284176306f8353e503c88539c%2Fweb-chat-prechat-contacts-list.png?alt=media" alt="聯絡人列表"><figcaption><p>聯絡人列表可用姓名、Email 或電話搜尋</p></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-9bc3a0bf13c97c7eed1f5223b76a9bca113962f5%2Fweb-chat-prechat-contact-attributes.png?alt=media" alt="自訂屬性分頁"><figcaption><p>「自訂屬性」分頁列出表單每個欄位的值</p></figcaption></figure></div>

已登入使用者填的資料會對應到他的帳號，不再是無主的匿名聯絡人。聯絡人名稱依表單設定而定：姓名欄位有對應「姓名（Contact.name）」時顯示表單填的姓名；沒有姓名欄位時顯示登入帳號的名稱。

## 訪客可能看到的其他提示 <a href="#other-visitor-prompts" id="other-visitor-prompts"></a>

以下是對話中偶爾出現、但不需要管理員設定的提示，整理在這裡方便回答訪客的疑問：

| 畫面                                                              | 什麼時候出現                                                                                                                                           | 怎麼處理                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| 登入、註冊與重設密碼頁的人機驗證方塊；「操作過於頻繁，請稍後再試。」                              | 開啟登入功能的 Web Chat 會在這三個頁面加上 Cloudflare Turnstile 驗證；短時間內送出太多請求（例如連續開新對話或傳訊息）會被頻率限制擋下                                                              | 等驗證方塊打勾後再送出；被限制時稍等再試                                                                |
| 底部面板「安裝 {App 名稱} App」                                           | 用手機瀏覽器開啟獨立全螢幕頁時，可以把 Web Chat 加到主畫面當 App 用。Android 顯示 <mark style="color:blue;">立即安裝</mark>；iPhone 的 Safari 顯示「加入主畫面」步驟，其他 iPhone 瀏覽器會建議改用 Safari | 不想安裝就按 <mark style="color:blue;">下次提醒</mark>，一天內不會再出現；已經安裝成 App 開啟時不會顯示             |
| 「內容過長（共 N 字元），已改為純文字顯示」＋<mark style="color:blue;">顯示完整內容</mark> | 單則回覆超過 50,000 字元（或單行超過 2,000 字元）時，不再套用 Markdown 排版，先顯示前 2,000 字                                                                                  | 按 <mark style="color:blue;">顯示完整內容</mark> 展開，<mark style="color:blue;">收合</mark> 收回 |
| 「內容過大（共 N 字元），僅顯示前段」                                            | 工具回傳的 JSON 資料過大                                                                                                                                  | 只是畫面截斷，Agent 已拿到完整資料                                                                |
| 「較早的長訊息已部分省略（共約 N 字），助理可能沒看到完整內容」                               | 對話很長時，系統為了控制上下文長度省略了較早的長訊息                                                                                                                       | 需要 Agent 參考那段內容時重新貼上相關段落；也可用 [整理交接](/work/maigpt/chat/conversation-handoff.md) 開新對話 |
| 回覆旁的小標籤「此回覆由團隊成員「{名稱}」產出」                                       | Agent 屬於 [Agent 團隊](/build/teams.md)，這一則是由團隊中的某個成員 Agent 回答                                                                                      | 無需處理                                                                                |
| 「正在委派給／正在移交給／正在切換至 {Agent}」、子代理任務卡                              | 多 Agent 協作時，主 Agent 把任務交給子代理執行                                                                                                                   | 卡片會顯示回覆中／已完成，等它完成即可                                                                 |
| 「正在定位...」「無法取得您的位置，請在設定中開啟定位權限」「已成功取得位置」                        | 管理員開啟了[位置資訊](/build/conversation-settings/platform-settings/function-settings.md#gps-location)，瀏覽器會詢問定位授權                                        | 允許定位後再送出；拒絕時 Agent 仍會回答，只是沒有位置資訊                                                    |
| 「連接 {服務}」授權卡                                                    | Agent 需要用訪客自己的帳號存取外部服務                                                                                                                           | 見[已連接的服務](/build/choose-channel/web-chat/connected-services.md)                     |
| 影片生成卡（排隊中／生成中／預計需要 60–90 秒）                                     | Agent 使用影片生成工具                                                                                                                                   | 等待完成即可，說明見 [AI 影片生成](/work/maigpt/video.md)                                         |

## 連線失敗時如何處理？ <a href="#connection-failure" id="connection-failure"></a>

例如，網站管理員收到訪客回報，表示 Web Chat 開啟時顯示無法連線。訪客先等待系統自動重試；若錯誤畫面仍出現，就擷取包含失敗階段、錯誤分類與發生時間的完整畫面交給管理員，讓管理員能更快判斷問題。

Web Chat 載入 Agent 設定時若遇到網路中斷，會先自動重試，這段時間畫面會維持載入狀態。若重試後仍無法連線，錯誤畫面會顯示：

* 失敗的載入階段
* 錯誤分類，有 HTTP 狀態碼時一併顯示
* 錯誤發生的當地時間

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e24edbd1a83fd7f69430443a8a74158aeb6a117b%2Fweb-chat-connection-failure-network.png?alt=media" alt="Web Chat 顯示載入 Agent 設定階段的網路連線失敗診斷"><figcaption><p>自動重試仍失敗後，畫面會列出失敗階段、錯誤分類與發生時間</p></figcaption></figure>

若系統已收到 HTTP 錯誤狀態碼，代表伺服器已回應；此時不會進行自動重試，而會直接顯示診斷錯誤畫面。

{% hint style="info" %}
請先確認裝置可正常上網，再按錯誤畫面的<mark style="color:blue;">重試</mark>。若問題持續，擷圖時請保留完整診斷資訊，並避免畫面中出現對話內容或個人資料。
{% endhint %}

## 生成回覆時回看前文 <a href="#review-during-generation" id="review-during-generation"></a>

Agent 還在產生回覆時，訪客可以直接向上捲動回看前面的訊息。回覆會繼續在下方產生，但畫面會停在訪客捲到的位置，不會被新出現的文字拉走；一旦離開最新進度，輸入框上方就會出現<mark style="color:blue;">回到最新</mark>。

### 使用情境 <a href="#generation-scroll-scenario" id="generation-scroll-scenario"></a>

訪客請 Agent 一次比較多個方案。回答還沒寫完，她想先回頭核對第一個方案的價格，於是向上捲動——畫面停在原處，不會因為後面的文字一直冒出來而跳走。核對完之後她按<mark style="color:blue;">回到最新</mark>，畫面回到最後一則提問的位置，繼續看剩下的比較內容。

### 操作方式 <a href="#generation-scroll-steps" id="generation-scroll-steps"></a>

{% stepper %}
{% step %}

### 1. 向上捲動 <a href="#scroll-up-during-generation" id="scroll-up-during-generation"></a>

在 Agent 產生回覆期間，用滑鼠滾輪、觸控手勢或拖曳捲軸向上捲動。
{% endstep %}

{% step %}

### 2. 在原地閱讀 <a href="#read-in-place" id="read-in-place"></a>

畫面會停在你捲到的位置，生成中的新內容不會改變目前的位置。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-537d8652530560963f91fe83d44727c547068051%2Fwebchat-back-to-latest.png?alt=media" alt="Web Chat 回覆生成期間向上捲動，輸入框上方顯示「回到最新」"><figcaption><p>回覆仍在生成（輸入框右側為方形停止按鈕），向上捲動後輸入框上方出現「回到最新」</p></figcaption></figure>
{% endstep %}

{% step %}

### 3. 回到最新 <a href="#press-back-to-latest" id="press-back-to-latest"></a>

按<mark style="color:blue;">回到最新</mark>，畫面會回到最後一則提問的位置，並恢復自動跟隨最新內容。
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/choose-channel/web-chat.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.