Frequently Asked Questions

What is Discord Role Guardian?

Discord Role Guardian is a free, open-source Discord bot for advanced server management. It provides 14 powerful commands for reaction roles, welcome/leave messages, XP leveling with auto-role rewards, support tickets, and scheduled announcements. Built with Node.js and discord.js.

Is Discord Role Guardian free?

Yes! Discord Role Guardian is 100% free and open source under the MIT License. View source code, report bugs, and contribute on GitHub. You can use it for free or host it yourself at no cost.

Do I need coding knowledge to use the bot?

No coding knowledge required! The bot uses Discord's slash commands (type / to see all commands). All features are configured through simple commands like /setup-reaction-roles, /setup-welcome, /setup-leveling, etc.

Where is my data stored?

Data is stored in JSON files using persistent Railway volumes. This includes reaction role configs, welcome/leave settings, user XP data, scheduled messages, and ticket configurations. If you self-host, all data stays on your server in the /data folder.

Is the bot always online?

The public hosted version runs 24/7 on Railway with UptimeRobot monitoring. You can check real-time uptime on our /status page. For self-hosted instances, uptime depends on your hosting setup.

How many servers can use the bot?

The bot supports multi-server functionality with guild-specific configurations. Each server has independent settings for all features. There's no limit on how many servers can use the bot simultaneously.

What are reaction roles and how do they work?

• Members click emoji reactions on a message to self-assign roles
• Use /setup-reaction-roles with channel, title, description, and roles (format: emoji:roleID,emoji:roleID)
• Bot automatically adds emojis and listens for reactions
• Removing the reaction removes the role automatically
• Works with both Unicode emojis (🔴🔵) and custom server emojis
• Multiple reaction role messages can be created per server

How does the leveling system work?

• Members earn XP by sending messages (default: 15-25 XP per message)
• 60-second cooldown per user to prevent spam/farming
• Level formula: Level N requires (N × N × 100) total XP
• Auto role rewards at specific levels with /add-level-role
• Check rank with /rank [user] - shows level, XP, and progress bar
• View server leaderboard with /leaderboard (top 5-25 members)
• Optional level-up announcements and XP gain notifications
• Guild-specific XP - doesn't transfer between servers

Can I customize welcome and leave messages?

• Yes! Use /setup-welcome and /setup-leave commands
• Placeholders: {user} (mention), {server} (name), {count} (member count)
• Custom hex colors for embeds (e.g., #00ff00 for green)
• Welcome messages show account creation date and member number
• Leave messages show how long member was in server
• Both require Send Messages + Embed Links permissions

What is the ticket system?

• Create private support channels with /setup-ticket
• Members click a button to create tickets
• Each ticket gets a private channel with staff access
• Supports up to 5 different staff roles per server
• Optional transcript channel for ticket logs
• View statistics with /ticket-stats (admin only)
• Tickets are organized in a specified category

Can I schedule recurring messages?

• Yes! Use /schedule-message with 4 schedule types:
• Once - One-time message (auto-removes after sending)
• Daily - Same time every day
• Weekly - Specific day and time (0=Sunday, 6=Saturday)
• Monthly - Specific day of month (1-31) and time
• Timezone-aware scheduling with UTC offset support
• View all with /list-scheduled, remove with /remove-scheduled
• Changes apply immediately without bot restart

What commands are available?

• Admin Commands (14 total):
• /setup-reaction-roles - Create reaction role messages
• /remove-reaction-roles - Delete reaction role config
• /setup-welcome - Configure welcome messages
• /setup-leave - Configure leave messages
• /setup-leveling - Enable XP/leveling system
• /add-level-role - Add role rewards for levels
• /setup-ticket - Create ticket system
• /schedule-message - Schedule announcements
• /list-scheduled - View scheduled messages
• /remove-scheduled - Delete scheduled message
• /ticket-stats - View ticket statistics
• /reset - Reset all server configurations
• Public Commands:
• /rank [user] - Check XP and level
• /leaderboard [limit] - View top ranked members

How do I add the bot to my server?

• Click the invite link on our homepage
• Select your server from the dropdown
• Grant Administrator permission (required for full functionality)
• The bot will join and slash commands appear within 5-10 minutes
• Start configuring with slash commands (type / to see all)

What permissions does the bot need?

• Required: Administrator (for easiest setup)
• Minimum permissions needed:
• • View Channels - Access server channels
• • Send Messages - Send responses
• • Embed Links - Send rich embeds
• • Manage Roles - Assign reaction roles and level rewards
• • Add Reactions - Add emojis to reaction role messages
• • Read Message History - Track reactions
• • Manage Channels - Create ticket channels
• IMPORTANT: Bot's role must be ABOVE all roles it assigns in role hierarchy

How do I set up reaction roles?

• 1. Get role IDs (Right-click role → Copy ID, needs Developer Mode enabled)
• 2. Use: /setup-reaction-roles
• • channel: Where to post the message
• • title: Embed title
• • description: Message description
• • roles: Format is emoji:roleID,emoji:roleID
• • Example: 🔴:123456789,🔵:987654321
• 3. Bot creates message with reactions automatically
• 4. Members click reactions to get roles instantly

How do I configure the leveling system?

• 1. Enable with /setup-leveling:
• • enabled: true
• • announce-channel: Where level-ups are announced (optional)
• • xp-min/xp-max: XP range per message (default: 15-25)
• • cooldown: Seconds between XP gains (default: 60)
• • announce-level: Announce level-ups (default: true)
• • announce-xp: Announce XP gains (default: false)
• 2. Add role rewards with /add-level-role:
• • level: 1-100
• • role: Role to assign
• 3. Members earn XP automatically by chatting

Can I reset bot configuration?

• Yes! Use /reset (Administrator only) to reset ALL:
• • Welcome and leave messages removed
• • All reaction role configs deleted
• • Leveling system disabled + all user XP/levels cleared
• • Scheduled messages cancelled immediately
• • Ticket system removed (channels must be deleted manually)
• • Reaction role panel messages deleted automatically
• Changes apply IMMEDIATELY without bot restart
• Use with caution - this cannot be undone!

Do slash commands work immediately?

Slash commands register globally and appear within 5-10 minutes after bot joins (Discord API propagation delay). If commands don't appear: ensure bot has Administrator permission, check bot is online, try removing and re-inviting bot.

Why would I self-host?

• Complete control over bot code and data
• Customize features and add your own commands
• No reliance on external servers
• Perfect for learning Node.js and discord.js
• Can run on your own hardware (Raspberry Pi, home server)
• Full access to logs and debugging

What do I need to self-host?

• Node.js 18.0.0 or higher
• Discord Bot Token (from Discord Developer Portal)
• Client ID (your bot's application ID)
• Basic command line knowledge
• 24/7 server or cloud hosting (Railway, Heroku, VPS)
• For Railway: Persistent volume for data storage

Where can I find setup instructions?

• Complete guides in GitHub repository:
• • README.md - Basic setup and features
• • DEPLOYMENT.md - Production deployment guide
• • .env.example - Environment variable template
• Step-by-step instructions for:
• • Local development setup
• • Railway deployment with volumes
• • Docker deployment
• • Environment variable configuration

Can I modify the bot code?

Yes! Discord Role Guardian is open source under MIT License. Modify, customize, and extend freely. The codebase includes detailed comments explaining every function. Contributions welcome on GitHub!

What hosting platforms are supported?

• Recommended: Railway (with persistent volumes)
• Also works on: Heroku, Render, DigitalOcean, AWS, VPS, Raspberry Pi
• Requires: Node.js support and persistent storage
• Free tier options available on Railway (500 hours/month)
• Health check endpoint at /health for monitoring

How do I set up UptimeRobot monitoring?

• 1. Create free UptimeRobot account (50 monitors, 5-min intervals)
• 2. Add HTTP monitor with your bot's health endpoint URL
• 3. Configure email alerts for downtime
• 4. View uptime stats on our /status page (UptimeRobot API integration)
• 5. Bot includes /health endpoint for monitoring
• Health endpoint returns: bot status, uptime, server count, timestamp

The bot isn't responding to commands. What should I do?

• 1. Check bot online status (green dot in member list)
• 2. Verify Administrator permission is granted
• 3. Wait 5-10 minutes after inviting (slash command propagation)
• 4. Type / in chat to see if bot commands appear
• 5. Check bot has View Channel and Send Messages permissions
• 6. Try removing and re-inviting with proper permissions

Reaction roles aren't working. How do I fix this?

• Role Hierarchy Issue:
• • Bot's role MUST be ABOVE all roles it assigns
• • Go to Server Settings → Roles
• • Drag bot's role above reaction roles
• Permission Issues:
• • Bot needs Manage Roles permission
• • Bot needs Add Reactions permission
• • Bot needs Read Message History
• Configuration Issues:
• • Verify correct message ID format
• • Check emoji is valid (custom emojis must be from your server)
• • Use /remove-reaction-roles to reset and try again

Members aren't earning XP. What's wrong?

• 1. Enable leveling: /setup-leveling enabled:true
• 2. Bot needs Read Message History permission
• 3. XP cooldown: Users earn XP once per 60 seconds (anti-spam)
• 4. Bot must see messages (check channel permissions)
• 5. Check bot role has Manage Roles permission (for level rewards)
• 6. Leveling is per-guild - XP doesn't transfer between servers

Scheduled messages aren't sending. Why?

• Check these common issues:
• • Bot must be online at scheduled time
• • Verify correct timezone offset (use UTC if unsure)
• • Check channel still exists and bot has permission
• • For monthly: Days 29-31 don't exist in all months
• • Use /list-scheduled to verify message is active
• • One-time messages auto-remove after sending
• If needed, use /remove-scheduled and recreate with correct settings

Data was lost after bot restart. What happened?

• Railway Deployment:
• • Persistent volumes required for data storage
• • Check Railway dashboard → Variables → Volumes
• • DATA_PATH must point to mounted volume (/app/data)
• Self-Hosting:
• • Ensure /data folder has write permissions
• • Check logs for file write errors
• • Verify NODE_ENV and DATA_PATH variables
• All data stored in /data/config.json - backup regularly!

How do I report bugs or request features?

• GitHub Issues (preferred):
• • Visit: github.com/nayandas69/discord-role-guardian/issues
• • Use bug report template for bugs
• • Use feature request template for new features
• • Include bot version, command used, and error details
• We actively monitor issues and welcome contributions!
• Check existing issues before creating duplicates

Can I get help if I'm stuck?

• Multiple support channels available:
• • Documentation page - Full command reference and guides
• • GitHub Issues - Bug reports and feature requests
• • GitHub Discussions - Questions and community help
• • Contact form on homepage
• Before asking, check:
• • FAQ page (you're here!)
• • Documentation page for detailed guides
• • GitHub issues for similar problems

What are the bot's limitations?

• Technical Limitations:
• • JSON storage (not suitable for 10,000+ users per guild)
• • XP formula is fixed (L×L×100) - not customizable
• • No XP decay or seasonal resets
• • Scheduled messages require bot online at send time
• • Max 5 staff roles per ticket system
• Feature Limitations:
• • Slash commands only (no custom prefix)
• • No built-in dashboard (code is dashboard-ready)
• • No XP transfer between servers
• • Scheduled messages are text-only (no embeds)
• • Leave messages only for members who joined while bot online