> 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/maiagent-user-guide/maiagent-user-guide-en/org/contact.md).

# Contacts

## What Is a Contact?

A **Contact** is one of MaiAgent's core features, functioning like an enterprise's "customer card file." It allows businesses to create a dedicated identity profile for each customer, ensuring a personalized service experience in every conversation.

{% hint style="info" %}
**Simple explanation:**

A contact is like a "customer data card" that records the customer's identity and permissions. When a customer visits, the AI Assistant uses this data card to determine what services and content to provide.
{% endhint %}

<figure><img src="/files/rXObrxHMxTbVp1Dwf3wr" alt=""><figcaption><p>Identity recognition example</p></figcaption></figure>

Imagine when a customer interacts with you through a website chatroom, the system can immediately identify "This is Mr. Zhang, he is a VIP member" or "This is a new visitor, only partial documents should be accessible," and provide the corresponding service content and permissions accordingly.

## Why Do You Need the Contact Feature?

### **Personalized Service Experience**

Every customer has unique needs and backgrounds. The contact feature enables the AI Assistant to:

* Remember conversation history with the customer
* Provide appropriate information based on the customer's identity
* Avoid repeatedly asking for already known information

### **Precise Permission Management**

Different customers should see different content:

* VIP members can view exclusive offers
* Regular members see standard service content
* Visitors can only access public information

### **Data Security Protection**

* Ensure customers can only access their own data, preventing information leaks.

## How Do Contacts Work?

When a user opens a conversation, the conversation request is sent to the enterprise's internal system for processing, which determines whether existing member information is available. Based on this determination, the system finds or creates a contact (anonymous or non-anonymous). Regardless of the path taken, a personalized conversation is ultimately initiated, ensuring every user receives an appropriate personalized experience.

Contact workflow diagram

<figure><img src="/files/bH9zl2nkmqJthI0y6cGE" alt=""><figcaption><p>Contact workflow diagram</p></figcaption></figure>

## Contact Type Descriptions

MaiAgent's contact system is divided into two types based on user identity recognition methods:

{% hint style="info" %}
**Simple explanation:**

* **Anonymous contact** = A visitor who has not logged in; the system does not know who they are
* **Non-anonymous contact** = A logged-in member; the system knows their identity and data
  {% endhint %}

## Contact Type Comparison Table

<table><thead><tr><th width="104.83331298828125">Item</th><th>Anonymous Contact</th><th>Non-Anonymous Contact</th></tr></thead><tbody><tr><td><strong>Applicable Scenario</strong></td><td>A visitor entering directly from the web who has not logged into the enterprise's member system, so there is no account to retrieve user data from</td><td>A logged-in member or a user entering through another platform account (such as Facebook, LINE, etc.), where the system can obtain the user's name and account information</td></tr><tr><td><strong>Identity Recognition</strong></td><td>Unable to obtain specific personal information</td><td>Has clear identity information (e.g., name, profile picture, etc.)</td></tr><tr><td><strong>System Setting</strong></td><td>Set as "Anonymous" within the MaiAgent system</td><td>The original member account ID is converted into a Source ID</td></tr><tr><td><strong>Permission Management</strong></td><td>Knowledge base document permissions, conversation platform management</td><td>Same as anonymous</td></tr><tr><td><strong>Data Mapping</strong></td><td>No Source ID, cannot be mapped to enterprise member data</td><td>Uses the Source ID to ensure the contact maps to the correct user each time</td></tr><tr><td><strong>Creation Method</strong></td><td>If a visitor (without member identity) enters, a new anonymous contact is automatically created for each conversation</td><td>The system automatically creates or updates contacts based on member login information via the MaiAgent API<br>For detailed integration instructions, see: <a href="https://docs.maiagent.ai/tech/authorization-integration/contacts">Technical Manual — Contact Introduction and Integration</a></td></tr><tr><td><strong>Record Mechanism</strong></td><td>The system records the user's conversation history based on cache</td><td>Maintains conversation continuity through Source ID and contact mapping</td></tr></tbody></table>

{% hint style="info" %}
**Importance of Source ID**

The **Source ID** is the key bridge connecting MaiAgent contacts with the enterprise's member system. When users interact with the enterprise through different channels (website, app, social platforms), the system can correctly identify the user's identity through the Source ID, ensuring conversation continuity and a personalized experience.

**Simple explanation:** The Source ID is like a "membership number" that lets the system recognize the same customer across different platforms.
{% endhint %}

## Setting Up Contacts

### Anonymous Users

When a user creates a new conversation, the system automatically creates a new anonymous user in the backend (each conversation creates one anonymous user) ⬇️

<div><figure><img src="/files/yrG1eQjHEwhdVBBDJmu4" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Y7IDihBDnikklCAtvMsk" alt=""><figcaption></figcaption></figure></div>

This includes information such as Contact ID, conversation platform records, creation time, etc.

You can click edit to manually edit anonymous contact information:

<div><figure><img src="/files/5b4G3VfyPMlvdRfmttDP" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Ez6HmyukdaCaYXlIDw5h" alt=""><figcaption></figcaption></figure></div>

**Through editing**, you can:

* Link member information: Enter a Source ID to link an anonymous contact to member data
* Update permission levels: Expand or restrict the scope of document access
* Add basic information such as customer name and contact details

### Non-Anonymous Users

When a user enters through another conversation platform (e.g., LINE, FB Messenger, Telegram):

The backend automatically creates a corresponding non-anonymous user based on the FB user information (including Source ID, contact name, profile picture, etc.):

<div><figure><img src="/files/MENrONLds6WIFWZ7cZgo" alt=""><figcaption></figcaption></figure> <figure><img src="/files/7T8nDcK5yVdnOwhlpYfa" alt=""><figcaption></figcaption></figure></div>

You can still click the edit button to edit non-anonymous contact information.

<figure><img src="/files/DlwFgdtL1dtUO03UmpDs" alt=""><figcaption></figcaption></figure>

**Through editing, you can:**

Complete and correct data

* Correct incorrect query metadata settings (update access scope based on permissions)
* Modify the internal Source ID to link the correct contact information with member information

{% hint style="danger" %}
Contacts rely on Source IDs for mapping. When editing, ensure the Source ID is synchronized with the enterprise's internal system; otherwise, it may cause data mapping errors during subsequent synchronization with internal enterprise information.
{% endhint %}

### Adding a Contact

The add contact feature is primarily used to **proactively create customer profiles with preset permissions**. If you have not specified a permission scope in Web Chat, you can create contacts in advance to complete permission configuration and service preparation before customers actually initiate a conversation.

{% hint style="info" %}
To specify a permission scope using a JavaScript script during Web Chat initialization, see: [Technical Manual: Getting Started — Using JSON Format](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces#webchat-chu-shi-hua-she-ding)
{% endhint %}

#### Core Feature Description

By manually creating a contact, system administrators can pre-create user profiles with specific identities in the customer service system and configure corresponding **Query Metadata** permissions. When these pre-created contacts later interact through a **designated conversation platform**, the system uses the **Source ID automatic matching mechanism** to immediately apply the preset permission level, ensuring they can access data content appropriate for their identity.

{% hint style="info" %}
**Simple explanation:**

Think of it as "preparing customer permission settings in advance." When this customer visits for the first time, the system already knows what data they can and cannot access.
{% endhint %}

You can click Add Contact to enter the editing page and add information:

<div><figure><img src="/files/tAtqktFj5IsawB1R8aNw" alt=""><figcaption></figcaption></figure> <figure><img src="/files/9AyBLBmEvZ3LfClBVrLp" alt=""><figcaption></figcaption></figure></div>

On the page, you can add contact name, specify conversation platform, and other information:

<figure><img src="/files/uXPak0TaeX0es4JBs5uI" alt=""><figcaption></figcaption></figure>

## Permission Management

Based on enterprise needs, you can use query metadata to restrict the scope of documents available to different contacts. For example:

#### Restrict by Membership Tier

* **VIP members**: Can query all knowledge bases, advanced FAQ, and product technical documents
* **Regular members**: Can only query basic FAQ and product user manuals
* **Guest users**: Can only query public FAQ and basic product introductions

#### Restrict by Department

* **Internal employees**: Can query internal operation manuals, system maintenance documents, and complete product data
* **Distributors**: Can query product specifications, price lists, and sales data
* **General customers**: Limited to querying user guides, FAQ, and warranty information

#### Restrict by Product Tags

* **Enterprise edition users**: Can query documents tagged with "Enterprise Features" and "Advanced Settings"
* **Personal edition users**: Can only query documents tagged with "Basic Features" and "Personal Use"
* **Trial users**: Can only query content tagged with "Trial Instructions" and "Getting Started Guide"

{% hint style="info" %}
To learn more about query metadata, see: [Knowledge Management Permissions: Query Metadata](/maiagent-user-guide/maiagent-user-guide-en/org/querymetadata.md)
{% endhint %}

When setting query metadata for a contact, the system only authorizes you to configure settings based on the knowledge base of your specified conversation platform. If you attempt to configure settings for another conversation platform's knowledge base, the following warning message appears:

<figure><img src="/files/MB3u4xKv4KP6Aur14X1Z" alt=""><figcaption></figcaption></figure>

## Automation Integration

For technical teams, MaiAgent also provides API endpoints for seamless integration with existing enterprise systems.

{% hint style="info" %}
For details, see: [Technical Manual — Contact Introduction and Integration](https://docs.maiagent.ai/tech/authorization-integration/contacts)
{% endhint %}

Regardless of enterprise size, the contact feature helps you deliver a better customer service experience while ensuring data security and operational efficiency. Through the classified management of anonymous and non-anonymous contacts, the precise mapping mechanism of Source IDs, and flexible creation methods, enterprises can provide the most suitable service experience for different types of users and be fully prepared before customer interactions begin.


---

# 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/maiagent-user-guide/maiagent-user-guide-en/org/contact.md?ask=<question>&goal=<endgoal>
```

`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.