ChirpBot Documentation

Overview

ChirpBot is a comprehensive Discord moderation and utility bot designed for gaming communities, with specialized features for Trailmakers and other popular games. The bot provides advanced moderation tools, content filtering, ticketing systems, and game-specific utilities.

Key Features

• Advanced Moderation: Automated warnings, timeouts, and bans with intelligent escalation
• Content Filtering: NSFW detection, spam protection, and scam link blocking
• Logging System: Comprehensive activity logging with forum channel support for community servers
• Ticket System: Professional support ticket management with thread-based organization
• Command Packs: Modular game-specific command collections
• User Restrictions: Granular control over user permissions and channel access
• Time-Based Roles: Automatic role assignment based on server membership duration
• Backup System: Complete server configuration backup and restore

Supported Games

• Trailmakers - Primary focus with extensive mod tools and utilities
• Minecraft - Building tools, server utilities, and player information
• Rust - Raid calculators, loot guides, and crafting tools
• Valheim - Progression guides, boss strategies, and world seeds
• Satisfactory - Factory optimization and production calculators

Getting Started

Initial Setup

When ChirpBot is first added to your server, you'll need to configure it using the /setup command. The bot offers two setup modes:

Quick Setup (Recommended)

• Creates a "ChirpBot" category with organized channels
• Sets up proper permissions and moderator roles
• Enables recommended features based on your server type
• Configures all available command packs based on your subscription
• Sets up content filtering and spam protection

Manual Setup

Use specific options to configure individual settings:

/setup mod_role:@ModeratorRole content_filter:True
/setup warning_threshold:3 spam_protection:True
/setup command_packs:trailmakers,minecraft

Critical Setup Requirements

How to Fix Role Position:

1. Go to Server Settings → Roles
2. Find ChirpBot's role in the list
3. Drag it above all user roles you want to moderate
4. Save changes

Required Permissions

ChirpBot needs these permissions to function properly:

• Manage Roles - For time-based roles and role selection
• Manage Channels - For creating log/ticket channels
• View Audit Log - For enhanced moderation logging
• Manage Messages - For content filtering and purging
• Moderate Members - For timeouts
• Kick/Ban Members - For moderation actions
• Manage Threads - For forum-based logging (community servers)

Channel Organization

ChirpBot creates an organized structure under the "ChirpBot" category:

• 📝 logs - Activity logging (forum channel for community servers)
• 📊 reports - User reports (may share with logs)
• 🎫 tickets - Support ticket management (forum for community servers)

Command Reference

ChirpBot commands are organized by permission level and category. All commands use Discord's slash command system.

Utilities

Moderation

Core Moderation

Advanced Moderation

Channel Management

Moderator Utilities

Fun Commands

Utility Commands

Support System

Context Menu Commands

Right-click on messages or users to access these commands:

• Report Message - Quickly report a problematic message
• User Info - Get detailed information about a user
• Check Rules - Analyze a message against server rules (moderators)
• Translate Message - Translate a message to English

Moderation System

Warning System

ChirpBot's warning system provides automated escalation and tracking:

How Warnings Work

• Automatic escalation: Configurable thresholds (default: 3 warnings = ban)
• Expiring warnings: Warnings automatically expire after set days (default: 30 days)
• Manual management: Clear warnings with /clearwarnings
• Comprehensive tracking: All warnings are logged with timestamps and reasons

Warning Escalation Example

1. Warning 1: User receives warning message
2. Warning 2: User receives second warning with escalation notice
3. Warning 3: User is automatically banned (if threshold is 3)

Content Filtering

Advanced content filtering protects your server from inappropriate content:

Filter Types

• NSFW Detection: AI-powered image scanning for new users and users with recent warnings
• Explicit Content: Text-based filtering using comprehensive word lists
• Spam Protection: Rate limiting with automatic warnings and escalation
• Scam Protection: Blocks known malicious domains and suspicious links
• Custom Filters: Add server-specific filtered words and phrases

Filter Actions

• Message Deletion: Inappropriate content is automatically removed
• User Notification: Users are informed when their content is filtered (optional)
• Automatic Warnings: Content violations add to warning count
• Progressive Timeouts: Repeated violations result in increasing timeout durations
• Suspicious Content Logging: Moderators are notified of potentially problematic content

User Restrictions

Granular control over user permissions and behavior:

Restriction Types

• Messages: Prevent user from sending messages
• Reactions: Block user from adding reactions
• Voice: Restrict access to voice channels
• Slash Commands: Disable bot command usage
• Channel Access: Limit user to specific channels only
• Rich Content: Prevent attachments, embeds, and links

Applying Restrictions

/restrict user:@username type:messages reason:"Spam violations"
/restrict user:@username type:channels channels:#general,#help
/restrict user:@username type:voice reason:"Disruptive behavior"

User Monitoring

Track and log activity from specific users:

• Message Logging: All messages from monitored users are logged
• Image Tracking: Images posted by monitored users are downloaded and logged
• Activity Timeline: Complete activity history in dedicated log threads
• Real-time Notifications: Immediate alerts for monitored user activity

Spam Protection

Intelligent spam detection and prevention:

Spam Detection

• Rate Limiting: Configurable message thresholds (default: 5 messages in 5 seconds)
• Pattern Recognition: Detects repeated messages and suspicious patterns
• Progressive Warnings: Automatic escalation from warnings to timeouts to bans
• Whitelist System: Owners and moderators are exempt from spam detection

Auto-Slowmode

Automatic channel slowmode activation during high activity:

• Threshold Detection: Activates when message count exceeds limit in time window
• Automatic Removal: Slowmode is removed when activity normalizes
• Configurable Settings: Customize thresholds, duration, and time windows
• Channel-Specific: Works independently across different channels

Timeout Management

Comprehensive timeout tracking and management:

• Automatic Tracking: All timeouts are logged and tracked
• Duration Management: Supports timeouts from seconds to 28 days
• Reason Logging: All timeouts include detailed reasons
• Removal Tracking: Early timeout removals are logged

Server Configuration

Channel Permissions

Control which commands can be used in specific channels to organize your server:

Permission Types

• Category Permissions: Enable/disable entire command categories
• Individual Commands: Control specific commands per channel
• Global Override: Owner and moderator commands work everywhere

Examples

# Enable fun commands in specific channels
/manageperms add channel:#bot-commands category:fun

# Allow specific utility commands in general chat
/manageperms add channel:#general command:help
/manageperms add channel:#general command:serverinfo

# Remove permissions
/manageperms remove channel:#serious-chat category:fun

# View current settings
/manageperms view channel:#bot-commands

Content Filter Configuration

Customize automatic content filtering for your server:

Filter Settings

Warning System Configuration

Spam Protection Settings

Time-Based Roles

Automatically assign roles based on server membership duration:

Creating Time-Based Roles

# Add roles for different membership durations
/timedroles add role:@1Week days:7
/timedroles add role:@1Month days:30
/timedroles add role:@Veteran days:365

# View all time-based roles
/timedroles list

# Remove a time-based role
/timedroles remove role:@1Week

How It Works

• Automatic Assignment: Roles are assigned when users reach the required days
• Retroactive: Existing members get roles based on their join date
• Progressive: Users accumulate higher-tier roles over time
• Fallback Logic: Smart handling for returning members

Auto-Slowmode Configuration

Automatic slowmode activation during high channel activity:

Backup System

Protect your server configuration with comprehensive backups:

What's Included in Backups

• Server Settings: All bot configuration options
• Warnings: Complete warning history
• Role Messages: Interactive role selection setups
• Channel Permissions: Command access configurations
• Time-Based Roles: Automatic role assignment rules
• Content Filters: Custom filtered terms and settings

Backup Management

# Create a backup
/backup

# Restore from backup
/importbackup

# Automatic cleanup keeps last 5 backups per server

Logging System

ChirpBot provides comprehensive activity logging with different approaches for community and regular servers.

Forum Channel Logging (Community Servers)

For Discord community servers, ChirpBot uses advanced forum channel logging:

Per-User Threads

• Individual Threads: Each user gets their own dedicated logging thread
• Thread Names: Format: "Username (UserID)" for easy identification
• Visual Tags: Color-coded tags show user status (banned, muted, reported, etc.)
• Automatic Management: Threads are created, archived, and cleaned up automatically

Thread Tags

• 🏷️ Log: Basic logging tag for all threads
• 🚫 Banned: User is currently banned
• 🔇 Muted: User is currently timed out
• 📢 Reported: User has active reports
• 🎫 Ticket: Ticket-related activity
• 👁️ Monitoring: User is being monitored
• 🔒 Restricted: User has active restrictions

Performance Optimization

• Automatic Archiving: Inactive threads are archived based on server activity level
• Smart Cleanup: Threads are archived after periods of inactivity
• Resource Management: System prevents Discord's thread limits from being exceeded

Text Channel Logging (Regular Servers)

For non-community servers, all logging goes to a single text channel:

• Centralized Logging: All events in one channel
• User Mentions: Easy identification with @mentions
• Embedded Messages: Rich formatting for better readability

Logged Events

User Activity

• Join/Leave Events: User joins and leaves with account age
• Message Activity: Message edits, deletions, and bulk deletions
• Voice Activity: Voice channel joins, leaves, and moves
• Role Changes: Role additions and removals (manual and automatic)

Moderation Actions

• Warnings: All warnings issued, cleared, or expired
• Timeouts: Mutes applied and removed
• Bans/Kicks: All ban and kick actions
• Restrictions: User restriction changes
• Monitoring: Start/stop user monitoring

Content Monitoring

• Image Posting: Images with NSFW scanning results
• Content Violations: Filtered content with violation types
• Spam Detection: Spam warnings and escalations
• Suspicious Content: Flagged content for moderator review
• Monitored Users: All activity from users under monitoring

System Events

• Command Usage: Who used what commands and when
• Ticket Activity: Ticket creation, replies, and closures
• Report Activity: User reports and their resolutions
• Configuration Changes: Settings modifications

Image Logging and NSFW Detection

Advanced image handling with security and safety features:

Automatic Image Scanning

• New User Scanning: All images from users who joined within 2 days
• Warning-Based Scanning: Images from users with recent warnings (last 30 days)
• Trusted User Exemption: Owners and moderators are not scanned
• AI-Powered Detection: Uses Mistral AI for NSFW content detection

Image Processing

• Secure Downloads: Only from authorized Discord CDN domains
• Format Validation: Strict file signature verification
• Rate Limiting: Prevents abuse and excessive processing
• Spoiler Protection: Potentially problematic images are spoilered in logs

Security Features

• Malware Detection: Blocks suspicious file signatures
• Content Scanning: Checks for embedded scripts or malicious content
• Size Limits: Maximum 20MB file size for processing
• Automatic Cleanup: Processed images are cleaned up after logging

Log Retention and Management

• Automatic Cleanup: Old logs are periodically cleaned
• Thread Archiving: Inactive forum threads are archived
• Performance Monitoring: System automatically manages resource usage
• Backup Integration: Important logs are included in server backups

Ticket System

Professional support ticket management for user assistance and issue resolution.

Creating Tickets

Users can create tickets through multiple methods:

Slash Commands

# Create a new support ticket
/ticket create

# Create a ticket with a specific message
/ticket create message:"I need help with server rules"

Report System

# Report a user (creates a ticket)
/report user:@username reason:"Harassment in voice chat"

# Report a message (right-click context menu)
Report Message → "Spam messages"

# Send general inquiry
/report inquiry:"Question about server events"

Ticket Structure

Community Servers (Forum Channels)

• Forum Channel: Dedicated "tickets" forum under ChirpBot category
• Individual Threads: Each ticket gets its own thread
• Thread Tags: Visual status indicators (Open, Resolved, Urgent)
• Persistent History: Complete conversation history preserved

Regular Servers (Text Channels)

• Individual Channels: Each ticket gets a dedicated text channel
• Channel Naming: Format: "ticket-username-id"
• Category Organization: All ticket channels under ChirpBot category
• Permission Management: Only ticket creator and moderators can see

Ticket Management

User Commands

Moderator Commands

Ticket Features

Automatic Organization

• Category Placement: All tickets organized under ChirpBot category
• Permission Setup: Automatic permission configuration for privacy
• Status Tracking: Real-time status updates (Open, Closed, etc.)
• ID System: Unique ticket IDs for easy reference

Abuse Prevention

• Rate Limiting: Users can't spam ticket creation
• Blocking System: Problematic users can be blocked from creating tickets
• Automatic Cleanup: Old closed tickets are cleaned up periodically
• Duplicate Detection: Prevents multiple tickets from same user

Integration with Reports

• Unified System: Reports create tickets for follow-up
• Context Preservation: Original report context is maintained
• Automatic Assignment: Reports are automatically triaged
• Resolution Tracking: Complete audit trail for all reports

Ticket Lifecycle

Creation → Active → Resolution

1. Creation: User creates ticket with issue description
2. Assignment: Ticket appears in designated channel/forum
3. Communication: Back-and-forth between user and moderators
4. Resolution: Issue is resolved through discussion
5. Closure: Ticket is closed by user or moderator
6. Archival: Closed tickets are archived for record-keeping

Status Indicators

• 🟢 Open: Active ticket awaiting response
• 🔴 Closed: Ticket has been resolved and closed
• 🟡 Urgent: High-priority ticket requiring immediate attention
• 🔵 In Progress: Moderator is actively working on the ticket

Best Practices

For Users

• Be Specific: Provide detailed descriptions of your issue
• One Issue Per Ticket: Create separate tickets for different problems
• Be Patient: Allow reasonable time for moderator response
• Follow Up: Respond to moderator questions promptly

For Moderators

• Timely Response: Acknowledge tickets within reasonable time
• Clear Communication: Provide clear, helpful responses
• Documentation: Keep records of resolutions for future reference
• Escalation: Know when to escalate to higher staff levels

Command Packs

ChirpBot uses a modular command pack system, allowing servers to enable specific game-focused command collections.

Pack System Overview

• Modular Design: Enable only the packs your community needs
• Core Pack: Essential moderation and utility commands (always enabled)
• Game Packs: Specialized commands for specific games
• Premium Packs: Enhanced features available with Nest Builder subscription

Managing Command Packs

During Setup

Command packs are configured during the initial /setup process:

• Quick Setup: Automatically enables all available packs based on your subscription
• Manual Setup: Choose specific packs to enable

Manual Pack Configuration

# Enable specific packs
/setup command_packs:trailmakers,minecraft

# Enable all available packs
/setup command_packs:all

# Disable all non-core packs
/setup command_packs:none

Pack Requirements

• Core Pack: Always enabled, no subscription required
• Trailmakers Pack: Free for all servers
• Game Packs: Require Nest Builder premium subscription

Premium Features - Nest Builder

Nest Builder is ChirpBot's premium subscription that unlocks enhanced features and additional command packs for your server.

Premium Benefits

Enhanced Command Packs

• Minecraft Pack: Complete Minecraft utilities and tools
• Rust Pack: Survival calculators and guides
• Valheim Pack: Viking survival assistance
• Satisfactory Pack: Factory optimization tools

Advanced Core Features

• Enhanced AI Tools: Advanced mod creation and code analysis
• Priority Support: Faster response times for technical issues
• Extended Limits: Higher rate limits for API-dependent commands
• Beta Features: Early access to new functionality

Exclusive Utilities

• Advanced Analytics: Detailed server activity reports
• Custom Integration: Special features for large communities
• Extended Backup Storage: More backup retention

Subscription Management

How to Subscribe

1. Server Owner: Only server owners can purchase subscriptions
2. Bot Profile: Click on ChirpBot's profile in Discord
3. Subscribe: Follow the subscription flow
4. Automatic Activation: Features are enabled immediately

Subscription Features

• Server-Specific: Each server needs its own subscription
• Instant Activation: Commands are available immediately after purchase
• Automatic Renewal: Continuous access without interruption
• Cancellation: Can be cancelled at any time

Subscription Status

Check your subscription status and premium features:

• /help command: Shows premium status and available features
• Command availability: Premium commands appear in autocomplete when active
• Expiry notifications: Automatic reminders before subscription expires

Free vs Premium Comparison

Subscription Support

Common Questions

• Q: Can moderators subscribe?
  A: No, only the server owner can purchase subscriptions.
• Q: What happens if subscription expires?
  A: Premium commands are disabled, but all settings and data are preserved.
• Q: Can I transfer subscriptions?
  A: Subscriptions are tied to specific servers and cannot be transferred.
• Q: Do I get refunds?
  A: Follow Discord's standard refund policies for app subscriptions.

Technical Issues

• Subscription not activating: Wait up to 15 minutes for Discord's systems to sync
• Commands not appearing: Try running /help to refresh command list
• Billing questions: Contact Discord support for payment issues

Troubleshooting

Common issues and their solutions to help you get the most out of ChirpBot.

Permission Issues

"I don't have permission to use this command"

1. Check Role Requirements: Use /help to see command requirements
2. Verify Channel Permissions: Use /manageperms view to check current channel
3. Contact Owner: Ask server owner to configure permissions or enable packs
4. Check Subscription: Premium commands require Nest Builder subscription

"ChirpBot can't moderate certain users"

1. Go to Server Settings → Roles
2. Find ChirpBot's role in the list
3. Drag it above all user roles you want to moderate
4. Save changes and test moderation commands

Channel and Setup Issues

"Commands aren't working in my channel"

# View permissions for specific channel
/manageperms view channel:#your-channel

# Add permissions if needed
/manageperms add channel:#your-channel category:fun
/manageperms add channel:#your-channel command:help

"Logging isn't working"

• Verify Channels: Ensure log channel exists and bot has permissions
• Check Category: Verify ChirpBot category wasn't accidentally deleted
• Re-run Setup: Use /setup to recreate channels if needed
• Permission Check: Bot needs Send Messages, Embed Links, Manage Threads

"Forum threads aren't working properly"

• Server must have Community feature enabled
• Bot needs Manage Threads and Create Public Threads permissions
• Forum channels require specific permission setup

Feature-Specific Issues

Content Filter Issues

• Adjust Settings: Use /setup to configure filtering
• Whitelist Users: Owners and moderators are automatically exempt
• Check Logs: Review filter logs to understand decisions

Ticket System Issues

• Check Permissions: Bot needs Manage Channels permission
• Category Limits: Discord limits channels per category (50)
• User Blocks: Check if user is blocked from creating tickets
• Channel Cleanup: Archive old ticket channels if needed

Time-Based Roles Issues

• Role Position: Ensure ChirpBot's role is above roles it assigns
• Permission Check: Bot needs Manage Roles permission
• User Activity: Roles are assigned when users are active (send messages)
• Manual Trigger: Users joining will get appropriate roles

Subscription and Premium Issues

"Premium commands not available after subscribing"

1. Wait for Sync: Allow up to 15 minutes for Discord systems to sync
2. Refresh Commands: Run /help to refresh command list
3. Check Owner: Only server owners can purchase subscriptions
4. Verify Purchase: Check Discord subscription settings

"Subscription expired but still showing active"

• Cache Delay: Changes may take up to 1 hour to fully propagate
• Restart Commands: Some commands may show temporarily
• Check Status: Use /help for current subscription status

Getting Additional Help

Built-in Help System

# General help
/help

# Permission debugging
/manageperms view

Support Channels

• Discord Support: Get in touch

Common Error Codes

Performance Guidelines

• Large Servers: Expect slightly longer response times in servers with 1000+ members
• Rate Limits: Respect command cooldowns to prevent temporary blocks
• Bulk Operations: Large purges or bulk actions may take time to complete
• Resource Management: ChirpBot automatically optimizes performance for your server size

Advanced Features

Advanced functionality for power users and large server management.

Advanced Restriction System

ChirpBot provides granular control over user behavior beyond simple timeouts:

Restriction Types

Advanced Restriction Examples

# Multiple restrictions
/restrict user:@username type:messages,reactions reason:"Spam violations"

# Channel-specific restriction
/restrict user:@username type:channels channels:#general,#help reason:"Probation"

# Voice channel restriction
/restrict user:@username type:voice reason:"Disruptive in voice"

# Remove all restrictions
/restrict user:@username type:remove

User Monitoring System

Comprehensive activity tracking for problematic users:

Monitoring Features

• Complete Message Logging: Every message logged with context
• Image Downloads: All images downloaded and stored in logs
• Activity Timeline: Chronological activity history
• Cross-Channel Tracking: Activity tracked across all channels
• Real-time Alerts: Immediate notifications for monitored activity

Monitor Management

# Start monitoring a user
/monitor user:@username action:start reason:"Suspicious behavior pattern"

# Stop monitoring
/monitor user:@username action:stop

# Check monitoring status
/monitor user:@username action:status

Advanced Logging Configuration

Forum Channel Optimization

For community servers using forum channels:

• Automatic Thread Management: Threads archived based on activity
• Tag Automation: Status tags updated automatically
• Performance Scaling: System adapts to server size and activity
• Resource Management: Prevents Discord thread limits

Log Retention Policies

• Active Threads: Kept active based on recent activity
• Inactive Archiving: Automated based on server activity level
• Historical Preservation: Important logs preserved long-term
• Storage Optimization: Automatic cleanup of redundant data

Backup and Disaster Recovery

Comprehensive Backup System

Complete server configuration protection:

• Settings Backup: All bot configurations
• Historical Data: Warnings, reports, and moderation history
• Role Configurations: Interactive role messages and time-based roles
• Permission Maps: Channel permission configurations
• Custom Content: Filtered terms and custom settings

Disaster Recovery

# Create comprehensive backup
/backup

# Restore from backup (overwrites current settings)
/importbackup

# Reset and clean slate (backup first!)
/reset delete_channels:true

Large Server Optimization

Performance Features for Large Communities

• Dynamic Rate Limiting: Cooldowns adjust based on server activity
• Intelligent Caching: Faster responses for frequently accessed data
• Batched Operations: Efficient processing of bulk actions
• Resource Scaling: System adapts to server size automatically

Auto-Slowmode for High Traffic

Automatic channel management during peak activity:

• Activity Detection: Monitors message rates per channel
• Graduated Response: Slowmode increases with activity level
• Automatic Removal: Slowmode removed when activity normalizes
• Channel-Specific: Independent operation across channels