MaiGPT 模式嵌入

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

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

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

一、兩種佈局模式

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

模式 A — 嵌入指定容器：MaiGPT 常駐顯示在頁面中的指定 div（適合作為系統的主要工作區）
模式 B — 漂浮按鈕 + 全屏：右下角漂浮按鈕，點擊後全屏開啟（適合全站 AI 助理入口）

兩種行為皆由相同的 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 設為品牌名稱）：

容器要求

容器必須自行給定高度（iframe 以 100% 撐滿容器；容器高度為 0 時看不到內容）
targetElement 接受 CSS selector 字串（如 '#maigpt-container'）或 HTMLElement 物件
容器若為 position: static，SDK 會自動改為 position: relative，一般不需處理
iframe 只佔據該容器，不影響頁面其他區塊

重要：selector 找不到元素時，會 fallback 成全屏覆蓋整個頁面，且沒有關閉鈕（console 會出現 [maiagent] targetElement selector "..." not found, falling back to <body> 警告）。

請確認：(1) selector 拼寫正確；(2) SDK 載入時容器已存在於 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>

行為說明

頁面右下角顯示漂浮按鈕（顏色取 primaryColor）
點擊按鈕 → MaiGPT 以全屏 iframe 開啟，右上角出現「×」關閉鈕
點「×」→ 全屏收合、回到漂浮按鈕
收合時 iframe 僅隱藏、不銷毀 → 再次開啟會保留原本的對話狀態

兩個狀態的靜態截圖

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

參數

預設值

說明

primaryColor

#1890ff

按鈕底色，可改為品牌色

buttonSize

3rem

按鈕尺寸

buttonRadius

50%

按鈕圓角

buttonPositionBottom

1rem

距視窗底部

buttonPositionRight

1rem

距視窗右側

buttonIcon

（內建 icon）

自訂按鈕圖示的圖片 URL

boxShadow

0.125rem 0.125rem 0.5rem #00000044

按鈕陰影

四、完整參數表

欄位

型別

必填

說明

webChatId

string

✅

WebChat 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

決定順序

config 的 locale（一定生效，優先權最高）
使用者上次在此瀏覽器使用過的語系（會被記住）
瀏覽器語系
預設 zh-TW

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

六、識別使用者（contactId）

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

後端在使用者登入時呼叫聯絡人身份同步 API 取得 contactId
前端把 contactId 加進 config：

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

// 動態設定 WebChat 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 模式下不提供視窗模式切換。

對話歷史存在哪裡？

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

同一頁可以放兩個 MaiGPT 嗎？

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

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

確保容器元素 mount 完成後再載入 embed.min.js（或屆時再設定 window.maiagentChatbotConfig 並動態插入 loader script）。若 SDK 先跑、容器還不存在，會觸發全屏 fallback（見容器要求）。

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

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

上一頁Web Chat 嵌入與 SDK

下一頁注入頁面 Context

最後更新於 1 個月前

這有幫助嗎？