基本設定

網頁對話平台的基本設定：平台名稱、綁定的 Agent、返回地址、自訂域名、允許嵌入的網域、公開訪問 URL 與三種嵌入方式，以及 API 平台的 Web Chat ID 在哪裡。

基本設定 是對話平台設定頁「一般」群組的第一個分類，決定這個平台「叫什麼、接哪個 Agent、從哪個網址提供服務」。本頁說明網頁平台的所有欄位；LINE、Microsoft Teams 等通訊平台的基本設定是該平台的憑證欄位，請見對應的「串接對話平台」頁面。設定頁的整體結構與進入方式請見對話平台設定總覽。

方案導覽：本頁是對話平台設定的其中一步，文字客服的完整上線流程見 文字客服：從零到上線；語音客服見 語音客服：從零到上線。

一、什麼時候會用到

行銷人員要把公司的 AI 客服掛上官網。她進入網頁平台的 基本設定，把名稱改成「客服小幫手」、確認綁定的是「產品諮詢助理」，在 返回地址 填上官網首頁，再到 允許嵌入的網域 加入 *.my-company.com，儲存後點 嵌入 複製 JavaScript 程式碼交給網站工程師。上線後只有公司自己的網站能載入這個客服，其他人複製程式碼也無法使用。

二、欄位說明

網頁平台的基本設定

欄位	說明
名稱	對話視窗標題列顯示的名稱，例如「客服小幫手」；必填
描述	簡短介紹這個 Agent 能幫什麼忙（最多 100 字），會顯示在 Agent 市集「組織自建」分頁的 Agent 卡片與分享連結預覽；留空時卡片顯示預設文案。網站與內部對話平台有此欄位，API 平台沒有
AI 助理	這個平台由哪一個 Agent 回答；同一個 Agent 可以接多個平台
返回地址	使用者在對話視窗點返回時前往的網址，通常填官網首頁
自訂域名 (CNAME)	用您自己的網域提供對話頁面，見第三節
允許嵌入的網域	嵌入白名單，見第四節
公開訪問URL	系統自動產生的對話頁網址，可直接分享或嵌入，見第五節

名稱與 Agent

在 名稱 輸入您希望在網站上顯示的名稱，在 AI 助理 下拉選單選擇要回答問題的 Agent。切換 Agent 後立即生效，對話視窗不需要重新嵌入。

平台名稱顯示在對話視窗的標題列

返回地址

填入公司網站網址後，使用者在全螢幕的對話頁點返回時會跳到這個網址；嵌入預覽時也會以這個網址當作背景。

加入返回地址後，嵌入預覽會以該網站作為背景

三、自訂域名 (CNAME)

預設的公開訪問網址在 chat.maiagent.ai 底下。若希望對話頁改用您自己的網域（例如 chat.my-company.com），在 自訂域名 (CNAME) 填入該網域並儲存，系統會為它申請憑證並建立分流。儲存後欄位旁會顯示 域名狀態：

狀態	意思	要做什麼
檢查中	系統正在建立分流與憑證	等待幾分鐘後重新整理
DNS 未就緒	您的 DNS 尚未把該網域指向 MaiAgent	到 DNS 服務商新增 CNAME 紀錄
憑證未就緒	DNS 已指向，憑證仍在簽發	等待，通常數分鐘內完成
DNS 設定異常	曾經啟用，但 DNS 紀錄已被改掉或移除	檢查 DNS 服務商的 CNAME 紀錄
已啟用	對話頁已可用您的網域開啟	公開訪問網址與嵌入程式碼會改用您的網域

CNAME 紀錄要指向的目標位址依環境不同，請向支援中心索取。清空欄位並儲存即可移除自訂域名，對話頁回到預設網址。

四、允許嵌入的網域

這是什麼？

允許嵌入的網域 是一份「嵌入白名單」：填入後，只有清單上的網站能嵌入此網頁聊天，其他網站放置的嵌入程式碼會失效。

適合啟用的情境：

• 防止盜嵌：擔心第三方網站複製您的嵌入程式碼、把您的客服機器人嵌到他們的頁面上，消耗您的對話額度

• 資安合規：公司或客戶的資安政策要求列管「哪些網站可以載入此客服元件」

這是進階安全設定，沒有上述需求時，維持空清單即可。清單為空：任何網站都可以嵌入此網頁聊天。

運作方式

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

• 被擋的網域嵌入時：該頁面上的聊天元件不會完成初始化，訪客無法開始對話

• 直接開啟公開訪問 URL 的訪客：此設定只限制「嵌入」，透過公開網址直接開啟聊天頁的訪客不受影響

• 安全機制採「無法驗證即拒絕」：清單非空時，凡是無法通過來源驗證的嵌入一律被拒，包括網域打錯字、或嵌入頁使用了不支援來源驗證的舊版嵌入腳本

設定步驟

1

找到欄位

在 基本設定 找到 允許嵌入的網域，點 ＋ 新增。

基本設定中的「允許嵌入的網域」欄位

2

新增網域

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

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

3

儲存並確認

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

已填入精確來源與萬用網域的清單範例

啟用前檢查清單

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

1. 列出所有會嵌入此網頁聊天的網域：包含正式站、測試環境、預覽環境，一個都不能漏

2. 重新取得最新的嵌入程式碼：較早期取得的嵌入腳本可能不支援來源驗證，啟用清單後會一律被拒絕；建議先到 嵌入 重新複製一份，更新到您的網站

3. 先加不刪：第一次啟用時把所有網域加齊，不要邊啟用邊清理

4. 逐一驗證：儲存後到每個嵌入頁實際開啟一次對話，確認都正常

5. 保留退路：若啟用後嵌入端無法建立對話，清空清單並儲存；等待約一分鐘後，即可恢復為不限制

常見問題

Q：設定後多久生效？

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

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

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

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

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

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

清空 允許嵌入的網域 清單並儲存；等待約一分鐘後即可恢復為不限制，再重新檢查網域寫法。

五、公開訪問 URL 與嵌入

頁面下方的 公開訪問URL 是系統自動產生的對話頁網址，旁邊的動作按鈕：

動作	用途
複製	複製網址，可直接分享給使用者或放在 QR Code
訪問	在新分頁開啟對話頁，測試設定效果
語音模式	在新分頁開啟語音對話頁；只有綁定的 Agent 已啟用語音助理時才會出現，上線流程見語音客服：從零到上線
嵌入	取得嵌入程式碼，見下方三種嵌入方式
嵌入預覽	以返回地址的網站為背景，預覽嵌入後的樣子

三種嵌入方式

點 嵌入 後，可在視窗上方切換：

• JavaScript：以 <script> 載入，最常用，會自動處理載入與相容性

• Iframe：以 <iframe> 直接嵌入，適合無法插入腳本的環境

• MaiGPT：ChatGPT 風格的完整對話介面（左側對話歷史＋右側主對話區），可常駐嵌入頁面，或以右下角浮動按鈕點擊後全螢幕展開

選擇 MaiGPT 後，可在左側調整 嵌入容器（targetElement）、語系（locale）、標題（maigptTitle），右側 程式碼預覽 會即時更新，點 複製 即可貼到您的網站。完整參數說明請見 MaiGPT 視窗模式嵌入。

嵌入腳本的特性

JavaScript 嵌入提供的 embed.js 腳本具備：

• 防重複執行：即使腳本被多次載入，也只會初始化一次

• 清楚的錯誤訊息：載入失敗時提供錯誤訊息方便除錯

• 不影響網站載入速度：腳本經過最佳化

• 相容各種網站環境與框架

嵌入時建議：

1. 將嵌入腳本放在 </body> 標籤之前，確保頁面主要內容先載入

2. 只在頁面中加入一次嵌入腳本，避免重複

3. 在 SPA（Single Page Application）中使用時，請參考技術文件的進階設定

嵌入預覽

六、API 平台的 Web Chat ID

工程師用 API 建立對話時，必填欄位 webChat 要填的是 API 平台的 Web Chat ID。它不在 Agent 詳細頁，而是在 API 平台的設定頁：

1. 前往 客服對話 → 對話平台，找到該 Agent 的 API 平台（建立 Agent 時自動產生），點選 編輯。

2. 在左側分類導覽的「串接與登入」群組點選 Webhook 設定。

3. 頁面下方的 API 資訊 卡顯示 Web Chat ID（唯讀），點右側的複製按鈕即可複製。

這張卡只有 API 平台才有；網頁、內部平台沒有 Web Chat ID 欄位。要查整個組織的 Web Chat 清單與 ID，工程師也可以呼叫 GET /api/v1/web-chats/，詳見技術手冊 建立對話與訊息。

七、常見問題

Q：改了名稱或 Agent，要重新嵌入嗎？

不用。按 儲存 後立即生效，嵌入程式碼不變。

Q：同一個 Agent 可以接多個網頁平台嗎？

可以。每個平台有自己的名稱、外觀與功能開關，適合同一個 Agent 在不同網站呈現不同樣貌。從 客服對話 → 對話平台 點 串接對話平台 新增即可。