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.

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 to complete the basic setup first.

Where to Start? Get the Embed Code

The embed code on this page is obtained from the Chat Platform Settings. Follow the steps below:

1

Access the Chat Platform Settings

Go to "Customer Service > Chat Platforms", select your Web Chat platform, and click "Operations" to enter the settings page.

2

Click "Embed"

In Basic Settings, find the Public Access URL section and click the "Embed" button to open the embed window.

3

Select the MaiGPT Embed Method

Switch between three embed methods at the top of the window and select "MaiGPT":

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).

4

Copy the Code and Paste It into Your Website

The code preview on the right updates in real time based on the left-side settings. Click "Copy" to get the embed code as shown below:

<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 below.

1. What is MaiGPT Window Mode?

The Web Chat SDK provides four window modes, specified via the enabledWindowModes setting in the embed configuration:

Window Mode	Description
floating	Default mode. A floating button in the bottom-right corner that expands into a conversation window when clicked. Suitable for general customer service.
sidebar	Sidebar mode. A conversation window slides out from the side of the page.
inline	Inline mode. The conversation window is embedded within the page content area.
maigpt	The mode described on this page. A full ChatGPT-style interface with the conversation history list expanded by default, suitable as the primary page UI.

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 and Tool Toggle can be enabled based on backend settings

2. Prerequisites

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 "MaiGPT" 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).

3. (Optional) Enable MaiGPT mode in the backend: If you want to make Deep Research and 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 "Embed" button on the chat platform settings page to get the embed code.

MaiAgent cloud service (chat.maiagent.ai) has MaiGPT window mode built in and is ready to use. For private deployments or older versions, the "MaiGPT" option may not appear in the embed window. Please confirm with MaiAgent and upgrade to a supported version.

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.

3. Embed Setup

1. Basic Embed Code

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

Embed MaiGPT Window Mode

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

enabledWindowModes is an array where the first element is the default window mode. To use MaiGPT window mode, set ['maigpt'] as the first item.

2. Two Embed Methods

Whether you set targetElement determines how MaiGPT is displayed:

Method 1: Embed in a Specified Container

Set targetElement, and the SDK will mount the MaiGPT interface directly into that element:

<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'))

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:

<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

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).

4. Configuration Parameter Reference

Common fields for window.maiagentChatbotConfig:

Field	Required	Description
webChatId	Required	Web Chat platform ID.
baseUrl	Recommended	MaiAgent service URL in the format https://your-domain/web-chats.
enabledWindowModes	Required (for this mode)	Array of enabled window modes, with the first item as the default. For MaiGPT mode, set to ['maigpt'].
targetElement	Optional	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).
maigptTitle	Optional	Brand title displayed in the top-left corner of the sidebar. Defaults to MaiGPT if not set.
contactId	Optional	Contact ID. Used to identify the end user.
locale	Optional	Interface language, such as 'zh-TW' or 'en'. Supports multiple languages.

The legacy defaultWindowMode field is no longer recommended. Please use enabledWindowModes instead (the first item in the array is the default).

5. Interface and Features

1. Conversation History List

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

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.

Deep Research cannot be triggered again while in progress (In Progress); it can only be restarted after reaching "Completed" or "Failed" status.

3. Tool Toggle

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

Click Settings 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

6. Notes

• 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.