> 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/tech/en/serve/web-chat-sdk/web-chat-maigpt-mode.md).

# Embedding in MaiGPT Mode

Embed a complete ChatGPT-like MaiGPT conversation interface into your website or product, with both specified-container and floating full-screen layouts

MaiGPT mode provides a **complete ChatGPT-like conversation interface** (conversation history sidebar, conversation search, and settings panel). Unlike the existing bottom-right chat bubble (floating / sidebar), it is ideal as the main feature area of a page or a site-wide AI assistant entry point.

{% hint style="warning" %}
**MaiGPT mode only determines the appearance of the interface, not what the assistant can do.** It uses the instructions, model, and tools of whichever AI assistant's Web Chat it is applied to. To provide capabilities such as image generation and web access, first follow [Integrating MaiGPT: Choose the Right Assistant and Add Capabilities](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md) to set the assistant to Agent mode and attach tools. The organization's built-in MaiGPT product is available only to signed-in members, and its Web Chat cannot be embedded in external pages.
{% endhint %}

{% hint style="info" %}
This page focuses on settings specific to MaiGPT mode. For embedding fundamentals, the complete configuration reference, and the JavaScript API, see [Web Chat Embed & SDK](/tech/en/serve/web-chat-sdk.md). Common parameters not listed on this page (`auth`, `queryMetadata`, button appearance, and so on) also apply in MaiGPT mode.
{% endhint %}

## 1. Two Layout Modes <a href="#layout-modes" id="layout-modes"></a>

The same configuration supports two layouts, determined by whether `targetElement` is present:

```mermaid
flowchart TD
    A["The frontend loads embed.min.js<br/>and configures maiagentChatbotConfig<br/>（the first enabledWindowModes item is maigpt）"] --> B{"Does config have<br/>targetElement?"}
    B -->|Yes| C["Mode A: Embed in a specified container<br/>iframe fills 100% × 100% of the container<br/>Always visible"]
    B -->|No| D["Mode B: Floating button at the bottom-right<br/>Click → full-screen iframe + close button at the top-right"]
    C -.->|"selector does not match an element"| E["⚠️ fallback: covers the entire page<br/>with no close button"]
```

* **Mode A — Embed in a specified container**: MaiGPT remains visible in a specified `div` on the page (ideal as the system's main workspace)
* **Mode B — Floating button + full screen**: A floating button at the bottom-right opens MaiGPT in full screen when clicked (ideal as a site-wide AI assistant entry point)

Both behaviors are triggered by the same `maigpt` mode; the only difference is the `targetElement` field.

## 2. Mode A: Embed in a Specified Container <a href="#mode-a-container" id="mode-a-container"></a>

### Embed Code <a href="#mode-a-code" id="mode-a-code"></a>

```html
<!-- Prepare a container on the page and set its dimensions -->
<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>
```

{% hint style="info" %}
The `baseUrl` and SDK loader URL use the SaaS environment (`chat.maiagent.ai`) as an example. For private cloud / on-premises deployments, replace them with your environment's domain.
{% endhint %}

Actual embedded result (MaiGPT embedded in an enterprise portal, with `maigptTitle` set to the brand name):

<figure><img src="https://3415477754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNBTi475lqozGpB7xObpE%2Fuploads%2Fgit-blob-aab515bf01f9122d1b558aeaefcd1e59079466a0%2Fwebchat-maigpt-mode-a-container.png?alt=media" alt="Actual view of MaiGPT embedded in a specified container"><figcaption><p>Mode A: MaiGPT remains visible in the specified container on the page, with the conversation history sidebar on the left</p></figcaption></figure>

### Container Requirements <a href="#container-requirements" id="container-requirements"></a>

* **You must set the container height** (the iframe fills the container at `100%`; content is not visible if the container height is 0)
* `targetElement` accepts a **CSS selector string** (such as `'#maigpt-container'`) or an **HTMLElement object**
* If the container uses `position: static`, the SDK automatically changes it to `position: relative`; no action is usually required
* The iframe occupies only that container and does not affect other areas of the page

{% hint style="danger" %}
**Important: If the selector does not match an element, the fallback covers the entire page in full screen with no close button** (the console displays the warning `[maiagent] targetElement selector "..." not found, falling back to <body>`).

Confirm that: (1) the selector is spelled correctly; and (2) the container exists in the DOM when the SDK loads (place the loader `<script>` after the container and add `defer`; for dynamically rendered SPA pages, load the SDK only after the container mounts).
{% endhint %}

## 3. Mode B: Floating Button + Full Screen <a href="#mode-b-floating" id="mode-b-floating"></a>

### Embed Code <a href="#mode-b-code" id="mode-b-code"></a>

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

### Behavior <a href="#mode-b-behavior" id="mode-b-behavior"></a>

1. A floating button appears at the bottom-right of the page (using `primaryColor`)
2. Click the button → MaiGPT opens in a **full-screen iframe**, with an “×” close button at the top-right
3. Click “×” → the full-screen view collapses back to the floating button
4. When collapsed, the iframe is only hidden, not destroyed → **opening it again preserves the existing conversation state**

<figure><img src="https://3415477754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNBTi475lqozGpB7xObpE%2Fuploads%2Fgit-blob-2c2fb982ff4bef9a000a279fe72580b846b69ce3%2Fwebchat-maigpt-mode-b-demo.gif?alt=media" alt="Mode B demonstration: open the full-screen view with the floating button, submit a question and receive an AI response, then collapse it back to the button"><figcaption><p>Mode B demonstration: click the floating button → open in full screen → submit a question and receive a streaming AI response → click “×” to collapse it back to the button</p></figcaption></figure>

<details>

<summary>Static screenshots of both states</summary>

<figure><img src="https://3415477754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNBTi475lqozGpB7xObpE%2Fuploads%2Fgit-blob-a605610e4f3854e4ad4134d63dd03a69e7e18b36%2Fwebchat-maigpt-mode-b-button.png?alt=media" alt="Floating button state"><figcaption><p>Collapsed state: only the floating button appears at the bottom-right of the page without interfering with the original page</p></figcaption></figure>

<figure><img src="https://3415477754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNBTi475lqozGpB7xObpE%2Fuploads%2Fgit-blob-51d70d15376664ce3e569f562c98e75f67ea3927%2Fwebchat-maigpt-mode-b-fullscreen.png?alt=media" alt="Full-screen open state"><figcaption><p>Open state: MaiGPT appears in full screen and can be collapsed with the “×” at the top-right</p></figcaption></figure>

</details>

### Button Appearance Parameters (All Optional, Mode B Only) <a href="#mode-b-button-options" id="mode-b-button-options"></a>

| Parameter              | Default value                        | Description                                                 |
| ---------------------- | ------------------------------------ | ----------------------------------------------------------- |
| `primaryColor`         | `#1890ff`                            | Button background color; can be changed to your brand color |
| `buttonSize`           | `3rem`                               | Button size                                                 |
| `buttonRadius`         | `50%`                                | Button corner radius                                        |
| `buttonPositionBottom` | `1rem`                               | Distance from the bottom of the viewport                    |
| `buttonPositionRight`  | `1rem`                               | Distance from the right of the viewport                     |
| `buttonIcon`           | (built-in icon)                      | Image URL for a custom button icon                          |
| `boxShadow`            | `0.125rem 0.125rem 0.5rem #00000044` | Button shadow                                               |

## 4. Complete Parameter Reference <a href="#config-reference" id="config-reference"></a>

| Field                | Type                      | Required | Description                                                                                                                                                                                          |
| -------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webChatId`          | `string`                  | ✅        | WebChat ID                                                                                                                                                                                           |
| `baseUrl`            | `string`                  | ✅        | Web Chat service URL; for SaaS, use `https://chat.maiagent.ai/web-chats`                                                                                                                             |
| `enabledWindowModes` | `string[]`                | ✅        | Fixed at `['maigpt']` (the first element determines the mode)                                                                                                                                        |
| `targetElement`      | `string` or `HTMLElement` | ✖        | Value present → Mode A; no value → Mode B                                                                                                                                                            |
| `maigptTitle`        | `string`                  | ✖        | Brand title at the top-left of the sidebar; defaults to `MaiGPT` when unset                                                                                                                          |
| `primaryColor`       | `string`                  | ✖        | Primary interface color; can be changed to your brand color                                                                                                                                          |
| `locale`             | `string`                  | ✖        | Interface language; see [Locales](#locale). If omitted, the previously remembered locale or browser locale is used                                                                                   |
| `contactId`          | `string`                  | ✖        | MaiAgent contact ID used to identify the signed-in user; see [Identifying Users](#identify-user)                                                                                                     |
| `queryMetadata`      | `object` or `string`      | ✖        | Query metadata attached to the conversation; see [Knowledge Management Permissions Overview](/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) |

Unknown configuration fields do not cause errors, but the console displays an `[maiagent] Unknown config options: ...` warning to help identify typos.

## 5. Locales <a href="#locale" id="locale"></a>

```javascript
window.maiagentChatbotConfig = {
  // ...
  locale: 'en',
}
```

### Supported Locale Values <a href="#supported-locales" id="supported-locales"></a>

`zh-TW` (Traditional Chinese), `zh-CN` (Simplified Chinese), `en`, `ja`, `ko`, `th`, `vi-VN`, `id`, `fil-PH`, `ms-MY`, `km-KH`, `lo-LA`, `my-MM`

### Resolution Order <a href="#locale-priority" id="locale-priority"></a>

1. The `locale` in config (always takes effect and has the highest priority)
2. The locale the user last used in this browser (remembered)
3. The browser locale
4. Default: `zh-TW`

{% hint style="info" %}
`locale` affects only **interface text** (buttons, menus, and prompts), not the language of AI responses. Unsupported values are ignored, and the fallback order above is used.
{% endhint %}

## 6. Identifying Users (contactId) <a href="#identify-user" id="identify-user"></a>

To let the AI know “who is asking” (preserving conversation history across devices, providing personalized responses, and calling tools with the user's permissions), include `contactId` in config:

1. When the user signs in, the backend calls the [Contact Identity Sync API](/tech/en/serve/contacts/contact-credentials-sync.md) to obtain the `contactId`
2. The frontend adds the `contactId` to config:

```javascript
// Assume the user information (including contactId) is obtained from the API after sign-in
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  body: JSON.stringify({ username, password })
});
const userData = await loginResponse.json();

// Dynamically configure WebChat
window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://chat.maiagent.ai/web-chats',
  enabledWindowModes: ['maigpt'],
  targetElement: '#maigpt-container',
  contactId: userData.maiagentContactId,  // Obtained from the sign-in response
};
```

{% hint style="warning" %}
`contactId` must be the value associated with the signed-in user. Without a `contactId`, usage is anonymous: conversation history is retained per browser (and remains after refreshing the same browser), but it is not available across devices and personal data cannot be accessed using the user's identity.
{% endhint %}

## 7. FAQ <a href="#faq" id="faq"></a>

<details>

<summary>How is MaiGPT mode different from the original chat bubble (floating / sidebar)?</summary>

MaiGPT is a complete conversation workspace (conversation history sidebar, conversation search, and settings panel) that occupies the entire container or screen. The floating / sidebar modes are small windows overlaid in a corner of the page. Both use the same `enabledWindowModes` field: `['maigpt']` vs. `['floating', 'sidebar']`. MaiGPT mode does not provide window mode switching.

</details>

<details>

<summary>Where is conversation history stored?</summary>

It is retained in the MaiAgent backend according to WebChat's identity mechanism. Without a `contactId`, it is retained per browser (anonymous). With a `contactId`, it follows the contact and is available across devices.

</details>

<details>

<summary>Can I place two MaiGPT instances on the same page?</summary>

No. The SDK initializes only once per page, and duplicate loads are ignored.

</details>

<details>

<summary>How do I embed Mode A in an SPA (React / Vue)?</summary>

Load `embed.min.js` only after the container element has mounted (or set `window.maiagentChatbotConfig` at that point and dynamically insert the loader script). If the SDK runs before the container exists, it triggers the full-screen fallback (see [Container Requirements](#container-requirements)).

</details>

<details>

<summary>Can I change the “MaiGPT” name at the top-left to my own brand?</summary>

Yes. Add `maigptTitle: 'Acme GPT'` to config. It applies to both modes; when unset or given an empty string, it falls back to the default `MaiGPT`.

</details>


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/serve/web-chat-sdk/web-chat-maigpt-mode.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 `build a script that syncs our docs to a CMS` 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.