Skip to content

13. FAQ

Jump to bottom Edit New page
ad1107 edited this page May 24, 2025 · 1 revision

Frequently Asked Questions

Common questions and answers about UtilsBot+ setup, usage, and troubleshooting.

📋 Table of Contents

General Questions

What is UtilsBot+?

UtilsBot+ is a modern, feature-rich Discord bot built with Python 3.11+ that provides comprehensive utilities including:

  • 🤖 AI integration with Google Gemini
  • 🎮 Interactive games (Wordle)
  • 🌐 Network tools (screenshots, IP lookup, URL unshortening)
  • 🔒 Security tools (TOTP, QR codes, password generation)
  • ⚙️ Developer utilities (code evaluation, hot reload)

Is UtilsBot+ free to use?

Yes! UtilsBot+ is completely free and open-source. It uses free tiers of external APIs:

  • Google Gemini: 15 requests/minute (free tier)
  • IP Geolocation: 1000 requests/month (free tier)
  • Screenshot API: Optional paid service for enhanced screenshots

What makes UtilsBot+ different from other bots?

  • Slash Commands Only: Modern Discord UX with no prefix commands
  • AI-Powered: Built-in Google Gemini integration for intelligent responses
  • Security-First: Permission layers, input validation, and user whitelisting
  • Developer-Friendly: Hot reload, code evaluation, and comprehensive error handling
  • Production-Ready: Structured logging, database integration, and monitoring

Can I self-host UtilsBot+?

Absolutely! UtilsBot+ is designed for easy self-hosting with:

  • Docker support for one-command deployment
  • Comprehensive setup scripts
  • Multiple database options (SQLite, PostgreSQL, MySQL)
  • Cloud platform deployment guides

Setup & Installation

What are the system requirements?

Minimum Requirements:

  • Python 3.11 or higher
  • 512MB RAM
  • 2GB storage
  • Internet connection for Discord API and external services

Recommended:

  • Python 3.12
  • 1GB+ RAM
  • 5GB+ storage
  • Dedicated server or VPS

How do I get a Discord bot token?

  1. Go to the Discord Developer Portal
  2. Click "New Application" and give it a name
  3. Go to "Bot" section and click "Add Bot"
  4. Copy the token under "Token" section
  5. Important: Keep this token secret and never share it publicly

How do I get a Google Gemini API key?

  1. Visit Google AI Studio
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Copy the generated API key
  5. The free tier provides 15 requests per minute

What permissions does the bot need?

Essential Permissions:

  • ✅ Send Messages
  • ✅ Use Slash Commands
  • ✅ Embed Links
  • ✅ Attach Files (for screenshots and QR codes)
  • ✅ Read Message History

Optional Permissions:

  • 📊 View Server Members (for analytics)
  • 🔧 Manage Messages (for bot management)

How do I invite the bot to my server?

  1. Go to Discord Developer Portal → Your Application → OAuth2 → URL Generator
  2. Select scopes: bot and applications.commands
  3. Select the permissions listed above
  4. Copy the generated URL and open it in your browser
  5. Select your server and authorize the bot

Commands & Features

Why are there only slash commands?

Slash commands provide a better user experience:

  • Discoverability: Users can see available commands with autocomplete
  • Validation: Built-in parameter validation and help text
  • Performance: More efficient than scanning all messages for prefixes
  • Security: Better permission handling and user identification

How do I see all available commands?

Use /help to see all commands organized by category:

  • Information: /info, /ping, /version, /help
  • AI: /ask, /chat
  • Games: /wordle
  • Network: /screenshot, /ip, /unshorten
  • Tools: /totp, /qr, /base64, /hash, /password
  • Admin: Developer and whitelist commands

What is the whitelist system?

The whitelist system allows bot owners to restrict access during beta testing:

  • Closed Beta: Only whitelisted users can use the bot
  • Developer Override: Bot developers always have access
  • Database Tracking: Whitelist status stored in database
  • Commands: /whitelist add/remove/list/check (dev-only)

How do game statistics work?

The bot tracks comprehensive game statistics:

  • Games Played: Total number of games started
  • Win Rate: Percentage of games won
  • Best Score: Best performance achieved
  • Achievements: Special milestones and accomplishments
  • Persistent: Stats saved across bot restarts

Are my conversations with the AI private?

Yes, your privacy is protected:

  • No Storage: Conversations are not permanently stored
  • Rate Limiting: 3 questions per minute to prevent spam
  • Ephemeral Options: Most AI responses can be made private
  • Context Aware: AI has context about Discord but not personal data

API & Integrations

Which external APIs does the bot use?

Core APIs:

  • Google Gemini 1.5 Flash: AI responses and chat (free tier: 15/min)
  • ip-api.com: IP geolocation lookup (free tier: 1000/month)

Optional APIs:

  • ScreenshotOne: Enhanced website screenshots (paid service)
  • RapidAPI: Additional API endpoints (varies by service)

What happens if an API is down?

UtilsBot+ includes comprehensive error handling:

  • Graceful Degradation: Features fail safely without crashing
  • User Feedback: Clear error messages explaining issues
  • Fallbacks: Local alternatives where possible (e.g., screenshot placeholders)
  • Retry Logic: Automatic retry for temporary failures

How do I get enhanced screenshot features?

  1. Sign up for ScreenshotOne
  2. Get your API key from the dashboard
  3. Add SCREENSHOT_API_KEY=your_key to your .env file
  4. Restart the bot to enable enhanced features

Enhanced Features:

  • Higher resolution screenshots
  • Full-page capture
  • Custom viewport sizes
  • Ad blocking
  • Faster processing

Are there rate limits on APIs?

Yes, each API has different limits:

Google Gemini (Free Tier):

  • 15 requests per minute
  • 1 million input tokens per minute
  • 8,192 output tokens per response

IP Geolocation:

  • 1,000 requests per month
  • No daily limits

Bot Rate Limiting:

  • AI commands: 3 per minute per user
  • Other commands: 5 per minute per user
  • Global cooldown: 2 seconds between commands

Troubleshooting

The bot won't start - what should I check?

Common Issues:

  1. Invalid Bot Token: Verify token in Discord Developer Portal
  2. Missing Dependencies: Run pip install -r requirements.txt
  3. Python Version: Ensure Python 3.11+ is installed
  4. Environment Variables: Check .env file exists and has required values
  5. Permissions: Ensure bot has necessary permissions in Discord

Debug Steps:

# Check Python version
python --version

# Verify dependencies
pip list | grep discord

# Test environment loading
python -c "from config.settings import settings; print(settings.bot_token[:10])"

# Check logs
tail -f logs/bot.log

Commands aren't showing up in Discord

Solutions:

  1. Sync Commands: Use /sync command (dev-only)
  2. Check Permissions: Ensure bot has Use Slash Commands permission
  3. Wait for Propagation: Discord can take up to 1 hour to update commands
  4. Guild vs Global: Try syncing to specific guild first: /sync guild

AI commands return errors

Common Causes:

  1. Invalid API Key: Check Gemini API key in .env
  2. Rate Limiting: Wait and try again (3 questions/minute limit)
  3. API Quota: Verify you haven't exceeded free tier limits
  4. Network Issues: Check internet connection and API status

Database errors on startup

Solutions:

  1. Initialize Database: Run python migrations/init_db.py
  2. Check Permissions: Ensure write access to data/ directory
  3. Database URL: Verify DATABASE_URL format in .env
  4. SQLite Issues: Delete data/bot.db and reinitialize if corrupted

Memory or performance issues

Optimization Tips:

  1. Reduce Log Level: Set LOG_LEVEL=WARNING in production
  2. Database Cleanup: Regularly clean old command logs
  3. Resource Monitoring: Use htop or similar to monitor usage
  4. Connection Pooling: Configure database connection limits

Development & Contributing

How can I contribute to UtilsBot+?

Ways to Contribute:

  1. Bug Reports: Submit issues on GitHub with detailed information
  2. Feature Requests: Propose new features or improvements
  3. Code Contributions: Submit pull requests with new features or fixes
  4. Documentation: Improve wiki pages and code documentation
  5. Testing: Help test new features and report issues

What's the development setup process?

# Clone repository
git clone https://github.com/ad1107/utils-bot-plus.git
cd utils-bot-plus

# Create development environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Install development dependencies
pip install -r requirements-dev.txt

# Copy environment template
cp .env.example .env
# Edit .env with your credentials

# Initialize database
python migrations/init_db.py

# Run in development mode
python main.py

How do I add a new command?

Example: Adding a /hello command:

  1. Choose the appropriate cog (e.g., cogs/tools.py)
  2. Add the command function:
@app_commands.command(name="hello", description="Say hello to the bot")
@app_commands.describe(name="Your name (optional)")
async def hello(self, interaction: discord.Interaction, name: str = None):
    greeting = f"Hello {name}!" if name else "Hello there!"
    embed = create_success_embed("Greeting", greeting)
    await interaction.response.send_message(embed=embed)
  1. Add error handling and logging as needed
  2. Test the command thoroughly
  3. Update documentation

What coding standards should I follow?

Code Style:

  • Formatting: Use Black formatter (black .)
  • Imports: Use isort for import organization (isort .)
  • Type Hints: Include type annotations for all functions
  • Docstrings: Document all public functions and classes
  • Error Handling: Use try/except blocks for external API calls

Git Workflow:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/new-command
  3. Make your changes with clear, descriptive commits
  4. Test thoroughly
  5. Submit a pull request with detailed description

How do I run tests?

# Install development dependencies
pip install -r requirements-dev.txt

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=.

# Run specific test file
python -m pytest tests/test_commands.py

# Run linting
black --check .
isort --check-only .
mypy .

🔗 Related Pages

📝 Still Need Help?

If you couldn't find the answer to your question:

  1. Check the logs: Look in logs/bot.log for detailed error information
  2. Search GitHub Issues: Your question might already be answered
  3. Create an Issue: Submit a detailed bug report or feature request
  4. Join the Community: Connect with other users and developers

When asking for help, please include:

  • Bot version (/version command output)
  • Operating system and Python version
  • Complete error messages from logs
  • Steps to reproduce the issue
  • Your configuration (without sensitive tokens)
Add a custom footer
Add a custom sidebar
Clone this wiki locally