Integrate MaiGPT: Choose the Right Assistant and Add the Capabilities You Need

Integrate MaiGPT into your system: understand the difference between the MaiGPT product and MaiGPT window mode, build your own agent with image generation and other tools for customers, or embed the M

On the MaiAgent platform, “MaiGPT” refers to two different things. Distinguishing them before integration will save most of the back-and-forth:

	MaiGPT product (organization's built-in agent)	MaiGPT window mode (a Web Chat SDK layout)
What it is	An enterprise AI workspace automatically provided to every organization and centrally maintained by MaiAgent. It includes AI image generation, Deep Research, connectors, and other capabilities. See What is MaiGPT?	A full ChatGPT-like interface enabled with enabledWindowModes: ['maigpt'], including a conversation history sidebar, search, and settings. It is purely a frontend presentation mode.
Who can use it	Organization members after signing in (web, iOS App, LINE, and Microsoft Teams). Access is controlled by role permissions.	Any Web Chat can use it, including anonymous visitors and identified contacts.
Can it be embedded in your system?	Only for organization members: creating a conversation requires a member identity with the maigpt_access permission. Embedding it directly with its Web Chat ID returns 400 You do not have permission to use MaiGPT. To embed it for members, use member identity embedding, with your backend issuing member tokens.	Yes: this is covered in Sections 2 and 3 of this page.
Can it be customized?	No: instructions, models, tools, and skills are configured centrally by the platform. Organizations can only restrict access through role permissions.	Yes: the interface runs an AI Agent you create, so you control its instructions, models, tools, and knowledge bases.

Conclusion: There are two use cases. For your customers or other non-organization members, create your own AI Agent, add the required tools, and embed it using MaiGPT window mode (Sections 2 and 3). For organization members who need the capabilities of the MaiGPT product itself—image generation, Deep Research, connectors, and role permissions—use member identity embedding (Section 5), with your backend issuing short-lived member tokens.

1. Common Symptoms

What you see	Cause	Solution
The interface looks like MaiGPT, but responses behave like regular Chat. When asked to generate an image, the AI says, “I can't generate images.”	A regular AI Agent is embedded, and either (1) its reply mode is not Agent mode, or (2) it does not have an image generation tool or other required tools.	Follow Section 2 to switch to Agent mode and add tools.
The chat window does not open and shows “Failed to create conversation (HTTP 400),” while the API returns You do not have permission to use MaiGPT.	The embedded Web Chat ID belongs to the organization's built-in MaiGPT product, but the visitor does not have a member identity.	For customers → use the Web Chat ID of a custom agent (Section 3); for members → provide a member token as described in member identity embedding.
The AI Agent list API in the admin console does not return MaiGPT.	GET /api/v1/chatbots/ only lists agents created by the organization; the MaiGPT product is not included.	This is expected. Integrations should always target a custom agent.

Embedding the organization's built-in MaiGPT Web Chat: the visitor is not a signed-in member, so conversation creation is rejected (HTTP 400)

2. Create an AI Agent That Can Generate Images and Use Tools

The steps below use AI image generation as an example. Add other capabilities—web search, web fetch, MCP tools, or your own API tools—in the same way.

1

Create an AI Agent

In the admin console, go to “AI Features → AI Assistants,” create a new AI Agent, and configure its role instructions and model. See Create an AI Assistant in the user guide.

2

Switch the Reply Mode to “Agent Mode”

Open the agent's “Reply Mode Settings” and change the reply mode to Agent mode.

Only Agent mode invokes tools. The default “RAG Q&A” mode responds quickly but does not use any tools—the most common reason an agent still does not generate images after an image tool has been added.

3

Add Tools

Open the agent's “Tools” page, click “Select Tools,” and select the required built-in tools, such as:

• Image generation: Global_Image_Tool_OpenAI_GPT_Image_2, Global_Image_Tool_Gemini_3, and others (select one; see Built-in AI Image Generation Tools for model differences)

• Web search: Global_Tavily_Search_Tool

• Web fetch: Global_Web_Fetch_Tool

• An API tool for your own system or an MCP tool

For complete instructions, see Configure Tools for an AI Assistant in the user guide.

4

Create a Web Chat Conversation Platform

Under “Customer Service Conversations → Conversation Platforms,” add a Web Chat for this agent and obtain its webChatId. See Integrate a Conversation Platform: Website.

Automate with the API (for ISVs Provisioning on Behalf of Customers)

Each of the four steps above has a corresponding API, allowing software vendors to complete provisioning programmatically when onboarding each customer. See Quick Start for authentication and instructions on obtaining an API Key.

# 1. List built-in tools and obtain the ID of an image generation tool
GET /api/v1/tools/

# 2. Create an AI Agent: use Agent reply mode and attach tools
POST /api/v1/chatbots/
{
  "name": "Acme GPT",
  "instructions": "You are Acme's AI assistant. Please respond in English.",
  "largeLanguageModel": "<LLM id>",
  "embeddingModel": "<embedding model id>",
  "rerankerModel": "<reranker model id>",
  "replyMode": "agent",
  "tools": ["<ID of Global_Image_Tool_OpenAI_GPT_Image_2>"]
}

# 3. Create a Web Chat conversation platform for the agent (channel.id in the response is the webChatId)
POST /api/v1/inboxes/
{
  "name": "Acme GPT",
  "chatbot": "<chatbot id>",
  "channelType": "web",
  "channel": {
    "name": "Acme GPT",
    "theme": { "primaryColor": "#1890ff", "...": "..." },
    "darkTheme": { "primaryColor": "#404040", "...": "..." }
  }
}

• To change the mode or add tools to an existing agent, use PATCH /api/v1/chatbots/{id}/. Pass the complete array of tool IDs in tools (the entire array is replaced).

• theme and darkTheme are required. To obtain the field list, first use GET /api/v1/web-chats/{existing webChatId}/ and copy an existing configuration.

• Always create a Web Chat through POST /api/v1/inboxes/ together with its inbox. Calling POST /api/v1/web-chats/ directly creates an orphaned Web Chat without an inbox, which returns 404 when embedded.

3. Embed Using MaiGPT Window Mode

Take the webChatId from Section 2 and place the embed code from Embed with MaiGPT Mode on your page:

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<webChatId created in Section 2>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    maigptTitle: 'Acme GPT',
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

To let the agent identify signed-in users and call your APIs with their permissions, add contactId or auth as described in the Software Vendor Integration Guide.

Verify: The Same Embed Code Before and After Adding Capabilities

The two images below show the same AI Agent with the same embed code. The only difference is the “reply mode + tools” configuration:

Before: RAG Q&A mode without tools

The interface uses MaiGPT window mode, but the agent says, “I can't generate, create, or produce images.”

After: Agent mode with an image generation tool

With the same embed code, the agent invokes the image generation tool and displays the image directly in the conversation.

4. When to Use the MaiGPT Product Itself

If you need “a ChatGPT-level internal assistant for our employees,” rather than “an assistant embedded in our product for our customers,” using the MaiGPT product directly is the simplest option:

• Employees can use it after signing in as organization members. Entry points include the web app, iOS App, LINE, and Microsoft Teams.

• Image generation, Deep Research, connectors, and skills are built in. Administrators only need to use role permissions to determine who can use each capability.

• To add organization-specific knowledge, make the relevant knowledge bases visible to members. You do not need to create a separate agent.

To embed MaiGPT in your own system when users are organization members, follow the member identity embedding flow in Section 5. If any of the following apply—“for non-members (customers or subscribers),” “needs your own API tools,” or “requires custom instructions or models”—use the custom-agent approach in Sections 2 and 3.

5. Member Identity Embedding: Embed the MaiGPT Product in Your System for Organization Members

For an end-to-end walkthrough, see Add MaiGPT to Your System. This section provides a complete reference for each parameter.

Use this approach when users of your system are also members of the MaiAgent organization—for example, in an enterprise portal, an employee workspace, or an ISV-managed internal enterprise system—and they need the MaiGPT product itself rather than a separate agent. Your backend uses an organization API Key to issue a short-lived token for the signed-in member. The frontend then embeds the MaiGPT Web Chat using the SDK's existing member identity injection settings.

Prerequisites

• An organization API Key whose owner is the organization owner or has the “Organization Overview” management permission. Only a key issued by someone who can manage members can issue tokens on their behalf. See Quick Start for instructions on obtaining an API Key.

• The user to embed is already a member of the organization and has MaiGPT access through their role (MaiGPT Role Permissions). Token issuance returns 404 if the member does not exist; it does not provision the member automatically. For member provisioning options—SCIM provisioning API, admin invitation, and SSO—see Member Provisioning. The standard approach for an ISV-managed deployment is to provision members through SCIM and then issue tokens as described in this section.

• The MaiGPT Web Chat ID: in the response from GET /api/v1/web-chats/, use the entry named MaiGPT whose accessType is web.

Step 1: Issue a Member Token from the Backend

Create a backend endpoint that only signed-in users can call—for example, GET /maigpt-token. It calls MaiAgent internally, and the frontend SDK calls it whenever needed:

curl -X POST https://api.maiagent.ai/api/v1/members/embed-tokens/ \
  -H "Authorization: Api-Key <your organization API Key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Provide either email or memberId, but not both (memberId is the MaiAgent member ID). A successful request returns 201 (expiresAt is an epoch timestamp in milliseconds):

{
  "accessToken": "<short-lived member JWT>",
  "organizationId": "8d2f...-...",
  "expiresAt": 1789906401000,
  "member": {
    "id": "c1a4...-...",
    "userId": "5e77...-...",
    "email": "[e-mail]",
    "name": "Alice"
  }
}

Status code	Meaning
400	Both email and memberId were provided, or neither was provided.
401	The request was not authenticated with an Api-Key (member sign-in tokens and anonymous requests are rejected).
403	The API Key owner is neither the organization owner nor a user with organization management permission.
404	The specified member does not exist, is disabled, or does not belong to the organization associated with the key.

Token rules: The lifetime is fixed at 15 minutes. No refresh token is issued, and the lifetime cannot be extended. You can issue tokens for the same member repeatedly; earlier tokens remain valid until they expire. This token can only be used for Web Chat conversations (the three calls for creating conversations, sending messages, and continuing after handoff). Using it for any /api/v1/ endpoint, any other conversation management action, or WebSocket access always returns 401. Every issuance is recorded in the organization's API request logs for auditing (the token in the response is not logged).

Step 2: Provide the SDK with a Token Retrieval Function

The embed configuration is the same as in Section 3, with an additional auth.getToken. Replace webChatId with the MaiGPT Web Chat ID:

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<MaiGPT Web Chat ID>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    auth: {
      // Called once during SDK initialization and again whenever the token is about to expire; renewal is automatic, so you do not need a timer
      getToken: async () => {
        const res = await fetch('/maigpt-token', { credentials: 'include' })  // Your backend; see Step 1
        const { accessToken, organizationId, member } = await res.json()
        return { accessToken, organizationId, sourceId: member.userId }
      },
    },
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

Fields returned by getToken:

Field	Required	Description
accessToken	✅	The accessToken returned in Step 1.
organizationId	✅	The organizationId returned in Step 1.
sourceId	Recommended	The member.userId returned in Step 1. You can also set it at auth.sourceId; if both locations provide it, auth.sourceId takes precedence.

auth must be defined in maiagentChatbotConfig so the SDK knows to wait for member identity injection before creating the first conversation. If you call MaiAgent.auth.setup() only after the SDK has loaded, the first conversation may be created anonymously before identity injection and be rejected.

sourceId must be the member.userId from the response—not member.id or the user ID from your own system. MaiGPT uses it to associate conversations with members. If it is incorrect, the conversation becomes anonymous and the member cannot see their MaiGPT history.

How Expiration and Renewal Work

• Tokens expire after 15 minutes. The iframe notifies the SDK 60 seconds before expiration. The SDK calls getToken again to obtain and inject a new token, and continues the same conversation without reloading the page or iframe, transparently to the user.

• Every getToken call must request a new token from MaiAgent; do not return a cached value. The SDK schedules the next renewal based on the token's own remaining lifetime. Returning the same token as before is treated as a failure and triggers the retry flow described below.

• If getToken fails—for example, because the user has signed out or the backend returns 401—the SDK retries after 30, 60, and 120 seconds. If all retries fail, it stops and logs an error to the console. After the token expires, the next message fails to send and displays the existing error notification. The conversation and previously sent messages remain visible.

• When the user signs out of your system, call MaiAgent.auth.signOut(). The SDK clears the identity and stops renewal. Any issued token may remain valid for up to 15 minutes. When another user signs in, call MaiAgent.auth.setup() again; any renewal in progress for the previous user is invalidated.

• If the Web Chat has Source ID signature verification enabled, the signature is single-use. The SDK does not reuse the initial ts/sig during renewal, so have getToken return a new signature along with the token ({ accessToken, ts, sig }).

• If you provide a static auth.accessToken instead of using getToken, the SDK does not renew it. You must call MaiAgent.auth.setup() again after 15 minutes.

Choosing Between These Approaches

	Embed MaiGPT with a member identity (this section)	Custom agent + MaiGPT window mode (Sections 2 and 3)
Users	Must be organization members	Anyone (customers, subscribers, or anonymous visitors)
Capabilities	Complete MaiGPT feature set: image generation, Deep Research, connectors, and skills, subject to role permissions	The tools and knowledge bases you select
Custom instructions/models	No (centrally managed by the platform)	Yes
Backend work	One endpoint that proxies the token issuance API	None (optional contact identity synchronization)
Billing attribution	The member's quota	The agent/Web Chat

6. Frequently Asked Questions

I see a Web Chat named MaiGPT under “Conversation Platforms” in the admin console. Can I use its embed code?

Not directly. It is the conversation platform for the organization's built-in MaiGPT product and only serves organization members. When embedded on an external page, visitors do not have member identities, so conversation creation is rejected (HTTP 400 You do not have permission to use MaiGPT.). If users are already organization members, follow member identity embedding and have your backend issue member tokens before embedding it. Otherwise, add a separate Web Chat for a custom AI Agent.

Can a custom agent use the image generation, Deep Research, and connector capabilities available in the MaiGPT product?

• Built-in tools such as image generation, web search, and web fetch are available to all agents. Select them on the agent's “Tools” page.

• Connectors such as Notion, Slack, and Google Drive can be linked to custom agents in the agent settings.

• Deep Research and tool toggles can be made available to end users in MaiGPT window mode. The agent owner must enable MaiGPT mode for that Web Chat in the admin console. See Embed with MaiGPT Window Mode in the user guide.

The agent is already in Agent mode and has an image generation tool, but it still does not generate images. What should I check?

Check the following in order: (1) whether the webChatId in the embed code belongs to the Web Chat attached to this agent (one agent can have multiple conversation platforms); (2) whether the organization's plan and quota are sufficient (image generation is charged per image, and messages cannot be sent when the quota is insufficient); and (3) whether the role instructions contain constraints such as “respond with text only” that prevent tool use. Tool setting changes also apply to existing conversations, so you do not need to start a new conversation.

How does MaiGPT window mode differ from floating/sidebar mode?

Only the interface layout differs. They use the same underlying AI Agent and contact mechanism. See Embed with MaiGPT Mode.