MaiGPT 視窗模式嵌入
以 MaiGPT 視窗模式將 ChatGPT 風格的完整對話介面直接嵌入您的網站，並可開放深度研究與工具開關。
除了常見的「右下角浮動按鈕」外，MaiAgent 的 Web Chat SDK 新增了 MaiGPT 視窗模式，讓您可以把一個 ChatGPT 風格的完整對話介面（左側對話歷史列表 + 右側主對話區）直接嵌入到自家頁面的任意位置，做為頁面的主要 UI，而不是縮在角落的小工具。
從哪裡開始？取得嵌入程式碼
本頁的嵌入程式碼是從 對話平台設定 取得的。依下列步驟操作：
複製程式碼貼到您的網站
右側 程式碼預覽 會依左側設定即時更新，點擊 「 複製 」 取得如下的嵌入程式碼：
<script>
window.maiagentChatbotConfig = {
webChatId: '你的 Web Chat ID',
baseUrl: 'https://你的-maiagent-網域/web-chats',
enabledWindowModes: ['maigpt'],
targetElement: '#maigpt-container',
}
</script>
<script src="https://你的-maiagent-網域/js/embed.min.js" defer></script>各參數與兩種佈局（嵌入容器 / 右下角全屏按鈕）的完整說明，請見下方 三、嵌入設定。
一、什麼是 MaiGPT 視窗模式？
Web Chat SDK 共提供四種視窗模式，透過嵌入設定中的 enabledWindowModes 指定：
floating
預設模式。右下角浮動按鈕，點擊後展開對話視窗。適合一般客服。
sidebar
側邊欄模式，從頁面側邊滑出對話視窗。
inline
行內模式，將對話視窗嵌入頁面內容區塊中。
maigpt
本頁介紹的模式。ChatGPT 風格的完整介面，預設展開對話歷史列表，可做為頁面主要 UI。
MaiGPT 視窗模式的特點：
完整介面：iframe 填滿您指定的容器（或整個瀏覽器視窗），左側為對話歷史列表、右側為主對話區
無浮動按鈕、不可縮小：嵌入後即為頁面主體，不會有縮起的角落按鈕
對話歷史預設展開：使用者一進來就能看到過去的對話紀錄
二、前置條件
在嵌入 MaiGPT 視窗模式前，請先確認：
MaiAgent 版本已支援 MaiGPT 視窗模式：MaiGPT 視窗模式為 Web Chat SDK 新增的功能，需要 SDK（
embed.min.js）與後台皆為支援 MaiGPT 的版本。嵌入視窗才會出現 「 MaiGPT 」 選項。已建立 Web Chat 對話平台，並取得該平台的 Web Chat ID（請參考 串接對話平台：網站）。
取得嵌入腳本：於對話平台設定頁點擊 「 嵌入 」 按鈕取得嵌入程式碼。
深度研究與工具開關的權限完全由後端把關。前端只負責顯示 / 隱藏入口，實際是否可用取決於後台的 MaiGPT 模式設定。
三、嵌入設定
1. 基本嵌入程式碼
在您網站的 </body> 標籤前，加入以下腳本並設定 window.maiagentChatbotConfig：
2. 兩種嵌入方式
是否設定 targetElement 會決定 MaiGPT 以哪一種方式呈現：
設定 targetElement，SDK 會把 MaiGPT 介面直接掛載到該元素中：
iframe 會填滿
targetElement（若指定為<body>則填滿整個瀏覽器視窗）不顯示浮動按鈕、使用者無法切換視窗模式，MaiGPT 即為頁面主體
targetElement可傳入 CSS selector 字串（如'#maigpt-container'）或 HTMLElement 物件（如document.getElementById('maigpt')）
不設定 targetElement，SDK 會在頁面右下角顯示一顆按鈕，點擊後以全螢幕方式覆蓋整個畫面開啟 MaiGPT，右上角提供關閉按鈕：
適合不想改動既有頁面版面、只想加一個入口的情境
點擊右下角按鈕 → 全螢幕開啟 MaiGPT；點擊右上角關閉 → 回到按鈕狀態
四、設定參數說明
window.maiagentChatbotConfig 常用欄位：
webChatId
必填
Web Chat 對話平台 ID。
baseUrl
建議
MaiAgent 服務網址，格式為 https://你的網域/web-chats。
enabledWindowModes
必填（本模式）
啟用的視窗模式陣列，第一項為預設值。MaiGPT 模式請設為 ['maigpt']。
targetElement
選填
MaiGPT 掛載的目標元素，可為 CSS selector 字串或 HTMLElement。省略時改用右下角按鈕全螢幕模式（見上方方式二）。
maigptTitle
選填
側欄左上角顯示的品牌標題。不設定時預設顯示 MaiGPT。
contactId
選填
聯絡人 ID。用於識別終端使用者身份。
locale
選填
介面語言，如 'zh-TW'、'en'。支援多國語系。
舊版的 defaultWindowMode 欄位已不建議使用，請改用 enabledWindowModes（陣列第一項即為預設值）。
五、介面與功能
1. 對話歷史列表
MaiGPT 視窗模式左側為常駐的對話歷史列表（ChatGPT 風格），預設展開，使用者可：
瀏覽並切換過去的對話
開啟新對話
收合 / 展開側欄
2. 深度研究
當該 Web Chat 已於後台開啟 MaiGPT 模式時，輸入區會出現 深度研究（Deep Research） 入口。使用者可先點擊深度研究、再送出訊息，AI 助理便會針對該則訊息執行深度研究。
深度研究的狀態會經歷：尚未使用 → 已啟動 → 執行中 → 完成 / 失敗。
3. 工具開關
同樣在 MaiGPT 模式開啟時，使用者可透過工具選單開關 AI 助理背後掛載的工具，控制本次對話要不要使用某些工具。變更會即時生效。
4. 設定選單
點擊左下角的 設定，可開啟設定選單。實際顯示的項目會依該 Web Chat 的後台設定而定，可能包含：
文字語言：切換介面語言
文字大小：小 / 中 / 大（需後台開啟字級切換功能）
主題模式：自動 / 淺色 / 深色（需後台開啟主題模式切換）
語音語言：語音輸入所使用的語言
六、注意事項
最後更新於
這有幫助嗎？