Vendor Integration Guide (End-to-End)

End-to-end guide for software vendors embedding Web Chat into their product and completing authorization integration: embedding, batch backfill, login sync, Token refresh, and logout revocation

This page is for software vendors who want to embed MaiAgent Web Chat into their product and integrate it with their own account system for authorization. After a user logs into your system, the AI assistant recognizes who they are, can recall their conversation history, and can call your system's API with their permissions.

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

Integration Overview

The core concept is just one thing: Contact — each user in your system maps to a Contact in MaiAgent. A Contact carries conversation history, personalization attributes, knowledge base query scope, and tool credentials. Every action in the authorization integration is essentially maintaining the "your user <-> Contact" mapping and its credentials. For a conceptual introduction, see Contact Introduction and Integration.

What the Frontend and Backend Are Each Responsible For

Throughout this journey, your frontend is only responsible for "loading the chat window." All calls that involve Tokens or API Keys are initiated by your backend:

Among these, setup-contact-credentials does not require an API Key (public endpoint); bulk-import, PATCH, and DELETE all require Authorization: Api-Key authentication and can only be called from the backend.

Step 1: Embed Web Chat

Choose an embedding approach based on your product's form factor. Both use the same SDK and the same Contact mechanism:

Form	Best for	Documentation
Chat bubble (floating/sidebar)	Customer service, inquiries, and other auxiliary features	Web Chat Embed & SDK
MaiGPT mode (full ChatGPT-like interface)	Main functional area of the page, site-wide AI entry point	MaiGPT Mode Embed

For Web Chat instances that will use identity integration, it is recommended to configure the "Allowed Embed Origins" list at this point (currently set by the MaiAgent team on your behalf — provide the domain list to your integration contact). This restricts the origins that can call the Identity Sync API. See Allowed Embed Origins.

Step 2: Initial Integration — Batch Backfill Existing Users

When integrating an existing system for the first time, start by backfilling contacts for all current users. There are two approaches:

Approach	Best for	Documentation
Excel batch import (POST /contacts/bulk-import/)	Large user bases (up to 10,000 rows per batch), supports query metadata and API tool credentials simultaneously	Contact Batch Import
Per-record identity sync API calls	Gradual backfill through the login flow, or small volumes	Batch Backfill for Existing Users

It is fine if you do not have the user's Access Token at the time of backfill — just create the mapping first. Token credentials will be added by the login flow in Step 4 when each user next logs in.

Step 3: Create a Contact When Adding Users

After the backfill is complete, add a single API call to your "create account" flow so that new users get a corresponding Contact right away:

• Have the backend call the Identity Sync API (setup-contact-credentials), using your system's user identifier as the sourceId

• Store the returned contactId in your member data table (see the Login Flow Integration Point for a suggested field design)

sourceId is an idempotent key: repeated calls with the same sourceId only update the existing record and never create duplicates, so this step can safely coexist with Steps 2 and 4.

Step 4: Login and Token Refresh

Each time a login succeeds and an Access Token is generated, have the backend call the same identity sync API again, passing in the new Token (mcpCredentials). This allows the AI assistant to call your system's API with that user's identity and permissions. On Token refresh, use the same approach — just call the API again. The same (contact, tool) combination results in an update, not a duplicate. For the full sequence diagram and considerations (asynchronous calls, not blocking login on failure), see Contact Identity Sync and Token Update.

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

If you do not need the AI to call your system's API and only need to recognize users, you can skip the backend entirely: just include auth in the frontend config. For a comparison of the trade-offs, see Choosing Between Frontend Auth and Backend Integration.

Step 5: Logout and Credential Revocation

There are two things to do at logout, each with a different scope — it is recommended to do both:

• Frontend: Call the SDK's signOut() to return the chat window to anonymous state

• Backend: Delete the contact's tool credentials so the AI can no longer call tools as that user

For the detailed API and a comparison of the two, see Logout and Credential Revocation.

Integration Checklist

Stage	Action	Documentation
Setup	Embed Web Chat (standard or MaiGPT mode)	Web Chat Embed & SDK / MaiGPT Mode
Setup	Provide domain list to MaiAgent to configure "Allowed Embed Origins"	Allowed Embed Origins
Setup	Add maiagent_contact_id field to the member data table	Login Flow Integration Point
Setup	Batch backfill existing users	Contact Batch Import
Operations	Call the identity sync API in the account creation flow	Contact Identity Sync and Token Update
Operations	Update credentials in the login/Token refresh flow	When to Call
Operations	Revoke credentials in the logout flow	Logout and Credential Revocation
Advanced	Sync department, membership tier, and other personalization attributes	Sync Contact Profile
Advanced	Restrict each user's knowledge base retrieval scope via query metadata	Knowledge Management Permissions (Query Metadata)