> 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/api-integration/web-chat-sdk/web-chat-maigpt-mode.md).
# MaiGPT Mode Embedding
MaiGPT mode provides a **full ChatGPT-like conversation interface** (sidebar conversation history, conversation search, settings panel), distinct from the existing "bottom-right chat bubble" (floating / sidebar). It is ideal as a primary functional area on a page or as a site-wide AI assistant entry point.
{% hint style="info" %}
This page focuses on MaiGPT mode-specific settings. For the complete SDK initialization flow, events, and operation commands, refer to [Web Chat SDK Operation Commands](/tech/en/api-integration/web-chat-sdk.md).
{% endhint %}
## 1. Two Layout Modes
The same configuration supports two layouts, determined by whether `targetElement` is present:
```mermaid
flowchart TD
A["Frontend loads embed.min.js
Configure maiagentChatbotConfig
(first item of enabledWindowModes is maigpt)"] --> B{"Does config have
targetElement?"}
B -->|Yes| C["Mode A: Embed in designated container
iframe fills container 100% × 100%
Always visible"]
B -->|No| D["Mode B: Bottom-right floating button
Click → fullscreen iframe + top-right close button"]
C -.->|"selector cannot find element"| E["⚠️ Fallback: fullscreen covering entire page
with no close button"]
```
* **Mode A — Embed in Designated Container**: MaiGPT is always visible within a designated `div` on the page (ideal as the system's primary workspace)
* **Mode B — Floating Button + Fullscreen**: A bottom-right floating button that opens fullscreen when clicked (ideal as a site-wide AI assistant entry point)
Both behaviors are triggered by the same `maigpt` mode, differing only by the `targetElement` field.
## 2. Mode A: Embed in Designated Container
### Embed Code
```html
```
{% hint style="info" %}
`baseUrl` and the SDK Loader URL use the SaaS environment (`chat.maiagent.ai`) as an example. For private cloud or on-premises deployments, replace with your environment's domain.
{% endhint %}
Actual embed result (MaiGPT embedded within an enterprise portal, `maigptTitle` set to the brand name):
### Container Requirements
* **The container must have a defined height** (the iframe fills the container at `100%`; content is invisible when the container height is 0)
* `targetElement` accepts a **CSS selector string** (e.g., `'#maigpt-container'`) or an **HTMLElement object**
* If the container is `position: static`, the SDK automatically changes it to `position: relative` — no action is typically needed
* The iframe only occupies the container and does not affect other areas of the page
{% hint style="danger" %}
**Important: When the selector cannot find the element, it falls back to fullscreen covering the entire page with no close button** (the console will display a `[maiagent] targetElement selector "..." not found, falling back to ` warning).
Ensure: (1) the selector is spelled correctly; (2) the container exists in the DOM when the SDK loads (place the loader `
```
### Behavior Description
1. A floating button appears at the bottom-right of the page (color uses `primaryColor`)
2. Click the button → MaiGPT opens as a **fullscreen iframe** with a "×" close button in the top-right corner
3. Click "×" → fullscreen collapses back to the floating button
4. When collapsed, the iframe is only hidden, not destroyed → **reopening preserves the original conversation state**
Static screenshots of the two states
### Button Appearance Parameters (all optional, Mode B only)
| Parameter | Default | Description |
| ---------------------- | ------------------------------------ | -------------------------------------------------- |
| `primaryColor` | `#1890ff` | Button background color, can be set to brand color |
| `buttonSize` | `3rem` | Button size |
| `buttonRadius` | `50%` | Button border radius |
| `buttonPositionBottom` | `1rem` | Distance from viewport bottom |
| `buttonPositionRight` | `1rem` | Distance from viewport right |
| `buttonIcon` | (built-in icon) | Custom button icon image URL |
| `boxShadow` | `0.125rem 0.125rem 0.5rem #00000044` | Button shadow |
## 4. Complete Parameter Reference
| Field | Type | Required | Description |
| -------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webChatId` | `string` | ✅ | WebChat ID |
| `baseUrl` | `string` | ✅ | Web Chat service URL, SaaS is `https://chat.maiagent.ai/web-chats` |
| `enabledWindowModes` | `string[]` | ✅ | Fixed as `['maigpt']` (first element determines the mode) |
| `targetElement` | `string` or `HTMLElement` | ✖ | Present → Mode A; absent → Mode B |
| `maigptTitle` | `string` | ✖ | Brand title in the top-left of the sidebar; defaults to `MaiGPT` if not set |
| `primaryColor` | `string` | ✖ | Interface primary color, can be adjusted to brand color |
| `locale` | `string` | ✖ | Interface language, see [Locale](#locale) below; when not specified, determined by the last remembered language or browser language |
| `contactId` | `string` | ✖ | MaiAgent contact ID for identifying logged-in users, see [Identify User](#identify-user) |
| `queryMetadata` | `object` or `string` | ✖ | Query metadata attached to the conversation, see [Knowledge Management Permissions Overview](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) for details |
Unknown fields in the configuration will not cause errors, but the console will display an `[maiagent] Unknown config options: ...` warning to help check for typos.
## 5. Locale
```javascript
window.maiagentChatbotConfig = {
// ...
locale: 'en',
}
```
### Supported Locale Values
`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`
### Priority Order
1. `locale` in config (always takes effect, highest priority)
2. The language last used by the user in this browser (remembered)
3. Browser language
4. Default `zh-TW`
{% hint style="info" %}
`locale` only affects **interface text** (buttons, menus, prompts) and does not affect the language of AI responses. Unsupported values are ignored and fall back in order.
{% endhint %}
## 6. Identify User (contactId)
To let the AI know "who is asking" (preserve conversation history across devices, personalized responses, invoke tools with user permissions), include `contactId` in the config:
1. The backend calls the [Contact Credentials Sync API](/tech/en/authorization-integration/contact-credentials-sync.md) when the user logs in to obtain the `contactId`
2. The frontend adds `contactId` to the config:
```javascript
// Assume user info (including contactId) is obtained from the API after login
const loginResponse = await fetch('/api/auth/login', {
method: 'POST',
body: JSON.stringify({ username, password })
});
const userData = await loginResponse.json();
// Dynamically configure WebChat config
window.maiagentChatbotConfig = {
webChatId: 'your-web-chat-id',
baseUrl: 'https://chat.maiagent.ai/web-chats',
enabledWindowModes: ['maigpt'],
targetElement: '#maigpt-container',
contactId: userData.maiagentContactId, // Obtained from login response
};
```
{% hint style="warning" %}
`contactId` must be the value corresponding to the logged-in user. Without `contactId`, the session is anonymous: conversation history is retained per browser (persists after refreshing within the same browser), but cannot be shared across devices and cannot access personal data with user identity.
{% endhint %}
## 7. FAQ
What is the difference between MaiGPT mode and the original chat bubble (floating / sidebar)?
MaiGPT is a full conversation workspace (sidebar conversation history, conversation search, settings panel) that occupies the entire container or fullscreen. Floating / sidebar is a small window overlaid on the page corner. Both are switched using the same `enabledWindowModes` field: `['maigpt']` vs `['floating', 'sidebar']`. Window mode switching is not available in MaiGPT mode.
Where is conversation history stored?
It is retained on the MaiAgent backend based on the WebChat identification mechanism. Without `contactId`, it is stored per browser (anonymous). With `contactId`, it is associated with that contact and can be accessed across devices.
Can I place two MaiGPT instances on the same page?
No. The SDK initializes only once per page; duplicate loads are ignored.
How do I embed Mode A in an SPA (React / Vue)?
Ensure the container element is mounted before loading `embed.min.js` (or set `window.maiagentChatbotConfig` and dynamically insert the loader script at that time). If the SDK runs before the container exists, it triggers the fullscreen fallback (see [Container Requirements](#container-requirements)).
Can the "MaiGPT" name in the top-left be changed to my brand?
Yes. Add `maigptTitle: 'Acme GPT'` to the config. This applies to both modes. If not set or set to an empty string, it reverts to the default `MaiGPT`.
---
# 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/tech/en/api-integration/web-chat-sdk/web-chat-maigpt-mode.md?ask=&goal=
```
`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.