# Differences Between Roles and Contacts

## Display in Conversations

### Contact

MaiAgent creates a contact ID in the synchronized user information storage to identify user conversation information.

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

{% hint style="info" %}
To learn more about contacts, please refer to [🌐Contact](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/contact)
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-014415472288f559f650849304a7b45e5d2cb89d%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.29.05.png?alt=media" alt=""><figcaption><p>Contact name not set: Users default to anonymous</p></figcaption></figure>

### Role

To assign a role to a user, that user must have a MaiAgent account and be part of the organization. Enterprises can predefine roles internally, such as: customer service representative, administrative staff, intern, etc. Within the organization, roles can be created in advance with usable permissions and reference databases. Organization members can select roles according to their needs and directly apply the settings.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3ee9233a19709cbeb9d408d978d2b331b2f8e898%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.36.55.png?alt=media" alt=""><figcaption><p>Role user basic information display</p></figcaption></figure>

{% hint style="info" %}
To learn more about contacts, please refer to 🌐[Role Permission Management](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/rolepermission.md)
{% endhint %}

## Permission Method Comparison

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-bb81392bc29a9771001ca21c0572cd2a94c123fc%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.32.19.png?alt=media" alt=""><figcaption><p>AI assistant embedded view</p></figcaption></figure>

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

## Typical Application Scenarios

**Contact Use Cases: Suitable for scenarios requiring clear role division and permission definition**

* **Corporate Website**: Visitors receive different product information based on their identity
* **Member Center**: Access corresponding service content based on membership level
* **Customer Service Center**: Provide differentiated support based on customer type

**Role Use Cases**

* **Internal Operations**: Employees handle work according to departmental roles
* **Customer Service Team**: Query knowledge base according to scope of responsibility
* **Management Level**: Conduct content review and maintenance according to permissions

## Comprehensive Usage Strategy

Contact management is suitable for external business (where explicit user identity is not required)

Role management is suitable for internal business (where clear permission division is needed / multiple members can use the same permissions)

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-53645aaed37bd279cd5330b940b591e287bba444%2Fimage.png?alt=media" alt=""><figcaption><p>Contact and role authorization usage recommendations</p></figcaption></figure>
