> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/conversations/web-chat/maigpt-embed.md).

# MaiGPT 視窗模式嵌入

以 MaiGPT 視窗模式將 ChatGPT 風格的完整對話介面直接嵌入您的網站，並可開放深度研究與工具開關。

除了常見的「右下角浮動按鈕」外，MaiAgent 的 Web Chat SDK 新增了 **MaiGPT 視窗模式**，讓您可以把一個 **ChatGPT 風格的完整對話介面**（左側對話歷史列表 + 右側主對話區）直接嵌入到自家頁面的任意位置，做為頁面的主要 UI，而不是縮在角落的小工具。

{% hint style="info" %}
本頁說明「如何在自家網站嵌入 MaiGPT 視窗模式」。若您還沒有建立 Web Chat 對話平台，請先參考 [串接對話平台：網站](/conversations/web-chat/website.md) 完成基本設定。
{% endhint %}

## <mark style="color:blue;">從哪裡開始？取得嵌入程式碼</mark> <a href="#where-to-start" id="where-to-start"></a>

本頁的嵌入程式碼是從 [基本設定](/conversations/platform-settings/basic-settings.md#public-url-and-embed) 取得的。依下列步驟操作：

{% stepper %}
{% step %}

### 進入對話平台設定

於 「 <mark style="color:blue;">客服對話 > 對話平台</mark> 」 選擇您的 Web Chat 平台，點擊 「 <mark style="color:blue;">操作</mark> 」 進入設定頁。
{% endstep %}

{% step %}

### 點擊「嵌入」

於 <mark style="color:blue;">基本設定</mark> 找到公開訪問 URL 區塊，點擊 「 <mark style="color:blue;">嵌入</mark> 」 按鈕開啟嵌入視窗。
{% endstep %}

{% step %}

### 選擇 MaiGPT 嵌入方式

在視窗上方切換三種嵌入方式，選擇 「 <mark style="color:blue;">MaiGPT</mark> 」：

| 嵌入方式       | 說明                       |
| ---------- | ------------------------ |
| JavaScript | 以 `<script>` 載入，最常用      |
| Iframe     | 以 `<iframe>` 直接嵌入        |
| **MaiGPT** | **本頁介紹的 ChatGPT 風格完整介面** |

左側可調整 嵌入容器（`targetElement`）、語系（`locale`）、標題（`maigptTitle`）。
{% endstep %}

{% step %}

### 複製程式碼貼到您的網站

右側 <mark style="color:blue;">程式碼預覽</mark> 會依左側設定即時更新，點擊 「 <mark style="color:blue;">複製</mark> 」 取得如下的嵌入程式碼：

```html
<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>
```

各參數與兩種佈局（嵌入容器 / 右下角全屏按鈕）的完整說明，請見下方 [三、嵌入設定](#embed-setup)。
{% endstep %}
{% endstepper %}

## <mark style="color:blue;">一、什麼是 MaiGPT 視窗模式？</mark> <a href="#what-is-maigpt-mode" id="what-is-maigpt-mode"></a>

Web Chat SDK 共提供四種視窗模式，透過嵌入設定中的 `enabledWindowModes` 指定：

<table><thead><tr><th width="140">視窗模式</th><th>說明</th></tr></thead><tbody><tr><td><code>floating</code></td><td>預設模式。右下角浮動按鈕，點擊後展開對話視窗。適合一般客服。</td></tr><tr><td><code>sidebar</code></td><td>側邊欄模式，從頁面側邊滑出對話視窗。</td></tr><tr><td><code>inline</code></td><td>行內模式，將對話視窗嵌入頁面內容區塊中。</td></tr><tr><td><code>maigpt</code></td><td><strong>本頁介紹的模式</strong>。ChatGPT 風格的完整介面，預設展開對話歷史列表，可做為頁面主要 UI。</td></tr></tbody></table>

MaiGPT 視窗模式的特點：

* **完整介面**：iframe 填滿您指定的容器（或整個瀏覽器視窗），左側為對話歷史列表、右側為主對話區
* **無浮動按鈕、不可縮小**：嵌入後即為頁面主體，不會有縮起的角落按鈕
* **對話歷史預設展開**：使用者一進來就能看到過去的對話紀錄
* **進階功能入口**：可依後台設定開放 [深度研究](#deep-research) 與 [工具開關](#tool-toggle)

## <mark style="color:blue;">二、前置條件</mark> <a href="#prerequisites" id="prerequisites"></a>

在嵌入 MaiGPT 視窗模式前，請先確認：

1. **MaiAgent 版本已支援 MaiGPT 視窗模式**：MaiGPT 視窗模式為 Web Chat SDK 新增的功能，需要 SDK（`embed.min.js`）與後台皆為支援 MaiGPT 的版本。嵌入視窗才會出現 「 <mark style="color:blue;">MaiGPT</mark> 」 選項。
2. **已建立 Web Chat 對話平台**，並取得該平台的 **Web Chat ID**（請參考 [串接對話平台：網站](/conversations/web-chat/website.md)）。
3. **（選用）在後台開啟 MaiGPT 模式**：若您希望開放 [深度研究](#deep-research) 與 [工具開關](#tool-toggle) 給終端使用者操作，需由 AI 助理擁有者在後台開啟該 Web Chat 的 MaiGPT 模式。未開啟時，MaiGPT 版面仍可正常顯示，但不會出現進階功能入口。
4. **取得嵌入腳本**：於對話平台設定頁點擊 「 <mark style="color:blue;">嵌入</mark> 」 按鈕取得嵌入程式碼。

{% hint style="info" %}
MaiAgent 雲端服務（`chat.maiagent.ai`）已內建 MaiGPT 視窗模式，可直接使用；若為私有部署或較舊版本，嵌入視窗可能不會出現 「 <mark style="color:blue;">MaiGPT</mark> 」 選項，請先與 MaiAgent 確認並升級至支援的版本。
{% endhint %}

{% hint style="warning" %}
深度研究與工具開關的權限完全由後端把關。前端只負責顯示 / 隱藏入口，實際是否可用取決於後台的 MaiGPT 模式設定。
{% endhint %}

## <mark style="color:blue;">三、嵌入設定</mark> <a href="#embed-setup" id="embed-setup"></a>

### 1. 基本嵌入程式碼 <a href="#basic-embed-code" id="basic-embed-code"></a>

在您網站的 `</body>` 標籤前，加入以下腳本並設定 `window.maiagentChatbotConfig`：

{% code title="嵌入 MaiGPT 視窗模式" overflow="wrap" lineNumbers="true" %}

```html
<script>
  window.maiagentChatbotConfig = {
    webChatId: '你的 Web Chat ID',
    baseUrl: 'https://你的-maiagent-網域/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    locale: 'zh-TW',
  }
</script>
<script src="https://你的-maiagent-網域/js/embed.min.js"></script>
```

{% endcode %}

{% hint style="info" %}
`enabledWindowModes` 為陣列，**第一個元素即為預設視窗模式**。要使用 MaiGPT 視窗模式，請將 `['maigpt']` 設為第一項。
{% endhint %}

### 2. 兩種嵌入方式 <a href="#two-embed-methods" id="two-embed-methods"></a>

是否設定 `targetElement` 會決定 MaiGPT 以哪一種方式呈現：

{% tabs %}
{% tab title="方式一：嵌入到指定容器" %}
**設定 `targetElement`**，SDK 會把 MaiGPT 介面直接掛載到該元素中：

```html
<div id="maigpt-container" style="width: 100%; height: 100vh;"></div>
<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"></script>
```

* iframe 會填滿 `targetElement`（若指定為 `<body>` 則填滿整個瀏覽器視窗）
* 不顯示浮動按鈕、使用者無法切換視窗模式，MaiGPT 即為頁面主體
* `targetElement` 可傳入 **CSS selector 字串**（如 `'#maigpt-container'`）或 **HTMLElement 物件**（如 `document.getElementById('maigpt')`）
  {% endtab %}

{% tab title="方式二：右下角按鈕全螢幕開啟" %}
**不設定 `targetElement`**，SDK 會在頁面右下角顯示一顆按鈕，點擊後以全螢幕方式覆蓋整個畫面開啟 MaiGPT，右上角提供關閉按鈕：

```html
<script>
  window.maiagentChatbotConfig = {
    webChatId: '你的 Web Chat ID',
    baseUrl: 'https://你的-maiagent-網域/web-chats',
    enabledWindowModes: ['maigpt'],
  }
</script>
<script src="https://你的-maiagent-網域/js/embed.min.js"></script>
```

* 適合不想改動既有頁面版面、只想加一個入口的情境
* 點擊右下角按鈕 → 全螢幕開啟 MaiGPT；點擊右上角關閉 → 回到按鈕狀態
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
若 `targetElement` 指定的 selector 在頁面上找不到，SDK 會自動改掛載到 `<body>`，並在瀏覽器 Console 輸出警告訊息（不會中斷初始化）。
{% endhint %}

## <mark style="color:blue;">四、設定參數說明</mark> <a href="#config-reference" id="config-reference"></a>

`window.maiagentChatbotConfig` 常用欄位：

<table><thead><tr><th width="200">欄位</th><th width="120">是否必填</th><th>說明</th></tr></thead><tbody><tr><td><code>webChatId</code></td><td>必填</td><td>Web Chat 對話平台 ID。</td></tr><tr><td><code>baseUrl</code></td><td>建議</td><td>MaiAgent 服務網址，格式為 <code>https://你的網域/web-chats</code>。</td></tr><tr><td><code>enabledWindowModes</code></td><td>必填（本模式）</td><td>啟用的視窗模式陣列，第一項為預設值。MaiGPT 模式請設為 <code>['maigpt']</code>。</td></tr><tr><td><code>targetElement</code></td><td>選填</td><td>MaiGPT 掛載的目標元素，可為 CSS selector 字串或 HTMLElement。省略時改用右下角按鈕全螢幕模式（見上方方式二）。</td></tr><tr><td><code>maigptTitle</code></td><td>選填</td><td>側欄左上角顯示的品牌標題。不設定時預設顯示 <code>MaiGPT</code>。</td></tr><tr><td><code>contactId</code></td><td>選填</td><td>聯絡人 ID。用於識別終端使用者身份。</td></tr><tr><td><code>locale</code></td><td>選填</td><td>介面語言，如 <code>'zh-TW'</code>、<code>'en'</code>。支援多國語系。</td></tr></tbody></table>

{% hint style="warning" %}
舊版的 `defaultWindowMode` 欄位已**不建議使用**，請改用 `enabledWindowModes`（陣列第一項即為預設值）。
{% endhint %}

## <mark style="color:blue;">五、介面與功能</mark> <a href="#ui-features" id="ui-features"></a>

### 1. 對話歷史列表 <a href="#conversation-history" id="conversation-history"></a>

MaiGPT 視窗模式左側為常駐的對話歷史列表（ChatGPT 風格），預設展開，使用者可：

* 瀏覽並切換過去的對話
* 開啟新對話
* 收合 / 展開側欄

### 2. 深度研究 <a href="#deep-research" id="deep-research"></a>

當該 Web Chat 已於後台開啟 MaiGPT 模式時，輸入區會出現 **深度研究（Deep Research）** 入口。使用者可先點擊深度研究、再送出訊息，AI 助理便會針對該則訊息執行深度研究。

深度研究的狀態會經歷：`尚未使用 → 已啟動 → 執行中 → 完成 / 失敗`。

{% hint style="info" %}
深度研究進行中（執行中）時無法重複觸發；待「完成」或「失敗」後才能再次啟動。
{% endhint %}

### 3. 工具開關 <a href="#tool-toggle" id="tool-toggle"></a>

同樣在 MaiGPT 模式開啟時，使用者可透過工具選單開關 AI 助理背後掛載的工具，控制本次對話要不要使用某些工具。變更會即時生效。

### 4. 設定選單 <a href="#settings-menu" id="settings-menu"></a>

點擊左下角的 <mark style="color:blue;">設定</mark>，可開啟設定選單。實際顯示的項目會依該 Web Chat 的後台設定而定，可能包含：

* **文字語言**：切換介面語言
* **文字大小**：小 / 中 / 大（需後台開啟字級切換功能）
* **主題模式**：自動 / 淺色 / 深色（需後台開啟主題模式切換）
* **語音語言**：語音輸入所使用的語言

## <mark style="color:blue;">六、注意事項</mark> <a href="#notes" id="notes"></a>

{% hint style="info" %}

* **響應式**：MaiGPT 版面支援桌機與行動裝置，並支援深色模式。
* **與既有模式相容**：MaiGPT 為新增的視窗模式，不影響既有 `floating` / `sidebar` / `inline` 模式的行為；既有整合無須調整。
* **進階功能取決於後台**：深度研究與工具開關是否顯示，取決於後台是否開啟該 Web Chat 的 MaiGPT 模式；未開啟時仍可作為純對話介面使用。
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/conversations/web-chat/maigpt-embed.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.