Contact Introduction and Integration

What Is a Contact?

A Contact represents an end user who interacts with the AI assistant. Once you map users from your own system to MaiAgent Contacts, the AI can identify "who is asking" — correctly retrieving that person's conversation history and permission settings, rather than someone else's.

Contacts do not need a MaiAgent account (this is the key difference from Members/Roles), and users are not aware of their existence — a Contact is simply an identity mapping between your system and MaiAgent.

Enterprise integration for external consumers

Enterprise integration for internal employees

What Can Be Attached to a Contact

Data	Purpose	Details
Basic info (name, email, avatar)	Displayed in the backend contact list and conversation logs	See API documentation below on this page
Custom attributes (metadata)	Background data such as department and membership tier — the AI reads and incorporates this into responses	Contact Identity Sync and Token Update
Query metadata (query_metadata)	Restrict the knowledge base/document/tag scope this user can search	Knowledge Management Permissions (Query Metadata)
MCP/API tool credentials	Allow the AI to call external tools with that user's identity and permissions	Contact Identity Sync and Token Update
Conversation history	Continue conversations across devices	Takes effect when the frontend includes contactId

Three Paths to Create and Sync Contacts

Method	Best For	Description
Identity Sync API (setup-contact-credentials)	Syncing on user login, binding tool credentials, bulk backfilling from existing systems	Idempotent (no duplicates for the same sourceId), no API Key required. Includes a version that Web Chat frontend auth calls automatically. Recommended for most integration scenarios — see Contact Identity Sync and Token Update
Contact API (POST /api/v1/contacts/)	Full backend control over the contact lifecycle, need to set query_metadata at creation time	Requires an API Key; use PATCH /api/v1/contacts/{contact_id}/ for updates (only updates the fields provided). See schema at API Documentation - Contacts
Bulk Import (Excel)	First-time integration with existing systems, backfilling large numbers of users at once	Limit of 10,000 rows; can include query_metadata and API tool credentials simultaneously — see details below
Backend GUI	Small-scale, manual management scenarios	See instructions below

All four paths create the same type of Contact and can be mixed (e.g., use bulk import for initial integration, then identity sync for daily logins).

Integration Flow

Three steps:

1. Check mapping: Use the enterprise system's user ID to look up member data and confirm whether a MaiAgent contact_id already exists

2. Create or update: If none exists, create one (and store the contact_id); when the user changes their name/email or permissions change, sync-update the contact (PATCH /api/v1/contacts/{contact_id}/), to ensure subsequent conversations have correct personalized content and permissions

3. Initialize Web Chat: Include contactId in the frontend config — see Web Chat Embedding and SDK

If your scenario involves "syncing contact creation and updating Token credentials when a user logs into the enterprise system" (e.g., allowing the AI to call MCP tools with the user's permissions), refer to Contact Identity Sync and Token Update — a single call completes both contact creation and credential binding.

Contact Bulk Import (Excel)

For first-time integration with existing systems, use Excel to bulk create (or update) contacts:

1

Download the Template

GET /api/v1/contacts/bulk-import-template/ downloads an Excel template (with header row and sample rows).

2

Fill In the Data

Field	Required	Description
Name(required)	✅	Contact display name
Email(required)	✅	One of the matching keys (case-insensitive)
Phone Number		Phone number
Source ID(required)	✅	User identifier from the enterprise system, one of the matching keys; use a non-guessable value (same as the Identity Sync API security note)
Query Metadata		JSON object written to the contact's knowledge query scope; empty cell = preserve existing value. See JSON Format Guide for formatting
API Credentials		JSON array [{"tool": "<tool ID>", "headers": {...}}] to bind API tool credentials; empty = preserve existing credentials

3

Upload and Import

POST /api/v1/contacts/bulk-import/ (multipart/form-data, Authorization: Api-Key authentication, same as the Contact API):

• file: The completed .xlsx file (limit: 10 MB, 10,000 rows)

• inboxes: List of inbox UUIDs — each imported contact's inbox set will be entirely replaced with this list; if you plan to use Web Chat login sync afterwards, make sure to include the corresponding Web Chat inbox

Response: { "created": N, "updated": M }

Import matching and update rules:

• Upsert using (Source ID, Email) as the key: if an existing contact matches, update the name/phone/Query Metadata (empty cells are left unchanged); if no match, create a new contact

• API Credentials upsert using (contact, tool) as the key; tool credentials not mentioned in the file are left untouched

• The entire batch completes within a single transaction: if any row has a format error (e.g., mismatched field names, invalid JSON), the entire batch is not written, and the error message indicates the row number

Import only creates mappings and attributes; user Token credentials are still updated by the Identity Sync API during each login flow.

Create Contacts via the GUI

1. Go to the contact management interface

2. Click Add Contact

The following page appears after clicking:

Enter the contact name, select the conversation platform, and create the contact. After creation, click the copy button to retrieve the contact ID (the contactId parameter for Web Chat initialization).

---

The identity information configured on a contact is used to generate the corresponding query_metadata condition combinations during queries.

👉 Learn about Query Metadata

Implementation Recommendations

1. Add a mapping field to the member data table (e.g., maiagent_contact_id, UUID, nullable), and record creation/update timestamps to ensure the enterprise user ID ↔ Contact ID mapping is traceable

2. Implement idempotency: Check the mapping before creating, or use the Identity Sync API directly (sourceId is idempotent — re-running does not create duplicate contacts)

3. Log API calls for easier troubleshooting of mapping issues

4. Call asynchronously: Execute contact-related API calls in parallel with other login flow requests; failures should not block user login — retry on the next login