> 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, covering embedding, bulk backfilling, login synchronization, Token refresh, and credential revoc

This page is for software vendors embedding MaiAgent Web Chat in their own products and integrating permissions with their account systems. After users log in to your system, the AI Agent recognizes them, retrieves their conversation history, and calls your system's APIs with **their permissions**.

The integration journey has five stages. This page explains what to do at each stage and in what order, with links to the relevant 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["Backfill existing users in bulk"]
    end
    subgraph DAILY["Daily operations (account lifecycle)"]
        C["Create a contact when adding a user"] --> D["Update Token at login"]
        D --> E["Synchronize again on Token refresh"]
        E --> F["Revoke credentials at logout"]
    end
    ONCE --> DAILY
```

{% hint style="info" %}
The users on this page are **your customers** (mapped to MaiAgent contacts). If you are integrating **your company's or your customer's employees** so they become MaiAgent organization members (using MaiGPT, role permissions, and Credits quotas), see [Member Provisioning: SCIM / Invitations / SSO](/tech/en/identity-and-access/member-provisioning.md).
{% endhint %}

There is one core concept: **Contact**. Each user in your system maps to a MaiAgent contact. A contact holds conversation history, personalized attributes, knowledge base query scope, and tool credentials. Every permission integration action maintains this mapping between your users and contacts and their credentials. For an introduction, see [Contacts: Overview 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 only loads the chat window. Your backend initiates all calls containing a Token or API Key:

```mermaid
flowchart LR
    subgraph FE["Your frontend"]
        A["Embed code loads SDK<br/>config includes contactId"]
        B["Call signOut at logout"]
    end
    subgraph BE["Your backend"]
        C["Login/refresh: POST setup-contact-credentials"]
        D["Bulk backfill: 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
```

`setup-contact-credentials` requires no API Key (it is a public endpoint). `bulk-import`, `PATCH`, and `DELETE` require `Authorization: Api-Key` authentication and must 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.** Embedded capabilities (image generation, web access, and tool calls) depend on the Agent configuration behind Web Chat, rather than the embedding method. The organization's built-in MaiGPT product is available only to logged-in members, and its Web Chat **cannot** be embedded in external systems. Create an AI Agent for your product, set it to Agent mode, and attach the required tools. See [MaiGPT Integration: Choose the Right Agent and Add Capabilities](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md).
{% endhint %}

Choose the embedding method that fits your product. Both use the same SDK and contact mechanism:

| Form                                        | Suitable 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 (a full ChatGPT-like interface) | The main feature area of a page or a site-wide AI entry point | [Embedding in MaiGPT Mode](/tech/en/serve/web-chat-sdk/web-chat-maigpt-mode.md) |

{% hint style="info" %}
For Web Chat with identity integration, configure the Allowed Embedding Domains list at this stage (administrators enter it in the conversation platform's basic settings). This limits origins that can embed Web Chat and call the identity synchronization API. See [Allowed Embedding Domains](/tech/en/serve/web-chat-sdk.md#embed-origin-allowlist).
{% endhint %}

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

When integrating an existing system for the first time, backfill contacts for existing users first. There are two options:

| Method                                                  | Suitable for                                                                                                           | Documentation                                                                                      |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Excel bulk import** (`POST /contacts/bulk-import/`)   | Large numbers of users (up to 10,000 rows per request); can also import knowledge query scope and API tool credentials | [Bulk Contact Import](/tech/en/serve/contacts.md#bulk-import)                                      |
| **Call the identity synchronization API for each user** | Gradual backfilling through the login flow, or small numbers of users                                                  | [Backfilling Existing Users in Bulk](/tech/en/serve/contacts/contact-credentials-sync.md#backfill) |

You do not need users' Access Tokens at backfill time. Create the mappings first; the login flow in Step 4 adds Token credentials the next time each user logs in.

## Step 3: Create a Contact When Adding a User <a href="#step-create-user" id="step-create-user"></a>

After backfilling, add an API call to your system's account creation flow so each new user has a corresponding contact from the start:

* Call the [Identity Synchronization API (`setup-contact-credentials`)](/tech/en/serve/contacts/contact-credentials-sync.md) from the backend, using your system's user identifier as `sourceId`
* Store the returned `contactId` in your member table (for the recommended field design, see [Where to Integrate in the Login Flow](/tech/en/serve/contacts/contact-credentials-sync.md#login-flow))

`sourceId` is an idempotency key: repeated calls with the same `sourceId` only update the contact without creating duplicates. 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 each successful login generates an Access Token, the backend calls the same identity synchronization API again with the **new Token** (`mcpCredentials`). This allows the AI Agent to call your system's APIs with that user's identity and permissions. Use the same approach on Token refresh: call the API again. For the same contact and tool pair, it updates credentials rather than creating duplicates. For the full sequence diagram and considerations (asynchronous calls and failures that do not block login), see [Contact Identity Synchronization and Token Updates](/tech/en/serve/contacts/contact-credentials-sync.md).

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

{% hint style="info" %}
If you only need the AI to recognize users without calling your system's APIs, you can skip the backend entirely: include `auth` in the frontend config. For the tradeoffs, see [Choosing Frontend auth or Backend Integration](/tech/en/serve/contacts/contact-credentials-sync.md#frontend-vs-backend).
{% endhint %}

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

At logout, take two actions with different scopes. We recommend both:

* **Frontend**: Call the SDK's `signOut()` to return the chat window to an anonymous state
* **Backend**: Delete the contact's tool credentials so the AI immediately loses the ability to call tools as that user

For API details and a comparison of the two actions, 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 your own AI Agent: Agent mode + tools such as image generation + Web Chat | [MaiGPT Integration: Choose the Right Agent and Add 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      | Enter Allowed Embedding Domains in the conversation platform's basic settings    | [Allowed Embedding Domains](/tech/en/serve/web-chat-sdk.md#embed-origin-allowlist)                                                                          |
| Setup      | Add a `maiagent_contact_id` field to the member table                            | [Where to Integrate in the Login Flow](/tech/en/serve/contacts/contact-credentials-sync.md#login-flow)                                                      |
| Setup      | Backfill existing users in bulk                                                  | [Bulk Contact Import](/tech/en/serve/contacts.md#bulk-import)                                                                                               |
| Operations | Call the identity synchronization API in the account creation flow               | [Contact Identity Synchronization and Token Updates](/tech/en/serve/contacts/contact-credentials-sync.md)                                                   |
| Operations | Update credentials in the login/Token refresh flow                               | [When to Call](/tech/en/serve/contacts/contact-credentials-sync.md#when-to-call)                                                                            |
| Operations | Revoke credentials in the logout flow                                            | [Logout and Credential Revocation](/tech/en/serve/contacts/contact-credentials-sync.md#logout-revoke)                                                       |
| Advanced   | Synchronize personalized attributes such as department and membership tier       | [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)](/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 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 `automate deployments from our CI pipeline` 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.