Core Concepts

Understanding ChatMinder's protection system and user types is essential for effective API integration.

User Types

Protected Users

Users requiring supervision (such as minors or individuals needing oversight):

Have assigned guardians who manage their communication
Subject to approval workflows based on their protection level
Can have multiple guardians with shared access

Guardians

Users who manage and supervise protected users:

Review and approve messages and contact requests
Manage channel memberships for protected users
Can delegate supervision to other guardians

Protection Levels

ChatMinder supports three protection levels that determine supervision requirements for protected users:

1. GuardianFullyManaged

Most Restrictive: Guardian controls all communication activities
❌ Protected user cannot create channels or accept invitations
❌ All messages require guardian approval
🎯 Best for: Young children or users requiring complete supervision

2. GuardianFullyModerated

Collaborative: Shared control between guardian and protected user
✅ Protected user can create channels (with guardian approval for invitations)
❌ All messages require guardian approval
🎯 Best for: Adolescents learning digital responsibility

3. Trusted

Minimal Supervision: Independent communication with monitoring
✅ Protected user can create channels and manage invitations independently
✅ Messages are delivered immediately (guardian monitors but doesn't block)
🎯 Best for: Mature users who need monitoring but not restriction

For detailed protection level workflows, API endpoints, and implementation patterns, see the Protected User Management Guide.

// Messages send immediately
showMessagePendingStatus = false;
enableImmediateMessaging = true;

}


## Protection Level Implementation

When working with protected users, check their protection level to understand approval requirements:

### Channel Permissions
```csharp
switch (protectionLevel)
{
    case ProtectionLevel.GuardianFullyManaged:
        return new ChannelPermissions(
            canCreateDirectChannels: false,
            invitingMembersToDirectChannelsRequiresGuardianApproval: true,
            canCreateGroupChannels: false,
            invitingMembersToGroupChannelsRequiresGuardianApproval: true,
            canAcceptOrRejectInvites: false,
            acceptingOrRejectingInvitesToChannelsRequiresGuardianApproval: true);
    case ProtectionLevel.GuardianFullyModerated:
        return new ChannelPermissions(
            canCreateDirectChannels: true,
            invitingMembersToDirectChannelsRequiresGuardianApproval: true,
            canCreateGroupChannels: false,
            invitingMembersToGroupChannelsRequiresGuardianApproval: true,
            canAcceptOrRejectInvites: true,
            acceptingOrRejectingInvitesToChannelsRequiresGuardianApproval: true);
    case ProtectionLevel.Trusted:
        return new ChannelPermissions(
            canCreateDirectChannels: true,
            invitingMembersToDirectChannelsRequiresGuardianApproval: false,
            canCreateGroupChannels: true,
            invitingMembersToGroupChannelsRequiresGuardianApproval: false,
            canAcceptOrRejectInvites: true,
            acceptingOrRejectingInvitesToChannelsRequiresGuardianApproval: false);
    default:
        throw new NotSupportedException();
}

Message Permissions

switch (protectionLevel)
{
    case ProtectionLevel.GuardianFullyManaged:
        return new MessagePermissions(
            sendingMessagesRequiresGuardianApproval: true,
            receivingMessagesRequiresGuardianApproval: true);
    case ProtectionLevel.GuardianFullyModerated:
        return new MessagePermissions(
            sendingMessagesRequiresGuardianApproval: true,
            receivingMessagesRequiresGuardianApproval: true);
    case ProtectionLevel.Trusted:
        return new MessagePermissions(
## Personal Contacts (Address Book)

Users can maintain personal address books with custom contact names:

- **No Communication Gating**: Contacts are purely organizational - they don't affect communication permissions
- **Bi-directional**: Contact relationships work in both directions
- **Guardian Managed**: For protected users, guardians can manage their contact lists
- **Custom Names**: Users can assign meaningful names to their contacts

```csharp
// Example: Adding a contact
POST /api/contacts
{
    "targetUserId": "user123",
    "contactName": "Dr. Smith (Family Doctor)"
}

Developer Guidelines

UI/UX Implementation Tips

Message Handling Best Practices:

Cache messages locally for better UX and implement optimistic UI updates
Access guardian approval properties via nested structure: approval.mostRecentMessage.id
Handle pendingMessageId responses that require explicit approval workflow
Show clear status indicators for pending, approved, and rejected messages

Guardian Interface Design:

Clearly distinguish guardian vs user actions in UI (different colors, sections, or interfaces)
Show approval status and pending counts to guardians prominently
Handle nested response structures in guardian approval workflows gracefully
Provide bulk approval options for efficiency when appropriate

Error Handling Patterns:
ChatMinder uses structured error responses with consistent patterns. For comprehensive error handling guidelines, see the Error Handling Guide.

Next Steps

Authentication Guide: Learn how to authenticate with the API
Protected User Management: Guardian relationships and supervision workflows
Error Handling: Comprehensive error codes and recovery patterns
Walkthroughs: See complete scenarios with protection level workflows
Real-time Features: Understand SignalR integration

📖 Documentation