Skip to main content

🎭 Roles

Define and manage user roles within your group. The Roles feature in Fren One provides community admins with a powerful way to recognize and reward members for their engagement. Roles can grant additional permissions, create a sense of achievement, and promote user participation by tying roles to XP milestones or custom criteria.

Overview​

Roles provide:

  • Member Recognition: Visual distinction for active or special members
  • Progression Rewards: Automatic role grants based on XP milestones
  • Permission Control: Grant specific capabilities to role holders
  • Engagement Motivation: Members work toward earning roles
  • Community Structure: Clear hierarchy and member classification
  • Custom Messages: Celebrate role promotions with custom notifications
Integration with XP

Roles work seamlessly with the XP system, automatically granting roles when members reach specific levels or XP thresholds.

Configuration​

To access Roles settings:

  1. Use the /settings command in your chat
  2. Navigate to 🏆 Gamification → 🎭 Roles
  3. Configure roles and settings

Main menu displays:

📛 Fren (example role name)

➕ Create Role
⚙️ Role Settings

Creating Roles​

Create custom roles with specific requirements and rewards.

Create Role​

Steps:

  1. Click ➕ Create Role
  2. Send role details in the specified format
  3. Bot will create and save the role

Format:

Role Name | XP Required (optional) | Promotion Message (optional)

Input format prompt:

Send the role details in this format:
Role Name | XP Required (optional) | Promotion Message (optional)

Available variables for role promotion messages: \{name\}, \{roleName\}

Use \{name\} to insert the user's name and \{roleName\} for the role name.

Examples:

Role with XP requirement and message:

Active Member | 1000 | Congratulations \{name\}, you are now an \{roleName\}!

Role with XP only:

Veteran | 5000

Role without XP (manually assigned):

Moderator

Role with custom celebration:

Community Champion | 10000 | 🎉 \{name\} has achieved the \{roleName\} rank! Welcome to the elite!
Promotion Messages

Use dynamic placeholders \{name\} and \{roleName\} to personalize role promotion messages. These make earning roles feel more rewarding and create community excitement.

After creating: The bot confirms creation and the role appears in your roles list.

Managing Roles​

Once created, roles can be viewed, edited, or deleted.

View Role Details​

Click on a role name (e.g., "Fren") to view its details:

Details display:

Role Name: Fren
XP Required: 10000
Permissions: pin
Default Role: ✅ Yes
Reward Message: You are fren! 👍

Available actions:

  • ✏️ Edit: Modify role name, XP requirement, or promotion message
  • 🗑️ Delete: Permanently remove the role
  • 🔒 Permissions: Configure role-specific permissions
  • 🔙 Back: Return to roles menu

Edit Role​

Modify existing role properties:

Editable properties:

  • Role name
  • XP requirement
  • Promotion message
  • Default role status

Steps:

  1. Select role from list
  2. Click ✏️ Edit
  3. Send updated details in the same format
  4. Bot updates the role
Editing Active Roles

Editing a role that members already have will not retroactively change their status. Only new earners will receive the updated promotion message or requirements.

Delete Role​

Permanently remove a role:

Steps:

  1. Select role from list
  2. Click 🗑️ Delete
  3. Confirm deletion

What happens:

  • Role is removed from the system
  • Members with the role lose it
  • XP thresholds are unaffected
  • Can be recreated if needed
Permanent Action

Deleting a role is permanent and immediately removes it from all members who have it. Consider carefully before deleting active roles.

Role Permissions​

Grant users with specific roles additional capabilities within the community.

Available Permissions​

Moderation Permissions:

  • ❌ Mute members: Grants ability to mute and unmute users using !mute and !unmute commands
  • ❌ Kick members: Grants ability to remove users from the group using !kick command
  • ❌ Warn members: Grants ability to warn and clear warnings for users using !warn and !acquit commands

Content Management:

  • ✅ Pin messages: Grants ability to pin messages using !pin command
  • ❌ Bypass restrictions: Grants immunity from all moderation restrictions
  • ❌ Manage scheduled messages: Grants ability to manage scheduled messages using /scheduler

Gamification:

  • ❌ Manage quizzes: Grants ability to create, edit, and delete quizzes using /quiz_settings

Configuring Permissions​

Steps:

  1. Select role from list
  2. Click 🔒 Permissions
  3. Toggle permissions on (✅) or off (❌)
  4. Click 💾 Save to apply changes

Permission descriptions shown:

Mute members: Grants this role the ability to mute and unmute users using the !mute and !unmute commands.
Kick members: Grants this role the ability to remove users from the group using the !kick command.
Warn members: Grants this role the ability to warn and clear warnings for users using the !warn and !acquit commands.
Pin messages: Grants this role the ability to pin messages using the !pin command.
Bypass restrictions: Grants this role immunity from all moderation restrictions.
Manage quizzes: Grants this role the ability to create, edit, and delete quizzes using /quiz_settings.
Manage scheduled messages: Grants this role the ability to manage scheduled messages using /scheduler.
Permission Strategy

Grant permissions thoughtfully. Start with minimal permissions and expand based on trust. Pin messages is generally safe, while moderation permissions should be reserved for trusted members.

Permission Use Cases​

Community Helper Role:

  • Pin messages: ✅
  • All others: ❌
  • Result: Can highlight important messages

Junior Moderator:

  • Warn members: ✅
  • Pin messages: ✅
  • All others: ❌
  • Result: Can issue warnings, manage content

Trusted Moderator:

  • Mute members: ✅
  • Kick members: ✅
  • Warn members: ✅
  • Pin messages: ✅
  • Manage quizzes: ✅
  • Result: Full moderation capability

VIP/Supporter:

  • Bypass restrictions: ✅
  • All others: ❌
  • Result: Immune to filters and restrictions

Content Manager:

  • Manage scheduled messages: ✅
  • Pin messages: ✅
  • Manage quizzes: ✅
  • Result: Can manage community content and engagement

Role Settings​

Configure how roles function within the community.

Accessing Role Settings​

  1. From Roles menu, click ⚙️ Role Settings
  2. View and configure global role options

Settings menu displays:

✅ Role Messages
🔒 Visibility: Private
📛 Default Role

Role Messages​

Role Messages: Activate the configured promotion messages whenever a user earns a new role (excluding the default role).

Options:

  • ✅ Enabled: Promotion messages are sent when users earn roles
  • ❌ Disabled: No messages sent, roles granted silently

When enabled:

  • User earns role → Bot posts promotion message in chat
  • Uses configured message with {name} and {roleName} placeholders
  • Creates public recognition and celebration
  • Motivates other members

When disabled:

  • Roles granted silently
  • No chat notifications
  • Good for private/utility roles
  • Reduces chat noise
Public Recognition

Enable role messages for achievement-based roles (XP milestones, special status). Disable for utility roles (token holders, manual assignments) to reduce unnecessary notifications.

Role Visibility​

🔒 Visibility: Public/🔒 Visibility: Private: Choose whether users can view the roles of other members in the group via /roles.

Public Visibility:

  • Members can use /roles command
  • Shows role list and who has each role
  • Transparent role structure
  • Encourages earning roles

Private Visibility:

  • /roles command restricted to admins only
  • Role information not publicly visible
  • Maintains privacy
  • Reduces status comparison

Steps to change:

  1. Click 🔒 Visibility
  2. Bot toggles between Public and Private
  3. Current setting displays on main menu
Command Access

When set to Public, any member can type /roles to see the community's role structure and members with each role. When Private, only admins can access this information.

Default Role​

📛 Default Role: Set the default role automatically assigned when users join the group or pass the CAPTCHA.

Purpose:

  • Welcome new members with a starting role
  • Distinguish new vs established members
  • Starting point for progression
  • Can tie basic permissions to membership

Steps to configure:

  1. Click 📛 Default Role
  2. Select from existing roles
  3. Chosen role automatically assigned to new members

Common default roles:

  • "Newcomer" or "New Member"
  • "Verified" (after CAPTCHA)
  • "Member" or "Community Member"
  • Token-specific name for token-gated groups

Default role characteristics:

  • Automatically assigned on join/CAPTCHA completion
  • No XP requirement
  • Usually has no special permissions
  • Starting point for advancement
  • Does not trigger promotion message
Default Role Strategy

Use a neutral welcome role as the default. Create a clear progression path from default role to earned roles through XP. For example: Newcomer → Regular → Active Member → Veteran.

Common Use Cases​

XP-Based Progression System​

Scenario: Reward active members with progressive roles.

Configuration:

  • Level 1 (300 XP): Regular (default)
  • Level 3 (1,200 XP): Active Member + pin permission
  • Level 5 (3,700 XP): Veteran + warn permission
  • Level 8 (12,200 XP): Community Champion + all permissions
  • Messages: Enabled with celebration text

Result: Clear progression path, members work toward permissions, public recognition.

Token Holder Recognition​

Scenario: Distinguish verified token holders.

Configuration:

  • "Token Holder" role (no XP, manual/token-gating)
  • Bypass restrictions: ✅
  • Role messages: Disabled
  • Visibility: Public

Result: Holders have immune status, visible distinction, no spam from messages.

Moderation Team Structure​

Scenario: Tiered moderation permissions.

Configuration:

  • "Helper" (Level 5): Pin messages
  • "Junior Mod" (Manually assigned): Pin + Warn
  • "Moderator" (Manually assigned): Pin + Warn + Mute + Kick
  • "Senior Mod" (Manually assigned): All permissions

Result: Graduated trust levels, earn way into moderation, clear hierarchy.

Community Supporter Program​

Scenario: Recognize top contributors and supporters.

Configuration:

  • "Supporter" (Manual): Bypass restrictions, special color
  • "Super Supporter" (Manual): Bypass + Pin + Manage quizzes
  • "Legend" (10,000 XP): All permissions + custom promotion
  • Messages: Enabled with gratitude text
  • Visibility: Public

Result: Recognition for support, exclusive perks, motivation to contribute.

Event-Based Roles​

Scenario: Temporary or special event roles.

Configuration:

  • "Event Winner" (Manual): Badge of honor, no permissions
  • "Contest Participant" (Manual): Special recognition
  • "Quiz Master" (High XP): Manage quizzes permission
  • Messages: Enabled with congratulatory text

Result: Event engagement, memorable recognition, special status.

Best Practices​

Effective Role Design
  • Clear Progression: Create obvious path from newcomer to veteran
  • Meaningful Names: Use descriptive, motivating role names
  • Balanced Requirements: XP thresholds should feel achievable but earned
  • Permission Gradation: Grant permissions gradually based on trust
  • Celebration Messages: Use creative promotion messages for recognition
  • Public Visibility: Let members see and aspire to roles
  • Default Role: Always set a welcoming default role
  • Regular Review: Adjust roles as community grows
  • Combine with XP: Tie roles to level achievements
  • Special Roles: Create manual roles for unique contributions
Common Mistakes
  • Too Many Roles: Overwhelming structure confuses members
  • Unclear Requirements: Members don't know how to earn roles
  • Inappropriate Permissions: Giving powerful permissions too easily
  • No Progression Path: All roles are manual with no way to earn
  • Boring Messages: Generic promotion messages reduce impact
  • Private Visibility: Hiding roles reduces motivation
  • No Default Role: New members feel excluded or unclear about status
  • Inconsistent Naming: Role names don't make sense together

Role Management Commands​

For Members​

View Available Roles:

/roles

Shows all roles, requirements, and who has them (if visibility is Public)

Check Personal Status:

/xp or /level

Shows current XP and next role threshold

For Admins​

Manual Role Assignment:

  • Assign roles to members manually
  • Useful for special recognition
  • Bypasses XP requirements
  • Immediate grant

Role Removal:

  • Manually remove roles if needed
  • Useful for corrections
  • Doesn't affect XP
  • Immediate removal

View Role Holders:

  • See all members with each role
  • Useful for management
  • Track role distribution
  • Identify active members
Manual Overrides

Admins can manually assign or remove any role regardless of XP requirements. This is useful for special circumstances, rewards, or corrections.

Integration with Other Features​

Roles + XP System​

Automatic role progression:

  • Set XP thresholds for each role
  • Members auto-earn roles at level-ups
  • Promotion messages celebrate achievement
  • Clear visual progression

Roles + Permissions​

Access control structure:

  • Grant moderation capabilities to trusted roles
  • Content management for active members
  • Bypass restrictions for supporters
  • Graduated trust model

Roles + Token Gating​

Token holder recognition:

  • Create "Holder" role
  • Auto-assign via Token Gating
  • Visual distinction for verified holders
  • Combine with XP progression

Roles + Leaderboard​

Competitive element:

  • Top leaderboard earners get special roles
  • Periodic role awards for leaders
  • Time-based competition roles
  • Recognition for achievement

Roles + Quizzes​

Educational roles:

  • "Quiz Master" for high scorers
  • Knowledge verification roles
  • Educational achievement recognition
  • Manage quiz permission for helpers

Roles + Moderation​

Distributed moderation:

  • Community helpers with limited powers
  • Graduated moderation permissions
  • Earn moderation through contribution
  • Reduce admin burden

Troubleshooting​

Roles not being granted automatically?

  • Verify XP thresholds are set correctly
  • Check member has reached required XP
  • Ensure bot has role management permissions
  • Verify role exists and is configured
  • Check for conflicts with other features

Permissions not working?

  • Verify bot has necessary Telegram admin permissions
  • Check role has permission enabled
  • Ensure member actually has the role
  • Test commands are correct (!pin, !warn, etc.)
  • Verify no other restrictions override permissions

Promotion messages not appearing?

  • Check Role Messages are enabled in settings
  • Verify promotion message is configured for role
  • Ensure bot has posting permissions
  • Check message isn't being filtered
  • Test with manual role grant

Default role not assigned to new members?

  • Verify default role is set in Role Settings
  • Check bot has role assignment permissions
  • Ensure member completed CAPTCHA (if enabled)
  • Verify role exists
  • Test with test account

Members can't see roles with /roles command?

  • Check Visibility is set to Public
  • Ensure command isn't restricted
  • Verify bot is responding to commands
  • Check user permissions
  • Test command yourself

Role deleted but members still have it?

  • This shouldn't happen - deletion removes role from all members
  • If it persists, contact support
  • May need to manually remove
  • Check for caching issues

Advanced Strategies​

Dynamic Role System​

Create flexible role structure:

Tier 1 - Participation:

  • Newcomer (default)
  • Regular (100 XP)
  • Active (500 XP)

Tier 2 - Contribution:

  • Contributor (1,000 XP)
  • Veteran (3,000 XP)
  • Champion (10,000 XP)

Tier 3 - Special:

  • Moderator (manual)
  • Supporter (manual/token)
  • Legend (manual, exceptional)

Seasonal Roles​

Time-limited special roles:

Event Roles:

  • "Launch Week Hero" (manual, first week)
  • "Quiz Champion" (monthly winner)
  • "Top Contributor" (monthly leaderboard #1)

Rotation:

  • Grant at event end
  • Remove when season ends (optional)
  • Permanent record of achievement
  • New competition each period

Role Economy​

Make roles valuable:

Benefits per Role:

  • Access to exclusive channels
  • Special XP multipliers
  • Priority support
  • Exclusive content
  • Voting power
  • Giveaway entries

Motivation: Clear value makes members work harder to earn roles

Progressive Permissions​

Carefully distribute power:

Level 1 (Default):

  • No permissions
  • Standard member

Level 2 (1,000 XP):

  • Pin messages
  • Help highlight important content

Level 3 (3,000 XP):

  • Pin messages
  • Warn members
  • Junior moderation

Level 4 (10,000 XP):

  • Pin messages
  • Warn members
  • Mute members
  • Full moderation (except kick/ban)

Manual (Admin discretion):

  • All permissions
  • Trusted team members only
Recognition Drives Engagement

Roles are powerful motivators. Members work hard to earn visible recognition and special permissions. Design a clear, achievable progression system and celebrate achievements publicly. A well-structured role system transforms passive members into active, engaged community participants!