> 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/maiagent-user-guide/en/build/choose-channel/web-chat/maigpt-embed.md).

# Embed MaiGPT in Window Mode

Embed a complete ChatGPT-style conversation interface directly into your website with MaiGPT window mode, including Deep Research and tool selection.

In addition to the familiar floating button in the bottom-right corner, the MaiAgent Web Chat SDK now offers **MaiGPT window mode**. You can embed a **complete ChatGPT-style conversation interface** (conversation history on the left + main conversation area on the right) anywhere on your own page as its main UI, instead of a small widget tucked into a corner.

{% hint style="info" %}
This page explains how to embed MaiGPT window mode into your website. If you have not created a Web Chat channel yet, first follow [Connect a Channel: Website](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/website.md) to complete the basic setup.
{% endhint %}

{% hint style="warning" %}
**MaiGPT window mode is different from the MaiGPT product.** Window mode only determines the appearance of Web Chat: it uses the role instructions, model, and tools of the Agent whose Web Chat it is applied to. The built-in [MaiGPT](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt.md) is a workspace that organization members sign in to use; these are two different things.
{% endhint %}

## <mark style="color:blue;">Where to Start: Get the Embed Code</mark> <a href="#where-to-start" id="where-to-start"></a>

Get the embed code for this page from [Basic Settings](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings/basic-settings.md#public-url-and-embed). Follow these steps:

{% stepper %}
{% step %}

### Open the channel settings

Under “ <mark style="color:blue;">Customer Service Conversations > Channels</mark> ”, select your Web Chat channel and click “ <mark style="color:blue;">Actions</mark> ” to open its settings page.
{% endstep %}

{% step %}

### Click “Embed”

In <mark style="color:blue;">Basic Settings</mark>, find the public access URL section and click “ <mark style="color:blue;">Embed</mark> ” to open the embed dialog.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6651b11c4e50542297b13ca2af596a8a6bc1e51b%2Fmaigpt-embed-start-2-embed-button.png?alt=media" alt="Embed button in Basic Settings"><figcaption><p>Basic Settings > Embed</p></figcaption></figure>
{% endstep %}

{% step %}

### Select the MaiGPT embed method

Switch between the three embed methods at the top of the dialog and select “ <mark style="color:blue;">MaiGPT</mark> ”:

| Embed Method | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| JavaScript   | Loaded with `<script>`; the most common method                |
| Iframe       | Embedded directly with `<iframe>`                             |
| **MaiGPT**   | **The complete ChatGPT-style interface covered on this page** |

On the left, you can adjust the embed container (`targetElement`), language (`locale`), and title (`maigptTitle`).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-389bc6aca11714bc271f35f3c015e9f6d8c81179%2Fmaigpt-embed-start-3-maigpt-tab.png?alt=media" alt="MaiGPT selected in the embed dialog, with a live code preview on the right"><figcaption><p>Embed dialog > Select MaiGPT > Live code preview on the right</p></figcaption></figure>
{% endstep %}

{% step %}

### Copy the code and paste it into your website

The <mark style="color:blue;">Code Preview</mark> on the right updates as you change the settings on the left. Click “ <mark style="color:blue;">Copy</mark> ” to get embed code like this:

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

For a full explanation of the parameters and the two layouts (embedded container / bottom-right fullscreen button), see [3. Embed Setup](#embed-setup) below.
{% endstep %}
{% endstepper %}

## <mark style="color:blue;">1. What Is MaiGPT Window Mode?</mark> <a href="#what-is-maigpt-mode" id="what-is-maigpt-mode"></a>

The Web Chat SDK offers four window modes, specified through `enabledWindowModes` in the embed configuration:

<table><thead><tr><th width="140">Window Mode</th><th>Description</th></tr></thead><tbody><tr><td><code>floating</code></td><td>The default mode. A floating button in the bottom-right corner opens a conversation window when clicked. Suitable for general customer service.</td></tr><tr><td><code>sidebar</code></td><td>Sidebar mode. The conversation window slides out from the side of the page.</td></tr><tr><td><code>inline</code></td><td>Inline mode. The conversation window is embedded in a content area on the page.</td></tr><tr><td><code>maigpt</code></td><td><strong>The mode covered on this page</strong>. A complete ChatGPT-style interface with conversation history expanded by default, suitable as the page's main UI.</td></tr></tbody></table>

Features of MaiGPT window mode:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-40da32c6e68a4607ef47a4430950a10cbb1765b5%2Fmaigpt-embed-overview.png?alt=media" alt="Overview of the MaiGPT window mode interface"><figcaption><p>MaiGPT window mode: conversation history on the left + main conversation area on the right (ChatGPT style)</p></figcaption></figure>

* **Complete interface**: The iframe fills your specified container (or the entire browser window), with conversation history on the left and the main conversation area on the right
* **No floating button or minimize option**: Once embedded, it becomes the main content of the page, without a collapsed button in the corner
* **Conversation history expanded by default**: Users can see their past conversations as soon as they arrive
* **Access to advanced features**: The input area provides [Deep Research](#deep-research) and [tool toggles](#tool-toggle)

## <mark style="color:blue;">2. Prerequisites</mark> <a href="#prerequisites" id="prerequisites"></a>

Before embedding MaiGPT window mode, confirm the following:

1. **Your MaiAgent version supports MaiGPT window mode**: This is a new Web Chat SDK feature. Both the SDK (`embed.min.js`) and the backend must be versions that support MaiGPT for the “ <mark style="color:blue;">MaiGPT</mark> ” option to appear in the embed dialog.
2. **You have created a Web Chat channel** and obtained its **Web Chat ID** (see [Connect a Channel: Website](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/website.md)).
3. **You have obtained the embed script**: Click “ <mark style="color:blue;">Embed</mark> ” on the channel settings page to get the embed code.

{% hint style="info" %}
MaiAgent's cloud service (`chat.maiagent.ai`) includes MaiGPT window mode and is ready to use. For private deployments or older versions, the “ <mark style="color:blue;">MaiGPT</mark> ” option may not appear in the embed dialog. Contact MaiAgent first to confirm and upgrade to a supported version.
{% endhint %}

## <mark style="color:blue;">3. Embed Setup</mark> <a href="#embed-setup" id="embed-setup"></a>

### 1. Basic embed code <a href="#basic-embed-code" id="basic-embed-code"></a>

You can use the code copied from the embed dialog directly (see [Get the Embed Code](#where-to-start) above). Paste it before your website's `</body>` tag. `enabledWindowModes` is an array, and **the first element sets the default window mode**. To use MaiGPT window mode, place `'maigpt'` first.

### 2. Two embed methods <a href="#two-embed-methods" id="two-embed-methods"></a>

Whether you set `targetElement` determines how MaiGPT appears:

* **Embed in a specified container** (set `targetElement`): MaiGPT stays in your specified area as the page's main content. It has no floating button and does not allow window mode switching. Suitable for AI portals or the main workspace of a system.
* **Open fullscreen from a bottom-right button** (omit `targetElement`): A button appears in the bottom-right corner of the page. Clicking it opens MaiGPT fullscreen; closing it from the top-right corner returns to the button. Suitable when you want to add an entry point without changing the existing layout.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fc00704a20ae5555852e51623ca7e220b7e0939f%2Fmaigpt-embed-fullscreen-button.png?alt=media" alt="The SDK provides a floating button in the bottom-right corner when targetElement is not set"><figcaption><p>Without <code>targetElement</code>, a button appears in the bottom-right corner and opens the interface fullscreen when clicked</p></figcaption></figure>

For complete code examples for both methods, container height requirements, behavior when the container is not found, and SPA embedding, developers can refer to [Embedding MaiGPT Mode](https://docs.maiagent.ai/tech/serve/web-chat-sdk/web-chat-maigpt-mode) in the technical manual.

## <mark style="color:blue;">4. Configuration Parameters</mark> <a href="#config-reference" id="config-reference"></a>

The code generated by the embed dialog includes the necessary fields: `webChatId` and `baseUrl` are required, and MaiGPT will not appear if either is missing; `enabledWindowModes` is set to `['maigpt']`. The fields adjustable on the left—`targetElement` (embed container), `locale` (language), and `maigptTitle` (sidebar title, which displays `MaiGPT` by default)—are optional.

For the types and descriptions of all fields, see [Embedding MaiGPT Mode: Complete Parameter Reference](https://docs.maiagent.ai/tech/serve/web-chat-sdk/web-chat-maigpt-mode#config-reference) in the technical manual. The older `defaultWindowMode` field is no longer recommended; use `enabledWindowModes` instead.

## <mark style="color:blue;">5. Interface and Features</mark> <a href="#ui-features" id="ui-features"></a>

### 1. Conversation history <a href="#conversation-history" id="conversation-history"></a>

MaiGPT window mode has a persistent ChatGPT-style conversation history sidebar on the left, expanded by default. Users can:

* Browse and switch between past conversations
* Start a new conversation
* Collapse / expand the sidebar

### 2. Deep Research <a href="#deep-research" id="deep-research"></a>

When opened in MaiGPT window mode, the input area includes a **Deep Research** entry point. Users can click Deep Research before sending a message, and the Agent will perform Deep Research for that message.

Deep Research progresses through these states: `Not used → Activated → Running → Completed / Failed`.

{% hint style="info" %}
Deep Research cannot be triggered again while it is running. It can be activated again after it completes or fails.
{% endhint %}

### 3. Tool toggles <a href="#tool-toggle" id="tool-toggle"></a>

When opened in MaiGPT window mode with tools attached to the Agent, users can select the tools they want to use from the tool menu. The message they send specifies the selected tools. If none are selected, the Agent decides which tools to use from all available tools. Selections apply only to the current conversation.

### 4. Settings menu <a href="#settings-menu" id="settings-menu"></a>

Click <mark style="color:blue;">Settings</mark> in the bottom-left corner to open the settings menu. The items shown depend on the backend settings for that Web Chat and may include:

* **Text Language**: Switch the interface language. After selection, the platform also asks the Agent to reply in that language (see [How the AI Reply Language Is Determined](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/multi-language-support.md#reply-language)). Switching the language here does not start a new conversation
* **Text Size**: Small / Medium / Large (requires font size switching to be enabled in the backend)
* **Theme Mode**: Auto / Light / Dark (requires theme mode switching to be enabled in the backend)
* **Voice Language**: The language used for voice input

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-df95f8609d6e5be9f3815f068b7deba7e5a66872%2Fmaigpt-embed-settings.png?alt=media" alt="MaiGPT window mode settings menu"><figcaption><p>Settings menu (actual items depend on backend settings)</p></figcaption></figure>

## <mark style="color:blue;">6. Notes</mark> <a href="#notes" id="notes"></a>

{% hint style="info" %}

* **Responsive layout**: MaiGPT supports desktop and mobile devices, as well as dark mode.
* **Compatible with existing modes**: MaiGPT is an additional window mode that does not affect the behavior of existing `floating` / `sidebar` / `inline` modes. Existing integrations require no changes.
  {% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/maigpt-embed.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
