> 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/conversations/web-chat/maigpt-embed.md).

# MaiGPT Window Mode Embed

Embed a full ChatGPT-style conversation interface in MaiGPT window mode directly into your website, with options to enable Deep Research and tool toggles.

In addition to the common "floating button in the bottom-right corner," MaiAgent's Web Chat SDK introduces **MaiGPT window mode**, which lets you embed a **full ChatGPT-style conversation interface** (conversation history list on the left + main conversation area on the right) directly into any position on your page as the primary UI, rather than a small widget tucked in a corner.

{% hint style="info" %}
This page explains "how to embed MaiGPT window mode on your website." If you have not yet created a Web Chat platform, please refer to [Integrate with Platform: Website](/maiagent-user-guide/en/conversations/web-chat/website.md) to complete the basic setup first.
{% endhint %}

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

The embed code on this page is obtained from [Basic Settings](/maiagent-user-guide/en/conversations/platform-settings/basic-settings.md#public-url-and-embed). Follow the steps below:

{% stepper %}
{% step %}

### Access the Chat Platform Settings

Go to "<mark style="color:blue;">Customer Service > Chat Platforms</mark>", select your Web Chat platform, and click "<mark style="color:blue;">Operations</mark>" to enter the settings page.
{% endstep %}

{% step %}

### Click "Embed"

In <mark style="color:blue;">Basic Settings</mark>, find the Public Access URL section and click the "<mark style="color:blue;">Embed</mark>" button to open the embed window.
{% endstep %}

{% step %}

### Select the MaiGPT Embed Method

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

| Embed Method | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| JavaScript   | Loaded via `<script>`, the most common method               |
| Iframe       | Embedded directly via `<iframe>`                            |
| **MaiGPT**   | **The full ChatGPT-style interface described on this page** |

On the left side, you can adjust the embed container (`targetElement`), locale (`locale`), and title (`maigptTitle`).
{% endstep %}

{% step %}

### Copy the Code and Paste It into Your Website

The <mark style="color:blue;">code preview</mark> on the right updates in real time based on the left-side settings. Click "<mark style="color:blue;">Copy</mark>" to get the embed code as shown below:

```html
<script>
  window.maiagentChatbotConfig = {
    webChatId: 'Your Web Chat ID',
    baseUrl: 'https://your-maiagent-domain/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
  }
</script>
<script src="https://your-maiagent-domain/js/embed.min.js" defer></script>
```

For a full description of each parameter and the two layout options (embed container / bottom-right full-screen button), see [Section 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 provides four window modes, specified via the `enabledWindowModes` setting 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>Default mode. A floating button in the bottom-right corner that expands into a conversation window when clicked. Suitable for general customer service.</td></tr><tr><td><code>sidebar</code></td><td>Sidebar mode. A 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 within the page content area.</td></tr><tr><td><code>maigpt</code></td><td><strong>The mode described on this page</strong>. A full ChatGPT-style interface with the conversation history list expanded by default, suitable as the primary page UI.</td></tr></tbody></table>

Key features of MaiGPT window mode:

* **Full interface**: The iframe fills the container you specify (or the entire browser window), with the conversation history list on the left and the main conversation area on the right
* **No floating button, cannot be minimized**: Once embedded, it becomes the main page content with no collapsible corner button
* **Conversation history expanded by default**: Users can see past conversation records as soon as they enter
* **Advanced feature access**: [Deep Research](#deep-research) and [Tool Toggle](#tool-toggle) can be enabled based on backend settings

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

Before embedding MaiGPT window mode, please confirm:

1. **Your MaiAgent version supports MaiGPT window mode**: MaiGPT window mode is a new feature added to the Web Chat SDK and requires both the SDK (`embed.min.js`) and the backend to be versions that support MaiGPT. The "<mark style="color:blue;">MaiGPT</mark>" option will only appear in the embed window when supported.
2. **You have created a Web Chat platform** and obtained its **Web Chat ID** (refer to [Integrate with Platform: Website](/maiagent-user-guide/en/conversations/web-chat/website.md)).
3. **(Optional) Enable MaiGPT mode in the backend**: If you want to make [Deep Research](#deep-research) and [Tool Toggle](#tool-toggle) available to end users, the AI assistant owner must enable MaiGPT mode for that Web Chat in the backend. When not enabled, the MaiGPT layout will still display normally, but advanced feature access points will not appear.
4. **Obtain the embed script**: Click the "<mark style="color:blue;">Embed</mark>" button on the chat platform settings page to get the embed code.

{% hint style="info" %}
MaiAgent cloud service (`chat.maiagent.ai`) has MaiGPT window mode built in 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 window. Please confirm with MaiAgent and upgrade to a supported version.
{% endhint %}

{% hint style="warning" %}
Permissions for Deep Research and Tool Toggle are fully controlled by the backend. The frontend only shows or hides the access points; actual availability depends on the MaiGPT mode settings in the backend.
{% 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>

Add the following script before the `</body>` tag on your website and configure `window.maiagentChatbotConfig`:

{% code title="Embed MaiGPT Window Mode" overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}
`enabledWindowModes` is an array where **the first element is the default window mode**. To use MaiGPT window mode, set `['maigpt']` as the first item.
{% endhint %}

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

Whether you set `targetElement` determines how MaiGPT is displayed:

{% tabs %}
{% tab title="Method 1: Embed in a Specified Container" %}
**Set `targetElement`**, and the SDK will mount the MaiGPT interface directly into that element:

```html
<div id="maigpt-container" style="width: 100%; height: 100vh;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: 'Your Web Chat ID',
    baseUrl: 'https://your-maiagent-domain/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
  }
</script>
<script src="https://your-maiagent-domain/js/embed.min.js"></script>
```

* The iframe fills the `targetElement` (if set to `<body>`, it fills the entire browser window)
* No floating button is displayed, and users cannot switch window modes — MaiGPT is the main page content
* `targetElement` accepts a **CSS selector string** (e.g., `'#maigpt-container'`) or an **HTMLElement object** (e.g., `document.getElementById('maigpt')`)
  {% endtab %}

{% tab title="Method 2: Bottom-Right Button with Full-Screen Opening" %}
**Do not set `targetElement`**, and the SDK will display a button in the bottom-right corner of the page. Clicking it opens MaiGPT in full-screen mode covering the entire screen, with a close button in the top-right corner:

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

* Suitable for scenarios where you don't want to modify the existing page layout and just want to add an entry point
* Click the bottom-right button to open MaiGPT in full screen; click the top-right close button to return to the button state
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
If the selector specified in `targetElement` cannot be found on the page, the SDK will automatically mount to `<body>` instead and output a warning message in the browser Console (initialization will not be interrupted).
{% endhint %}

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

Common fields for `window.maiagentChatbotConfig`:

<table><thead><tr><th width="200">Field</th><th width="120">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>webChatId</code></td><td>Required</td><td>Web Chat platform ID.</td></tr><tr><td><code>baseUrl</code></td><td>Recommended</td><td>MaiAgent service URL in the format <code>https://your-domain/web-chats</code>.</td></tr><tr><td><code>enabledWindowModes</code></td><td>Required (for this mode)</td><td>Array of enabled window modes, with the first item as the default. For MaiGPT mode, set to <code>['maigpt']</code>.</td></tr><tr><td><code>targetElement</code></td><td>Optional</td><td>The target element for mounting MaiGPT. Can be a CSS selector string or HTMLElement. When omitted, the bottom-right button full-screen mode is used (see Method 2 above).</td></tr><tr><td><code>maigptTitle</code></td><td>Optional</td><td>Brand title displayed in the top-left corner of the sidebar. Defaults to <code>MaiGPT</code> if not set.</td></tr><tr><td><code>contactId</code></td><td>Optional</td><td>Contact ID. Used to identify the end user.</td></tr><tr><td><code>locale</code></td><td>Optional</td><td>Interface language, such as <code>'zh-TW'</code> or <code>'en'</code>. Supports multiple languages.</td></tr></tbody></table>

{% hint style="warning" %}
The legacy `defaultWindowMode` field is **no longer recommended**. Please use `enabledWindowModes` instead (the first item in the array is the default).
{% endhint %}

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

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

The left side of MaiGPT window mode features a persistent conversation history list (ChatGPT style), 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 MaiGPT mode is enabled for the Web Chat in the backend, a **Deep Research** entry point appears in the input area. Users can click Deep Research before sending a message, and the AI assistant will perform deep research on that message.

The Deep Research status progresses through: `Not Used → Activated → In Progress → Completed / Failed`.

{% hint style="info" %}
Deep Research cannot be triggered again while in progress (In Progress); it can only be restarted after reaching "Completed" or "Failed" status.
{% endhint %}

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

Also available when MaiGPT mode is enabled, users can toggle the tools mounted to the AI assistant via the tool menu, controlling whether certain tools are used in the current conversation. Changes take effect immediately.

### 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 displayed depend on the Web Chat's backend settings and may include:

* **Text Language**: Switch the interface language
* **Text Size**: Small / Medium / Large (requires the font size switching feature to be enabled in the backend)
* **Theme Mode**: Auto / Light / Dark (requires theme mode switching to be enabled in the backend)
* **Voice Language**: Language used for voice input

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

{% hint style="info" %}

* **Responsive**: The MaiGPT layout supports desktop and mobile devices, and supports dark mode.
* **Compatible with existing modes**: MaiGPT is a newly added window mode and does not affect the behavior of existing `floating` / `sidebar` / `inline` modes. No adjustments are needed for existing integrations.
* **Advanced features depend on the backend**: Whether Deep Research and Tool Toggle are displayed depends on whether MaiGPT mode is enabled for the Web Chat in the backend. When not enabled, it can still be used as a pure conversation interface.
  {% 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/maiagent-user-guide/en/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.