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 的後台設定而定,可能包含:
文字語言:切換介面語言
文字大小:小 / 中 / 大(需後台開啟字級切換功能)
主題模式:自動 / 淺色 / 深色(需後台開啟主題模式切換)
語音語言:語音輸入所使用的語言
六、注意事項
最後更新於
這有幫助嗎?
