Differences between Role and Contact

Use Roles to manage platform permissions for internal members, and Contacts to identify external users — definitions, differences, and how to choose

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

Contact

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.

For the Contact data model and integration methods, refer to Contact Introduction and Integration.

Role

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

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

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

• Contact: Set Query Metadata 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 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

• 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