> 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-role-comparison.md).

# Differences Between Roles and Contacts

## Display in Conversations

### Contact

A contact is a storage entity in MaiAgent that synchronizes user information. A Contact ID is created to identify user conversation data.

Users do not need to log in or have a MaiAgent account to be created.

{% hint style="info" %}
To learn more about contacts, see [🌐 Contacts](/maiagent-user-guide/maiagent-user-guide-en/org/contact.md)
{% endhint %}

<figure><img src="/files/it70QaBvh98JhE7kjBx1" alt=""><figcaption><p>Contact name not set: User defaults to anonymous</p></figcaption></figure>

### Role

To assign a role to a user, the user must have a MaiAgent account and be a member of the organization. Enterprises can predefine roles such as customer service agent, administrative staff, intern, etc. Within an organization, you can preconfigure the permissions and reference databases available to each role, and organization members can select and apply role settings as needed.

<figure><img src="/files/hOC17s24O69NeWeRf9cC" alt=""><figcaption><p>Role user profile display</p></figcaption></figure>

{% hint style="info" %}
To learn more about roles, see 🌐 [Role Permission Management](/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md)
{% endhint %}

## Permission Comparison

<figure><img src="/files/sQqfrxmentDqiAv8VSrD" alt=""><figcaption><p>AI Assistant embed view</p></figcaption></figure>

|        Comparison Item       |                     Contact                     |                                    Role                                   |
| :--------------------------: | :---------------------------------------------: | :-----------------------------------------------------------------------: |
|        🎯 **Use Case**       |        External users, system integration       |                  Internal users, organization management                  |
| 👤 **MaiAgent Registration** |            ❌ No registration required           |            ✅ Registration and organization membership required            |
|    📋 **Creation Method**    | Automatically or manually created by the system |                         Predefined role templates                         |
|    🔄 **Update Mechanism**   |          Dynamic user information sync          |                      Static role permission settings                      |
|        🎯 **Purpose**        |         Identify user conversation data         | Apply preset permission settings, manage AI Assistant backend permissions |
|      👥 **Target Users**     |            External visitors, members           |                  Internal employees, organization members                 |
|   ⚙️ **Management Method**   |           Managed via API integration           |                    Managed via backend role management                    |
|   📊 **Permission Control**  |       Dynamic control based on Contact ID       |                        Static control based on Role                       |

## Typical Use Cases

**Contact use cases: Suitable for scenarios requiring clear identity-based differentiation**

* **Company website**: Visitors receive different product information based on their identity
* **Membership center**: Access corresponding service content based on membership tier
* **Customer service center**: Provide differentiated support based on customer type

**Role use cases**

* **Internal operations**: Employees handle tasks based on departmental roles
* **Customer service team**: Query knowledge bases according to job responsibilities
* **Management**: Review and maintain content based on permissions

## Combined Usage Strategy

External-facing operations (where user identity does not need to be explicitly known) are best managed with contacts.

Internal operations (requiring clear permission separation / multiple members sharing the same permissions) are best managed with roles.

<figure><img src="/files/rXObrxHMxTbVp1Dwf3wr" alt=""><figcaption><p>Recommended usage of contacts and roles for authorization</p></figcaption></figure>


---

# 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-role-comparison.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.