> 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/serve/vendor-integration-guide.md).

# 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 <a href="#overview" id="overview"></a>

```mermaid
flowchart LR
    subgraph ONCE["One-time setup"]
        A["Embed Web Chat"] --> B["Batch-provision existing users"]
    end
    subgraph DAILY["Daily operations (account lifecycle)"]
        C["Create a contact when adding a user"] --> D["Update the token at login"]
        D --> E["Synchronize again when the token is refreshed"]
        E --> F["Revoke credentials at logout"]
    end
    ONCE --> DAILY
```

{% hint style="info" %}
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](/tech/en/identity-and-access/member-provisioning.md).
{% endhint %}

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](/tech/en/serve/contacts.md).

### Frontend and Backend Responsibilities <a href="#frontend-backend-split" id="frontend-backend-split"></a>

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:

```mermaid
flowchart LR
    subgraph FE["Your frontend"]
        A["Embed code loads the SDK<br/>config includes contactId"]
        B["Call signOut at logout"]
    end
    subgraph BE["Your backend"]
        C["Login/refresh: POST setup-contact-credentials"]
        D["Batch provisioning: POST bulk-import"]
        E["Data synchronization: PATCH contacts"]
        F["Logout: DELETE tool credentials"]
    end
    subgraph MA["MaiAgent"]
        G["Chat window<br/>chat.maiagent.ai"]
        H["API<br/>api.maiagent.ai"]
    end
    A --> G
    B --> G
    C --> H
    D --> H
    E --> H
    F --> H
```

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 <a href="#step-embed" id="step-embed"></a>

{% hint style="warning" %}
**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](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md).
{% endhint %}

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](/tech/en/serve/web-chat-sdk.md)                |
| MaiGPT mode (full ChatGPT-like interface) | Main page areas and site-wide AI entry points                 | [Embed in MaiGPT Mode](/tech/en/serve/web-chat-sdk/web-chat-maigpt-mode.md) |

{% hint style="info" %}
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](/tech/en/serve/web-chat-sdk.md#embed-origin-allowlist).
{% endhint %}

## Step 2: Initial Integration—Batch-Provision Existing Users <a href="#step-backfill" id="step-backfill"></a>

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](/tech/en/serve/contacts.md#bulk-import)                                |
| **Call the identity synchronization API for each user**     | Progressive provisioning through the login flow or small user counts                                              | [Batch-Provision Existing Users](/tech/en/serve/contacts/contact-credentials-sync.md#backfill) |

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 <a href="#step-create-user" id="step-create-user"></a>

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`)](/tech/en/serve/contacts/contact-credentials-sync.md), 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](/tech/en/serve/contacts/contact-credentials-sync.md#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.

## Step 4: Login and Token Refresh <a href="#step-login-refresh" id="step-login-refresh"></a>

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](/tech/en/serve/contacts/contact-credentials-sync.md).

On the frontend, include the `contactId` when initializing Web Chat on the page. See [Identify Users](/tech/en/serve/web-chat-sdk.md#identify-users).

{% hint style="info" %}
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](/tech/en/serve/contacts/contact-credentials-sync.md#frontend-vs-backend) for the tradeoffs.
{% endhint %}

## Step 5: Logout and Credential Revocation <a href="#step-logout" id="step-logout"></a>

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](/tech/en/serve/contacts/contact-credentials-sync.md#logout-revoke).

## Integration Checklist <a href="#checklist" id="checklist"></a>

| Stage      | Action                                                                                              | Documentation                                                                                                                                                        |
| ---------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Setup      | Create an AI Agent: enable Agent mode, attach image-generation and other tools, and create Web Chat | [Integrate MaiGPT: Choose the Right Assistant and Add the Required Capabilities](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md)                |
| Setup      | Embed Web Chat (standard or MaiGPT mode)                                                            | [Web Chat Embedding and SDK](/tech/en/serve/web-chat-sdk.md)/[MaiGPT Mode](/tech/en/serve/web-chat-sdk/web-chat-maigpt-mode.md)                                      |
| Setup      | Give MaiAgent your domain list for the allowed embedding domain configuration                       | [Allowed Embedding Domains](/tech/en/serve/web-chat-sdk.md#embed-origin-allowlist)                                                                                   |
| Setup      | Add a `maiagent_contact_id` field to the member database                                            | [Where to Integrate with the Login Flow](/tech/en/serve/contacts/contact-credentials-sync.md#login-flow)                                                             |
| Setup      | Batch-provision existing users                                                                      | [Batch Import Contacts](/tech/en/serve/contacts.md#bulk-import)                                                                                                      |
| Operations | Call the identity synchronization API during account creation                                       | [Contact Identity Synchronization and Token Updates](/tech/en/serve/contacts/contact-credentials-sync.md)                                                            |
| Operations | Update credentials at login and token refresh                                                       | [When to Call](/tech/en/serve/contacts/contact-credentials-sync.md#when-to-call)                                                                                     |
| Operations | Revoke credentials at logout                                                                        | [Logout and Credential Revocation](/tech/en/serve/contacts/contact-credentials-sync.md#logout-revoke)                                                                |
| Advanced   | Synchronize personalized attributes such as department and membership level                         | [Synchronize Contact Data](/tech/en/serve/contacts/contact-credentials-sync.md#sync-contact-profile)                                                                 |
| Advanced   | Use query metadata to limit each user's knowledge base retrieval scope                              | [Knowledge Management Permissions (Query Metadata) Overview](/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) |


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/serve/vendor-integration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.