> 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/conversations/web-chat/website.md).

# 串接對話平台：網站

## <mark style="color:blue;">一、進入設定頁面</mark> <a href="#navigate-to-settings" id="navigate-to-settings"></a>

### 1. 路徑一：新增網頁客服對話 <a href="#path-add-web-chat" id="path-add-web-chat"></a>

點擊左側選單 「 <mark style="color:blue;">客服對話 > 對話平台</mark>」 ，點選右上角的 「<mark style="color:blue;">＋串接對話平台</mark>」，選擇平台 「 <mark style="color:blue;">Website</mark> 」

### 2. 路徑二：AI 助理關聯對話平台 <a href="#path-ai-agent-link-channel" id="path-ai-agent-link-channel"></a>

進入左側功能欄的 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">AI 助理</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-b8489ca6969c2a5473b72ee019bf07d539d1ca45%2Fai-agent-channel-platform-settings-prod.png?alt=media" alt="AI 助理的對話平台分頁，每張平台卡片都有平台設定按鈕"><figcaption><p>從 AI 助理的對話平台分頁點選「平台設定」。</p></figcaption></figure>

完成設定後，點選頁面上方的 <mark style="color:blue;">返回 AI 助理設定</mark>，即可回到原助理的 <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-9dc1869d16658968ef1f594d157bd5045fda1b3c%2Finbox-back-to-ai-agent-settings-prod.png?alt=media" alt="對話平台設定頁上方的返回 AI 助理設定按鈕"><figcaption><p>設定完成後，可直接返回原本的 AI 助理設定頁。</p></figcaption></figure>

{% hint style="info" %}
只有從 AI 助理的 <mark style="color:blue;">對話平台</mark>分頁進入時，才會顯示 <mark style="color:blue;">返回 AI 助理設定</mark>。若是從左側選單的 <mark style="color:blue;">對話平台</mark>直接進入，頁面維持原本的導覽方式。
{% endhint %}

#### 使用情境：調整網站客服後回到助理 <a href="#scenario-return-to-agent" id="scenario-return-to-agent"></a>

客服主管要為「產品諮詢助理」更新網站客服設定。她在這隻 AI 助理的 <mark style="color:blue;">對話平台</mark>分頁點選 <mark style="color:blue;">平台設定</mark>，完成調整後點選 <mark style="color:blue;">返回 AI 助理設定</mark>，回到同一隻助理的對話平台清單，繼續檢查其他客服入口，不需要再從 AI 助理清單重新尋找。

### 3. 路徑三：對話平台操作 <a href="#path-channel-management" id="path-channel-management"></a>

左側功能欄中的 「 <mark style="color:blue;">客服對話 > 對話平台</mark> 」，選擇您想要設定之 AI 助理，點選 「 <mark style="color:blue;">操作</mark> 」 圖示即可進入對話平台配置。

## <mark style="color:blue;">二、基本設定</mark> <a href="#basic-settings" id="basic-settings"></a>

### 1. 基本設定 <a href="#general-settings" id="general-settings"></a>

**設定平台名稱**

* 在 「 <mark style="color:blue;">平台名稱</mark> 」 欄位輸入您希望在網站上顯示的 AI 助理名稱
* 例如：「 客服小幫手 」、「 智能助理 」等

**選擇 AI 助理**

* 在 「 <mark style="color:blue;">AI 助理</mark> 」 下拉選單中選擇要使用的 AI 助理
* 這會決定聊天室使用哪一個 AI 助理 來回答問題

**設定返回網址**

* 在 「 <mark style="color:blue;">返回網址</mark> 」 欄位輸入您的公司網站網址
* 當用戶點擊聊天室的返回按鈕時，會跳轉到這個網址

**取得並使用公開網址**

* 系統會自動生成一個 「 <mark style="color:blue;">公開訪問URL</mark> 」
* 您可以：
  * 點擊 「 <mark style="color:blue;">複製</mark> 」 按鈕複製網址
  * 點擊 「 <mark style="color:blue;">訪問</mark> 」 按鈕在新視窗開啟聊天室
  * 點擊 「 <mark style="color:blue;">嵌入</mark> 」 按鈕取得嵌入程式碼
  * 點擊 「 <mark style="color:blue;">嵌入預覽</mark> 」 按鈕預覽嵌入效果

**嵌入腳本優化**

當您選擇嵌入方式時，系統會提供優化過的 embed.js 腳本，具備以下特點：

* **防重複執行機制**：即使腳本被多次載入，也只會初始化一次，避免衝突
* **更好的錯誤處理**：當載入失敗時，會提供清楚的錯誤訊息，方便除錯
* **優化載入效能**：腳本經過最佳化，不會影響網站載入速度
* **相容性提升**：與各種網站環境和框架更加相容

**嵌入最佳實踐：**

1. 將嵌入腳本放在 `</body>` 標籤之前，確保頁面主要內容先載入
2. 只在頁面中加入一次嵌入腳本，避免重複
3. 如需在 SPA（Single Page Application）中使用，請參考技術文檔的進階設定

**選擇嵌入方式**

點擊 「 <mark style="color:blue;">嵌入</mark> 」 後，可在視窗上方切換三種嵌入方式：

* **JavaScript**：以 `<script>` 載入，最常用，會自動處理載入與相容性
* **Iframe**：以 `<iframe>` 直接嵌入，適合無法插入腳本的環境
* **MaiGPT**：ChatGPT 風格的完整對話介面（左側對話歷史 + 右側主對話區），可常駐嵌入頁面，或以右下角浮動按鈕點擊後全屏展開

選擇 <mark style="color:blue;">MaiGPT</mark> 後，可在左側調整 「 <mark style="color:blue;">嵌入容器（targetElement）</mark> 」、「 <mark style="color:blue;">語系（locale）</mark> 」、「 <mark style="color:blue;">標題（maigptTitle）</mark> 」，右側 <mark style="color:blue;">程式碼預覽</mark> 會即時更新，點擊 「 <mark style="color:blue;">複製</mark> 」 即可貼到您的網站。

{% hint style="info" %}
MaiGPT 視窗模式的完整設定與參數說明，請見 [MaiGPT 視窗模式嵌入](/conversations/web-chat/maigpt-embed.md)。
{% endhint %}

#### 允許嵌入的網域 <a href="#allowed-embed-origins" id="allowed-embed-origins"></a>

**這是什麼？**

基本設定中的 「 <mark style="color:blue;">允許嵌入的網域</mark> 」 是一份「嵌入白名單」：填入後，只有清單上的網站能嵌入此網頁聊天，其他網站放置的嵌入程式碼會失效。

適合啟用的情境：

* **防止盜嵌**：擔心第三方網站複製您的嵌入程式碼、把您的客服機器人嵌到他們的頁面上，消耗您的對話額度
* **資安合規**：公司或客戶的資安政策要求列管「哪些網站可以載入此客服元件」

{% hint style="info" %}
這是進階安全設定，**沒有上述需求時，維持空清單即可**——清單為空：任何網站都可以嵌入此網頁聊天。
{% endhint %}

**運作方式**

| 清單狀態  | 行為                                     |
| ----- | -------------------------------------- |
| 空（預設） | 不限制，任何網站都可以嵌入此網頁聊天                     |
| 非空    | 白名單模式：瀏覽器會擋掉其他網域的嵌入，SDK 也會拒絕其 setup 呼叫 |

* **被擋的網域嵌入時**：該頁面上的聊天元件不會完成初始化，訪客無法開始對話
* **直接開啟公開訪問 URL 的訪客**：此設定只限制「嵌入」，透過公開網址直接開啟聊天頁的訪客不受影響
* **安全機制採「無法驗證即拒絕」**：清單非空時，凡是無法通過來源驗證的嵌入一律被拒——包括網域打錯字、或嵌入頁使用了不支援來源驗證的舊版嵌入腳本

**設定步驟**

{% stepper %}
{% step %}

### 進入基本設定 <a href="#embed-origins-step-navigate" id="embed-origins-step-navigate"></a>

點擊左側選單 「 <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-2c6dc13d0e37a07d6f539d493f1e1493d018dcfb%2Fwebchat-basic-allowed-origins.png?alt=media" alt="基本設定中的「允許嵌入的網域」欄位"><figcaption><p>基本設定中的「允許嵌入的網域」欄位</p></figcaption></figure>
{% endstep %}

{% step %}

### 新增網域 <a href="#embed-origins-step-add" id="embed-origins-step-add"></a>

每一筆可以是精確來源（`https://example.com`），或萬用網域（`*.example.com`，同時比對 example.com 及其所有子網域）。

| 寫法                          | 說明                                            |
| --------------------------- | --------------------------------------------- |
| ✅ `https://www.example.com` | 精確來源：只允許這個網址（含通訊協定）的頁面嵌入                      |
| ✅ `*.example.com`           | 萬用網域：允許 example.com 及其所有子網域（www、shop、blog⋯）嵌入 |
| ❌ `example.com`             | 精確來源必須包含通訊協定，缺少 `https://` 不會生效               |
| ❌ `*.com`                   | 範圍過寬，等於對所有 .com 網站開放，失去白名單意義                  |
| {% endstep %}               |                                               |

{% step %}

### 儲存並確認 <a href="#embed-origins-step-save" id="embed-origins-step-save"></a>

儲存設定後等待約一分鐘，再到清單上的網站重新整理嵌入頁，確認聊天視窗仍可正常開啟對話。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-856c495d2fb9896943ac455178eed55a38f15a0e%2Fembed-origins-01-filled-list.png?alt=media" alt="已填入網域清單的「允許嵌入的網域」欄位"><figcaption><p>已填入精確來源與萬用網域的清單範例</p></figcaption></figure>
{% endstep %}
{% endstepper %}

**啟用前檢查清單**

{% hint style="warning" %}
清單一旦非空，就會擋掉所有不在清單上的嵌入。為避免「一填就全部被擋」，啟用前請依序確認：

1. **列出所有會嵌入此網頁聊天的網域**——包含正式站、測試環境、預覽環境，一個都不能漏
2. **重新取得最新的嵌入程式碼**——較早期取得的嵌入腳本可能不支援來源驗證，啟用清單後會一律被拒絕；建議先到 「 <mark style="color:blue;">嵌入</mark> 」 重新複製一份，更新到您的網站
3. **先加不刪**：第一次啟用時把所有網域加齊，不要邊啟用邊清理
4. **逐一驗證**：儲存後到每個嵌入頁實際開啟一次對話，確認都正常
5. **保留退路**：若啟用後嵌入端無法建立對話，清空清單並儲存；等待約一分鐘後，即可恢復為不限制
   {% endhint %}

**常見問題**

**Q：設定後多久生效？**

儲存後通常約一分鐘內生效；之後重新整理已開啟的嵌入頁面，即會套用新設定。

**Q：子網域很多，要逐一列出嗎？**

不用。一筆 `*.example.com` 就會同時比對 example.com 及其所有子網域。

**Q：這個設定能防住什麼、防不住什麼？**

這是「嵌入層」的防護：能防止其他網站把此網頁聊天嵌入他們的頁面。它不是身分驗證——知道公開訪問 URL 的人仍然可以直接開啟聊天頁對話；若需要控管「誰能對話」，請搭配 [登入設定](#login-settings) 使用。

**Q：設定錯了，所有嵌入端都無法對話怎麼辦？**

清空 「 <mark style="color:blue;">允許嵌入的網域</mark> 」 清單並儲存；等待約一分鐘後即可恢復為不限制，再重新檢查網域寫法。

### 2. 外觀設定 <a href="#appearance-settings" id="appearance-settings"></a>

**上傳企業 Logo**

* 點擊 「 <mark style="color:blue;">Logo</mark> 」 區域的上傳按鈕
* 選擇您的企業標誌圖片檔案
* 上傳後會顯示預覽，可點擊刪除重新上傳

**上傳 AI 助理頭像**

* 點擊 「 <mark style="color:blue;">大頭貼</mark> 」 區域的上傳按鈕
* 選擇適合的頭像圖片
* 上傳後會顯示預覽，可點擊刪除重新上傳

**設定顏色主題**

* 點擊 「 <mark style="color:blue;">主題色</mark> 」 選擇器，選擇聊天室視窗標題的顏色
* 點擊 「 <mark style="color:blue;">標題字顏色</mark> 」 選擇器，設定標題文字顏色
* 點擊 「 <mark style="color:blue;">AI 助理回答背景色</mark> 」 選擇器，設定 AI 回覆訊息的背景顏色

**啟用主題切換**

* 將 「 <mark style="color:blue;">主題模式切換</mark> 」 開關切換為開啟狀態
* 用戶可以在淺色和深色主題間切換

### 3. 功能設定 <a href="#feature-settings" id="feature-settings"></a>

**設定是否啟用**

* 設定對話是否開啟提供服務使用

**設定檔案上傳**

* 將 「 <mark style="color:blue;">允許檔案上傳</mark> 」 開關切換為開啟狀態
* 用戶就可以上傳檔案給 AI 分析，如：圖片、檔案等

**設定引用文件顯示**

* 將 「 <mark style="color:blue;">顯示引用文件</mark> 」 開關切換為開啟狀態
* AI 回答時會顯示參考的來源文件

**設定允許下載引用文件**

* 將 「 <mark style="color:blue;">允許下載引用文件</mark> 」 開關切換為開啟狀態
* 使用者即可下載對話中 AI 助理所引用的檔案內容

**設定顯示使用工具及結果**

* 將 「 <mark style="color:blue;">顯示使用工具及結果</mark> 」 開關切換為開啟狀態
* 系統將標示正在透過 MCP 或 API 作業處理中

### 4. 互動設定 <a href="#interaction-settings" id="interaction-settings"></a>

**設定開場白**

* 在開場白輸入框中輸入歡迎訊息
* 例如：「您好！我是您的智能客服，有什麼可以幫助您的嗎？」
* 點擊 「 <mark style="color:blue;">新增</mark> 」 按鈕將開場白加入列表
* 可以新增多個開場白，系統會隨機選擇
* 如需刪除，點擊對應項目右側刪除按鈕

**設定對話開始問題**

* 在「對話開始問題」輸入框中輸入預設問題
* 例如：「如何申請退貨？」、「營業時間是什麼？」
* 點擊 「 <mark style="color:blue;">新增</mark> 」 按鈕將問題加入列表
* 這些問題會顯示為快速選項供用戶點擊
* 如需刪除，點擊對應項目右側刪除按鈕

**開場白選項納入 Agent 上下文**

在「對話開始問題」下方有一個 「 <mark style="color:blue;">開場白選項納入 Agent 上下文</mark> 」 開關（預設關閉）。開啟後，系統會將開場白本文與**編號化的選項清單**提供給 AI，讓使用者以數字或簡短字詞回覆選項時也能被辨識。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a752fbae4a5de93e8c75ae503fb7eb0d927e12d0%2Finteraction-greeting-context-toggle.png?alt=media" alt="互動設定中的「開場白選項納入 Agent 上下文」開關"><figcaption><p>互動設定中的「開場白選項納入 Agent 上下文」開關</p></figcaption></figure>

#### 開啟前後差異 <a href="#greeting-context-comparison" id="greeting-context-comparison"></a>

以航空客服為例：開場白設定為「請問需要什麼協助？」，對話開始問題依序設定「航班查詢」「行李規定」「會員里程」。開啟後，系統會依順序自動加上編號；訪客只輸入 「2」：

| 項目       | 未開啟（預設）                          | 開啟後                      |
| -------- | -------------------------------- | ------------------------ |
| 訪客看到的畫面  | 開場白＋隨機挑選的部分起始問題                  | 開場白＋**依設定順序完整顯示**的全部起始問題 |
| AI 取得的資訊 | 只有開場白本文，沒有選項清單                   | 開場白本文＋編號化的選項清單           |
| 訪客回覆「2」時 | AI 不知道「2」對應哪個選項，可能反問「請問您想詢問什麼呢？」 | AI 理解「2」＝行李規定，直接回覆行李規定說明 |
| 起始問題顯示行為 | 隨機洗牌，受「隨機顯示則數」限制                 | 依序全部顯示，「隨機顯示則數」設定不生效     |

#### 適用情境範例 <a href="#greeting-context-use-cases" id="greeting-context-use-cases"></a>

只要您用開場白搭配多個「對話開始問題」形成選單式引導，讓訪客從固定服務項目中挑選，就適合開啟此功能：

* **金融／銀行**：開場白使用「歡迎使用線上客服，請選擇服務項目」，並將「帳戶餘額查詢」「信用卡申辦進度」「保單查詢」「轉接專人」分別設為對話開始問題。客戶回「3」，AI 直接進入保單查詢流程
* **醫療／診所**：開場白使用「您好，請問需要哪項服務？」，並將「門診時段查詢」「預約掛號」「看診進度」「衛教資訊」分別設為對話開始問題。民眾回「掛號」這類簡短字詞，AI 也能對應到選項 2
* **政府／公部門**：開場白使用「請選擇要申辦的項目」，並將「補助申請」「活動報名」「服務據點查詢」分別設為對話開始問題。市民回「1」，AI 接續詢問要申請的補助類別

#### 何時建議開啟 <a href="#greeting-context-when-to-enable" id="greeting-context-when-to-enable"></a>

| 您的引導方式                                              | 建議                  |
| --------------------------------------------------- | ------------------- |
| **選單式引導**：已設定多個「對話開始問題」，希望訪客用系統顯示的編號或簡短字詞回覆、走固定流程   | ✅ 建議開啟              |
| **自由對話型**：只有一般問候語（如「您好！有什麼可以幫助您的嗎？」），沒有設定「對話開始問題」選項 | ❌ 不需開啟，可節省 Token 成本 |

#### 開啟後的注意事項 <a href="#greeting-context-side-effects" id="greeting-context-side-effects"></a>

1. **「隨機顯示則數」設定失效**：為確保訪客看到的編號與 AI 理解的編號一致，開啟後對話開始問題**不再隨機洗牌、也不受顯示數量限制**，一律依設定順序全部顯示。若您原本依賴「對話開始問題」的 「 <mark style="color:blue;">隨機顯示則數</mark> 」 設定控制版面，開啟前請先確認起始問題數量適中
2. **Token 成本增加**：開啟後畫面會出現黃色警告，提醒此功能會增加每次請求的上下文長度（token 成本）。選項越多，增加的成本越明顯，請視需求開啟

{% hint style="info" %}
未開啟時行為與過去相同：AI 仍看得到開場白本文，但不會取得編號化的選項清單，使用者僅回覆「1」時 AI 可能無法對應到選項。
{% endhint %}

### 5. 登入設定 <a href="#login-settings" id="login-settings"></a>

**設定 SSO 登入來源**

* MaiAgent 目前支援透過 Keycloak 整合實現 SSO（Single Sign-On）服務
* 於 「 <mark style="color:blue;">登入來源</mark> 」 下拉選單中進行切換
* 選擇使用 Maiagent 或 Keycloak 作為身份驗證方式

**嵌入端免登入對話**

若您把 Web Chat 嵌入自家網站，且使用者已在您的網站登入過，可開啟 「 <mark style="color:blue;">允許嵌入端以 Source ID 免登入對話</mark> 」 讓他們直接對話。設定方式與簽章串接說明請見 [以聯絡人 Source ID 免登入對話](/conversations/web-chat/source-id-access.md)。

## <mark style="color:blue;">三、自動回覆設定</mark> <a href="#auto-reply-settings" id="auto-reply-settings"></a>

您可以在此設定機器人回覆時間段。

* 點選日期旁的開關鈕：選定一周中的哪幾天回覆。
* 設定時段：選定開始的時間與結束的時間。
* 新增時段：如果有多個時段要設定，可按下 「 <mark style="color:blue;">+新增時段</mark> 」 來新增，並設定時段。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/conversations/web-chat/website.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.