> 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/role-vs-contact.md).

# Differences between Role and Contact

MaiAgent has two types of "people": **Members** — accounts that log in to the MaiAgent platform to manage the backend, with permissions determined by **Roles**; and **Contacts** — end users who interact with AI assistants, without needing a MaiAgent account. The most common confusion during integration is mixing up these two concepts. This page clarifies the differences once and for all.

## Definitions <a href="#definitions" id="definitions"></a>

### Contact <a href="#contact-definition" id="contact-definition"></a>

A Contact represents an "end user who interacts with an AI assistant": visitors on your website, users in your membership system, and LINE friends are all Contacts. Contacts do not log in to MaiAgent. The system creates them automatically during conversations, or your system can create them via API and map them to your own accounts. Conversation history, personalized attributes, knowledge query scope, and tool credentials are all associated with the Contact.

{% hint style="info" %}
For the Contact data model and integration methods, refer to [Contact Introduction and Integration](/tech/en/authorization-integration/contacts.md).
{% endhint %}

### Role <a href="#role-definition" id="role-definition"></a>

A Role is a **permission template for members**: it defines which features and resources (AI assistants, knowledge bases, inboxes, etc.) a member can access after logging in to the MaiAgent backend. Organizations can predefine roles such as "Customer Service Agent," "Administrative Staff," and "Intern," then assign them directly when members join — no need to configure permissions individually.

## Comparison <a href="#comparison" id="comparison"></a>

|        Comparison Item        |                                                         Contact                                                         |                                  Role                                 |
| :---------------------------: | :---------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------: |
|         🎯 **Target**         |                                    External end users (visitors, members, customers)                                    |              Internal members (employees, administrators)             |
|    👤 **MaiAgent Account**    |                                                      ❌ Not required                                                     |              ✅ Required (members log in to the platform)              |
|     📋 **Creation Method**    |                  Auto-created during conversations, created via API, or manually created in the backend                 |         Predefine roles in the backend, then assign to members        |
|    🎯 **What It Controls**    | The user's conversation history, personalized attributes, knowledge query scope (query\_metadata), and tool credentials | Member operation permissions and resource access scope in the backend |
| ⚙️ **Management Entry Point** |                                 API integration or the "Contacts" section in the backend                                |              "Role Permission Management" in the backend              |

## Knowledge Scope Control <a href="#knowledge-scope" id="knowledge-scope"></a>

Both can affect "which knowledge is retrievable," but through different mechanisms:

* **Contact**: Set [Query Metadata](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) on the Contact to restrict which knowledge bases, documents, and tag scopes the AI can search during conversations with that user
* **Role**: Control which resources a member can **view and manage** within the platform (see [Role Permission Management](https://docs.maiagent.ai/org/role-permission) in the user guide); members can also select the knowledge scope to reference on a per-message basis in internal Q\&A

## How to Choose <a href="#how-to-choose" id="how-to-choose"></a>

* **External services** (website customer support, member portal, embedded in your product): Users do not need and should not have a MaiAgent account → Use **Contacts**, and attach query\_metadata or custom attributes based on identity for differentiation
* **Internal use** (employee internal Q\&A, team-operated AI assistants): Members log in to the platform → Use **Roles** to assign permissions uniformly
* Both can coexist: An organization typically has both "members managing the backend" and "Contacts interacting with the AI" at the same time, each operating through its own mechanism without overlap


---

# 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/role-vs-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.