MaiGPT 模式嵌入

將類 ChatGPT 的 MaiGPT 完整對話介面嵌入您的網站或產品，支援指定容器與漂浮全屏兩種佈局

MaiGPT 模式提供類 ChatGPT 的完整對話介面（側欄對話歷史、搜尋對話、設定面板），與既有的「右下角聊天泡泡」（floating / sidebar）不同，適合作為頁面主要功能區塊，或全站 Agent 入口。

MaiGPT 模式只決定介面長相，不決定 Agent 會什麼。 它套在哪個 Agent 的 Web Chat 上，就是那個 Agent 的指令、模型與工具；要有生圖、上網等能力，請先照串接 MaiGPT：選對 Agent、補齊能力把 Agent 的回覆模式設成 Agent 並掛上工具。組織內建的 MaiGPT 產品只供登入成員使用，其 Web Chat 不能嵌入外部頁面。

本頁聚焦 MaiGPT 模式專屬設定。嵌入的基本觀念、完整配置參考與 JavaScript API 請見 Web Chat 嵌入與 SDK；未在本頁列出的共通參數（auth、queryMetadata、按鈕外觀等）在 MaiGPT 模式同樣適用。

一、兩種佈局模式

同一份設定支援兩種佈局，由 targetElement 是否存在決定：

• 模式 A — 嵌入指定容器：MaiGPT 常駐顯示在頁面中的指定 div（適合作為系統的主要工作區）

• 模式 B — 漂浮按鈕 + 全屏：右下角漂浮按鈕，點擊後全屏開啟（適合全站 Agent 入口）

兩種行為皆由相同的 maigpt 模式觸發，只差 targetElement 一個欄位。

二、模式 A：嵌入指定容器

嵌入程式碼

<!-- 頁面中先準備好容器，並自行給定尺寸 -->
<div id="maigpt-container" style="height: 720px;"></div>

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    primaryColor: '#1890ff',
    maigptTitle: 'Acme GPT',
  }
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

baseUrl 與 SDK Loader 網址以 SaaS 環境（chat.maiagent.ai）為例；私有雲 / 地端部署請換成您環境的網域。

實際嵌入效果（企業入口網站內嵌 MaiGPT，maigptTitle 設為品牌名稱）：

模式 A：MaiGPT 常駐顯示在頁面指定容器內，左側為對話歷史側欄

容器要求

• 容器必須自行給定高度（iframe 以 100% 撐滿容器；容器高度為 0 時看不到內容）

• targetElement 接受 CSS selector 字串（如 '#maigpt-container'）或 HTMLElement 物件；指定為 <body> 時以全屏方式顯示

• 傳 selector 字串時，SDK 會等元素出現，最多 5 秒，SPA 晚一點才 mount 的容器也接得到

• 容器若為 position: static，SDK 會自動改為 position: relative，一般不需處理

• iframe 只佔據該容器，不影響頁面其他區塊

找不到容器時不會嵌入：selector 寫錯、5 秒內等不到元素，或傳入的 HTMLElement 還沒掛到頁面上，MaiGPT 都不會出現，console 會出現 [maiagent] targetElement ... MaiGPT embed skipped 錯誤，說明原因。

請確認：(1) selector 拼寫正確；(2) 容器在 SDK 載入後 5 秒內出現在 DOM（loader <script> 放在容器之後並加 defer；SPA 請在容器 mount 後再載入 SDK）。

三、模式 B：漂浮按鈕 + 全屏

嵌入程式碼

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    primaryColor: '#1890ff',
    maigptTitle: 'Acme GPT',
  }
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

行為說明

1. 頁面右下角顯示漂浮按鈕（顏色取 primaryColor）

2. 點擊按鈕 → MaiGPT 以全屏 iframe 開啟，右上角出現「×」關閉鈕

3. 點「×」→ 全屏收合、回到漂浮按鈕

4. 收合時 iframe 僅隱藏、不銷毀 → 再次開啟會保留原本的對話狀態

模式 B 操作示範：點擊漂浮按鈕 → 全屏開啟 → 送出問題、AI 串流回覆 → 「×」收合回按鈕

兩個狀態的靜態截圖

收合狀態：頁面右下角僅顯示漂浮按鈕，不干擾原頁面

開啟狀態：MaiGPT 全屏顯示，右上角「×」可收合

按鈕外觀參數（皆選填，僅模式 B 適用）

參數	預設值	說明
primaryColor	#1890ff	按鈕底色，可改為品牌色
buttonSize	3rem	按鈕尺寸
buttonRadius	50%	按鈕圓角
buttonPositionBottom	1rem	距視窗底部
buttonPositionRight	1rem	距視窗右側
buttonIcon	（內建 icon）	自訂按鈕圖示的圖片 URL
boxShadow	0.125rem 0.125rem 0.5rem #00000044	按鈕陰影

四、完整參數表

欄位	型別	必填	說明
webChatId	string	✅	Web Chat ID
baseUrl	string	✅	Web Chat 服務位址，SaaS 為 https://chat.maiagent.ai/web-chats
enabledWindowModes	string[]	✅	固定 ['maigpt']（第一個元素決定模式）
targetElement	string 或 HTMLElement	✖	有值 → 模式 A；無值 → 模式 B
maigptTitle	string	✖	側欄左上角品牌標題，不設定則顯示 MaiGPT
primaryColor	string	✖	介面主色，可調整為品牌色
locale	string	✖	介面語系，見下方語系；不指定時由上次記住的語系或瀏覽器語系決定
contactId	string	✖	MaiAgent 聯絡人 ID，用於識別登入使用者，見識別使用者
queryMetadata	object 或 string	✖	附帶到對話的查詢元資料，詳見知識管理權限總覽

設定未知的欄位不會報錯，但 console 會出現 [maiagent] Unknown config options: ... 警告，方便檢查拼字。

五、locale 語系

window.maiagentChatbotConfig = {
  // ...
  locale: 'en',
}

支援的語系值

zh-TW（繁中）、zh-CN（簡中）、en、ja、ko、th、vi-VN、id、fil-PH、ms-MY、km-KH、lo-LA、my-MM

決定順序

1. config 的 locale（一定生效，優先權最高）

2. 使用者上次在此瀏覽器使用過的語系（會被記住）

3. 瀏覽器語系

4. 預設 zh-TW

locale 只影響介面文字（按鈕、選單、提示），不影響 AI 回答的語言。傳入不支援的值會被忽略，依序 fallback。

六、識別使用者（contactId）

若要讓 AI 知道「誰在問」（跨裝置保留對話歷史、個人化回覆、以使用者權限呼叫工具），需在 config 帶入 contactId：

1. 後端在使用者登入時呼叫 聯絡人身分同步 API 取得 contactId

2. 前端把 contactId 加進 config：

// 假設登入後從 API 取得使用者資訊（含 contactId）
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  body: JSON.stringify({ username, password })
});
const userData = await loginResponse.json();

// 動態設定 Web Chat config
window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://chat.maiagent.ai/web-chats',
  enabledWindowModes: ['maigpt'],
  targetElement: '#maigpt-container',
  contactId: userData.maiagentContactId,  // 從登入 response 取得
};

contactId 必須是該登入使用者對應的值。不帶 contactId 時為匿名使用：對話歷史以瀏覽器為單位保留（同一瀏覽器重新整理後仍在），但無法跨裝置、也無法以使用者身分存取個人資料。

七、常見問題

MaiGPT 模式跟原本的聊天泡泡（floating / sidebar）差在哪？

MaiGPT 是完整的對話工作介面（側欄對話歷史、搜尋對話、設定面板），佔據整個容器或全屏；floating / sidebar 是疊在頁面角落的小視窗。兩者用同一個 enabledWindowModes 欄位切換：['maigpt'] vs ['floating', 'sidebar']。MaiGPT 模式下不提供視窗模式切換。

對話歷史存在哪裡？

依 Web Chat 的識別機制保留在 MaiAgent 後端。不帶 contactId 時以瀏覽器為單位（匿名）；帶 contactId 時跟著該聯絡人，可跨裝置。

同一頁可以放兩個 MaiGPT 嗎？

不行。SDK 每頁只初始化一次，重複載入會被忽略。

SPA（React / Vue）怎麼嵌入模式 A？

確保容器元素 mount 完成後再載入 embed.min.js（或屆時再設定 window.maiagentChatbotConfig 並動態插入 loader script）。SDK 先跑時會等容器最多 5 秒，逾時就不嵌入（見容器要求）。

左上角的「MaiGPT」名稱可以改成自家品牌嗎？

可以。config 加 maigptTitle: 'Acme GPT' 即可，兩種模式都生效；不設定或給空字串時回到預設 MaiGPT。