Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MaiGPT Mode Embedding

Embed a full ChatGPT-like MaiGPT conversation interface into your website or product, supporting both designated container and floating fullscreen layouts

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.

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.

1. Two Layout Modes

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

  • 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

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

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.

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

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

Ensure: (1) the selector is spelled correctly; (2) the container exists in the DOM when the SDK loads (place the loader <script> after the container with defer; for SPA dynamically rendered pages, load the SDK only after the container is mounted).

3. Mode B: Floating Button + Fullscreen

Embed Code

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

queryMetadata

object or string

✖

Query metadata attached to the conversation, see Knowledge Management Permissions Overview 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

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

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.

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 when the user logs in to obtain the contactId

  2. The frontend adds contactId to the config:

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.

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

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.

PreviousWeb Chat Embed & SDK
NextPage Context Injection

Last updated

Was this helpful?