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.

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

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. Common parameters not listed on this page (auth, queryMetadata, button appearance, and so on) also apply in MaiGPT mode.

1. Two Layout Modes

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

• 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

Embed Code

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

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.

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

Mode A: MaiGPT remains visible in the specified container on the page, with the conversation history sidebar on the left

Container Requirements

• 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

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

3. Mode B: Floating Button + Full Screen

Embed Code

<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

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

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

Static screenshots of both states

Collapsed state: only the floating button appears at the bottom-right of the page without interfering with the original page

Open state: MaiGPT appears in full screen and can be collapsed with the “×” at the top-right

Button Appearance Parameters (All Optional, Mode B Only)

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

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. 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
queryMetadata	object or string	✖	Query metadata attached to the conversation; see Knowledge Management Permissions Overview

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

5. Locales

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

Resolution Order

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

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.

6. Identifying Users (contactId)

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 to obtain the contactId

2. The frontend adds the contactId to config:

// 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
};

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.

7. FAQ

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

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.

Where is conversation history stored?

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.

Can I place two MaiGPT instances on the same page?

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

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

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

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

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.