> 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/authorization-integration/contacts.md).
# 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](/tech/en/authorization-integration/role-vs-contact.md)), and users are not aware of their existence — a Contact is simply an identity mapping between your system and MaiAgent.
{% tabs %}
{% tab title="Enterprise integration for external consumers" %}
{% endtab %}
{% tab title="Enterprise integration for internal employees" %}
{% endtab %}
{% endtabs %}
### 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](/tech/en/authorization-integration/contact-credentials-sync.md#sync-contact-profile) |
| Query metadata (`query_metadata`) | Restrict the knowledge base/document/tag scope this user can search | [Knowledge Management Permissions (Query Metadata)](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) |
| MCP/API tool credentials | Allow the AI to call external tools **with that user's identity and permissions** | [Contact Identity Sync and Token Update](/tech/en/authorization-integration/contact-credentials-sync.md) |
| 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](/tech/en/authorization-integration/contact-credentials-sync.md) |
| **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](https://docs.maiagent.ai/api/lian-luo-ren) |
| **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](#bulk-import) |
| **Backend GUI** | Small-scale, manual management scenarios | See [instructions below](#tu-xing-hua-jie-mian-jian-li-lian-luo-ren) |
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
```mermaid
sequenceDiagram
participant CU as User
participant ES as Enterprise System
participant MA as MaiAgent
CU ->> ES: Open website and log in (with enterprise system user ID)
ES ->> ES: Look up member data: existing Contact ID?
alt No mapping found
ES ->> MA: Create contact (Identity Sync API or POST /api/v1/contacts/)
MA -->> ES: Return contactId
ES ->> ES: Store contactId in member data table
end
ES ->> CU: Load Web Chat embed code (config includes contactId)
CU ->> MA: Web Chat initializes with this contact identity
MA -->> CU: Display this user's conversation history and corresponding permissions
```
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](/tech/en/api-integration/web-chat-sdk.md#identify-users)
{% hint style="info" %}
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](/tech/en/authorization-integration/contact-credentials-sync.md) — a single call completes both contact creation and credential binding.
{% endhint %}
## Contact Bulk Import (Excel)
For first-time integration with existing systems, use Excel to bulk create (or update) contacts:
{% stepper %}
{% step %}
### Download the Template
`GET /api/v1/contacts/bulk-import-template/` downloads an Excel template (with header row and sample rows).
{% endstep %}
{% step %}
### 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](/tech/en/authorization-integration/contact-credentials-sync.md#request-body)) |
| `Query Metadata` | | JSON object written to the contact's knowledge query scope; **empty cell = preserve existing value**. See [JSON Format Guide](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md) for formatting |
| `API Credentials` | | JSON array `[{"tool": "", "headers": {...}}]` to bind API tool credentials; empty = preserve existing credentials |
| {% endstep %} | | |
{% step %}
### 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 }`
{% endstep %}
{% endstepper %}
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
{% hint style="info" %}
Import only creates mappings and attributes; user Token credentials are still updated by the [Identity Sync API](/tech/en/authorization-integration/contact-credentials-sync.md) during each login flow.
{% endhint %}
## 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).
***
{% hint style="info" %}
The identity information configured on a contact is used to generate the corresponding `query_metadata` condition combinations during queries.
[**👉 Learn about Query Metadata**](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)
{% endhint %}
## 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
---
# 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.maiagent.ai/tech/en/authorization-integration/contacts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.