Bot Setup

Complete guide for setting up and configuring the LuaBeans - Community Manager Discord bot.

Overview

The Discord bot provides:

• Automated role syncing - Syncs Discord roles to department memberships

• Slash commands - User and admin commands for portal interaction

• Real-time notifications - Event handlers for member updates

• Announcements - Create announcements from Discord

• Badge generation - Generate department badges

• User management - Onboard, promote, demote, offboard users

Prerequisites

• Discord bot application created

• Bot invited to your Discord server

• Required bot permissions configured

• DISCORD_BOT_TOKEN set in web panel .env

Discord Application Setup

Step 1: Create Discord Application

1. Go to Discord Developer Portal

2. Click New Application

3. Name it (e.g., "LuaBeans Bot")

4. Click Create

Step 2: Create Bot User

1. Navigate to Bot in the left sidebar

2. Click Add Bot

3. Click Yes, do it!

4. Note your Bot Token (click Reset Token if needed)

   • This is your DISCORD_BOT_TOKEN for the .env file

Step 3: Enable Required Privileges

In the Bot section, scroll to Privileged Gateway Intents and enable:

• ✅ SERVER MEMBERS INTENT - Required to read guild members

• ✅ MESSAGE CONTENT INTENT - Required for message commands (if used)

Step 4: Generate Invite URL

In OAuth2 → URL Generator:

Scopes:

• ✅ bot

• ✅ applications.commands (for slash commands)

Bot Permissions:

• ✅ View Channels

• ✅ Send Messages

• ✅ Use Slash Commands

• ✅ Embed Links

• ✅ Attach Files (for badge generation)

• ✅ Read Message History

• ✅ Manage Roles (for role syncing, if needed)

Copy the generated URL and invite the bot to your server.

Bot Installation

Step 1: Ensure Bot Token is Configured

In your web panel .env file:

DISCORD_BOT_TOKEN=your_bot_token_here

Step 2: Start the Bot

npm run bot

Or in production using a process manager:

# Using PM2
pm2 start bot/index.js --name luabeans-bot

# Using systemd (see deployment guide)
systemctl start luabeans-bot

Step 3: Deploy Slash Commands

Deploy commands to Discord:

npm run bot:deploy

Note: Global commands can take up to 1 hour to propagate. Guild-only commands are instant.

Command Registration

Global vs Guild Commands

Global Commands (DISCORD_BOT_PUBLIC_COMMANDS=true):

• Available in all servers

• Can take up to 1 hour to update

• Good for public bots

Guild Commands (DISCORD_BOT_PUBLIC_COMMANDS=false):

• Available only in specified guild (DISCORD_GUILD_ID)

• Update instantly

• Recommended for private servers

Re-registering Commands

If commands don't appear:

1. Check bot is in server

2. Verify bot has permissions

3. Redeploy commands: npm run bot:deploy

4. Wait for propagation (global: up to 1 hour, guild: instant)

Bot Permissions

Required Permissions

The bot needs these permissions in your Discord server:

• View Channels - Read channel messages

• Send Messages - Respond to commands

• Use Slash Commands - Execute slash commands

• Embed Links - Send rich embeds

• Attach Files - Upload badge images

• Read Message History - Read previous messages

Optional Permissions

• Manage Roles - If you want bot to manage roles automatically

• Manage Messages - For message management features

Bot Events

The bot automatically handles these Discord events:

guildMemberAdd

When a new member joins:

• Automatically syncs user to database

• Assigns departments based on Discord roles

• Updates LEO rank assignments

No configuration needed - Works automatically.

guildMemberUpdate

When a member's roles change:

• Syncs updated roles to database

• Updates department memberships

• Refreshes LEO rank assignments

No configuration needed - Works automatically.

messageCreate

When a message is created:

• Checks for Tebex purchase messages (if configured)

• Processes purchase data for garage system

Configuration: Requires Tebex bot integration setup.

Verification

Check Bot is Running

Look for console messages:

[LuaBeans - Community Manager Bot] ready

Test Bot Commands

1. Type /ping in any channel

2. Bot should respond with "pong"

3. If command doesn't appear, wait or check registration

Verify Permissions

1. Try /syncme command

2. Should respond successfully

3. Check database for updated user record

Configuration

Environment Variables

Variable	Required	Description
DISCORD_BOT_TOKEN	Yes	Bot token from Discord Developer Portal
DISCORD_GUILD_ID	Yes	Primary Discord server ID
DISCORD_BOT_PUBLIC_COMMANDS	No	true for global, false for guild-only
DISCORD_NOTIFICATIONS_CHANNEL_ID	No	Channel for bot notifications
DISCORD_NOTIFY_APPLICATION_SUBMITS	No	Notify when applications are submitted
DISCORD_NOTIFY_FORUM_THREADS	No	Notify when forum threads are created

Bot Behavior

The bot automatically:

• Syncs users on join

• Updates users when roles change

• Handles rate limiting gracefully

• Logs errors to console

Troubleshooting

Bot Not Responding

Issue: Commands don't work

Solutions:

1. Check bot is online (green dot in Discord)

2. Verify DISCORD_BOT_TOKEN is correct

3. Check console for errors

4. Verify bot has required permissions

5. Try restarting the bot

Commands Not Appearing

Issue: Slash commands don't show up

Solutions:

1. Wait 1 hour for global commands (or set DISCORD_BOT_PUBLIC_COMMANDS=false)

2. Redeploy commands: npm run bot:deploy

3. Verify bot is in server

4. Check bot has applications.commands scope

5. Restart Discord client (sometimes cached)

Rate Limiting

Issue: Bot shows rate limit warnings

Solutions:

• Bot handles rate limits automatically

• Reduce command frequency if excessive

• Check logs for specific routes being limited

Permission Errors

Issue: Bot can't perform actions

Solutions:

1. Check bot's role position (must be above roles it manages)

2. Verify required permissions are granted

3. Check channel-specific permissions

4. Ensure bot role has correct permissions

Database Connection

Issue: Bot can't access database

Solutions:

1. Verify database credentials in .env

2. Check database is running

3. Verify web panel can connect (tests database config)

4. Check network connectivity

Production Deployment

Process Management

Use a process manager to keep bot running:

PM2:

pm2 start bot/index.js --name luabeans-bot
pm2 save
pm2 startup

systemd: See Deployment Guide for systemd service files.

Monitoring

Monitor bot health:

• Check logs regularly

• Monitor for error messages

• Watch for rate limit warnings

• Verify commands are working

Updates

When updating bot commands:

1. Update code

2. Restart bot

3. Redeploy commands: npm run bot:deploy

4. Test commands work

Security Best Practices

1. Never share bot token - Keep DISCORD_BOT_TOKEN secret

2. Limit bot permissions - Only grant needed permissions

3. Monitor bot activity - Check audit logs regularly

4. Use guild-only commands - Set DISCORD_BOT_PUBLIC_COMMANDS=false for private servers

5. Keep bot updated - Update dependencies regularly

Related Documentation

• Bot Commands Reference - All available commands

• Bot Events - Event handlers and automation

• Bot Permissions - Permission requirements

• Deployment Guide - Production setup