Differences Between Roles and Contacts

Internal members use roles to manage platform permissions, while external users use contacts for identity—their definitions, differences, and how to choose between them

MaiAgent has two types of “people”: members, who have accounts that sign in to the MaiAgent platform and operate the admin console, with permissions determined by roles; and contacts, who are end users interacting with AI assistants and do not need MaiAgent accounts. Confusing the two is a common integration mistake, so this page clearly explains their differences.

Definitions

Contact

A contact represents an end user who interacts with an AI assistant, such as a website visitor, a user in a membership system, or a LINE friend. Contacts do not sign in to MaiAgent. The system creates them automatically during a conversation, or your system creates them through the API and maps them to your own accounts. Conversation history, personalized attributes, knowledge query scope, and tool credentials are all associated with contacts.

For the contact data model and integration methods, see Contacts: Introduction and Integration.

A contact without a configured name is displayed as anonymous by default

Role

A role is a permission template for members. It defines which features members can use and which resources they can access after signing in to the MaiAgent admin console, such as AI assistants, knowledge bases, and inboxes. An organization can define roles such as “customer service representative,” “administrative staff,” and “intern” in advance and apply them when members join, without configuring each person individually.

Role settings in a member's profile

Comparison

AI assistant embed screen

Comparison	Contact	Role
🎯 Who it applies to	External end users (visitors, members, customers)	Internal members (employees, administrators)
👤 MaiAgent account	❌ Not required	✅ Required (the member signs in to the platform)
📋 How it is created	Created automatically during a conversation, through the API, or manually in the admin console	A role is defined in advance in the admin console and applied to members
🎯 What it controls	The user's conversation history, personalized attributes, knowledge query scope (query_metadata), and tool credentials	A member's admin-console permissions and resource access scope
⚙️ Management interface	API integration or “Contacts” in the admin console	“Role Permission Management” in the admin console

How knowledge scope is controlled

Both can affect which knowledge is available, but they use different mechanisms:

• Contact: Configure Query Metadata on the contact to restrict which knowledge bases, documents, and tags the AI can retrieve during that user's conversations

• Role: Controls which resources members can view and manage on the platform (see Role Permission Management in the user manual). In internal Q&A, members can select the knowledge scope to reference for each message

How to choose

• External services (website customer support, member centers, or embedded products): Users do not need and should not have MaiAgent accounts → use contacts, associating query_metadata or custom attributes with each identity as needed

• Internal use (internal employee Q&A or team operations for AI assistants): Members sign in to the platform → use roles to grant permissions consistently

• Both can coexist: The same organization typically has both members who manage the admin console and contacts who interact with the AI. Each uses its own mechanism, with no overlap

Recommendations for Contact and Role authorization