Software Vendor Integration Guide: Embed AI Agents for Your Customers

An end-to-end guide for software vendors to embed Web Chat in their products and integrate permissions: embedding, batch provisioning, login synchronization, token refresh, and credential revocation a

This page is for software vendors that want to embed MaiAgent Web Chat in their products and integrate it with their own account and permission systems. After users sign in to your system, the AI Agent knows who they are, can retrieve their conversation history, and calls your system's APIs with their permissions.

The integration journey consists of five stages. This page explains what to do at each stage and in what order, with links to the corresponding technical documentation for details.

Integration Overview

The users on this page are your customers (represented as MaiAgent contacts). If you need to integrate employees of your company or your customers and make them MaiAgent organization members who can use MaiGPT, role permissions, and Credits, see Member Provisioning: SCIM, Invitations, and SSO.

There is only one core concept: Contact. Each user in your system corresponds to one contact in MaiAgent. Conversation history, personalized attributes, knowledge base query scope, and tool credentials are associated with the contact. Every permission-integration action ultimately maintains the mapping between your user and the contact, along with the contact's credentials. For an introduction to this concept, see Introduction to Contacts and Integration.

Frontend and Backend Responsibilities

Throughout the journey, your frontend is only responsible for loading the chat window. Your backend makes every request that includes a token or API key:

The setup-contact-credentials endpoint does not require an API key because it is public. bulk-import, PATCH, and DELETE all require Authorization: Api-Key authentication and must only be called from the backend.

Step 1: Embed Web Chat

First decide which AI Agent to embed. The embedded capabilities—such as image generation, web access, and tool calling—depend on the assistant settings behind Web Chat, not on the embedding method. The built-in organization product "MaiGPT" is only available to signed-in members, and its Web Chat cannot be embedded in an external system. Create an AI Agent for your product, set it to Agent mode, and attach the required tools. See Integrate MaiGPT: Choose the Right Assistant and Add the Required Capabilities.

Choose an embedding method based on your product format. Both methods use the same SDK and contact mechanism:

Format

Best for

Documentation

Chat bubble (floating/sidebar)

Supporting features such as customer service and consultation

Web Chat Embedding and SDK

MaiGPT mode (full ChatGPT-like interface)

Main page areas and site-wide AI entry points

Embed in MaiGPT Mode

For Web Chat with identity integration, we recommend configuring the allowed embedding domain list at this stage. The MaiAgent team currently configures it for you, so provide your domain list to your integration contact. Restricting the list limits which origins can call the identity synchronization API. See Allowed Embedding Domains.

Step 2: Initial Integration—Batch-Provision Existing Users

When integrating an existing system for the first time, provision contacts for all existing users in one batch. There are two options:

Method

Best for

Documentation

Batch import with Excel (POST /contacts/bulk-import/)

Large numbers of users (up to 10,000 rows per request), including knowledge query scopes and API tool credentials

Batch Import Contacts

Call the identity synchronization API for each user

Progressive provisioning through the login flow or small user counts

Batch-Provision Existing Users

It is fine if users' access tokens are not available during provisioning. Create the mappings first; the login flow in Step 4 will add token credentials the next time each user signs in.

Step 3: Create a Contact When Adding a User

After provisioning is complete, add an API call to your system's account creation flow so that every new user receives a corresponding contact immediately:

From the backend, call the identity synchronization API (setup-contact-credentials), using your system's user identifier as the sourceId.
Store the returned contactId in your member database. For a recommended field design, see Where to Integrate with the Login Flow.

sourceId is an idempotency key. Repeated calls with the same sourceId update the existing record instead of creating duplicates, so this step can safely coexist with Steps 2 and 4.

After every successful login and creation of an access token, have the backend call the same identity synchronization API again with the new token (mcpCredentials). This enables the AI Agent to call your system's APIs with that user's identity and permissions. Use the same approach when refreshing the token: call the API again. The same contact-and-tool pair is updated instead of duplicated. For a complete sequence diagram and important considerations, including asynchronous calls and preventing synchronization failures from blocking login, see Contact Identity Synchronization and Token Updates.

On the frontend, include the contactId when initializing Web Chat on the page. See Identify Users.

If the AI does not need to call your system's APIs and only needs to recognize the user, you can skip the backend entirely and include auth in the frontend config. See Choosing Between Frontend auth and Backend Integration for the tradeoffs.

Step 5: Logout and Credential Revocation

Perform both of the following at logout. They have different scopes:

Frontend: Call the SDK's signOut() method to return the chat window to an anonymous state.
Backend: Delete the contact's tool credentials so the AI can no longer call tools as that user.

For detailed APIs and a comparison of these operations, see Logout and Credential Revocation.