🤖 Spy Bot

A Discord bot for monitoring presence, status, and voice channels with beautiful notifications and detailed statistics for each user!

🌍 Languages

🇺🇸 English
🇧🇷 Português

✨ Features

🎯 Basic Monitoring

Automatic notifications for joining, leaving, and changing voice channels (except excluded channel)
Status monitoring (online, idle, do not disturb, offline)
Platform detection (Mobile/Desktop) for joins and leaves
Beautiful messages using embeds and emojis
Data persistence in MongoDB

🏆 Rankings and Achievements System

Automatic achievements based on online time, voice activity, and engagement
Competitive rankings of the most active members
Achievement notifications when unlocked
Medals and badges for different types of activity

📊 Advanced Commands

```
!stats
```
— Detailed personal statistics
```
!top
```
— Ranking of the 10 most active members
```
!top voice
```
— Ranking of those who used voice the most
```
!achievements
```
— Your achievements
```
!compare @user1 @user2
```
— Compare users
```
!serverstats
```
— General server statistics
```
!clear
```
— Clear all messages from the current channel (requires permission)
```
!silence
```
— Shows a tutorial on how to mute the channel manually in Discord (via DM)
```
!help
```
— List of commands

⚠️ Alerts and Reminders

Inactivity alerts for absent members
Automatic notifications for inactive users
Flexible configuration of days for alerts

🔇 Silence System

User-controlled notifications - Users can silence bot notifications
Flexible duration - Temporary (hours/days) or permanent silence
Automatic expiration - Temporary silences expire automatically
Permission-based access - Requires "Manage Messages" permission

📈 Automatic Reports

Weekly reports with general statistics
Top users of the week
Server activity rate
Achievements granted in the period
Automatic scheduling (Sunday at 8 PM)

💤 Sleep Mode

```
!sleep
```
— Puts the bot to sleep until it receives
```
!wake
```
.
```
!sleep 30m
```
/
```
!sleep 2h
```
/
```
!sleep 1d
```
— Bot sleeps for the specified time (minutes, hours, days).
```
!wake
```
— Wakes the bot up immediately.
```
!status-sleep
```
— Shows the current sleep mode status.

While sleeping:

The bot continues collecting all metrics normally (presence, voice, messages, achievements, etc).
The bot does not send automatic messages (reports, alerts, unlocked achievements, etc).
The bot still responds to commands.

Silence Commands:

```
!silence
```
— Shows a tutorial on how to mute the channel manually in Discord (via DM).

The !silence command only teaches you how to mute the channel manually. The bot cannot mute channels for you, as this is a personal Discord setting.

Ranking Commands:

```
!top
```
— Ranking of the 10 members with the most online time
```
!top voice
```
— Ranking of the 10 members with the most time in voice channels

Achievement Commands:

```
!achievements
```
— Shows your unlocked achievements
```
!achievements @user
```
— Shows achievements of another user
```
!achievements-categories
```
— Shows all achievement categories and how many there are in each (dare to collect them all!)

Achievement Categories (Examples):

🎤 Voice & Presence — For the most sociable! (e.g., stay 24h in voice?)
💬 Messages & Reactions — For the most active! (1000 messages in a day?)
🦋 Social & Community — For the most popular! (help 50 people?)
📈 Engagement & Usage — For the most dedicated! (7 days online without a break?)
⏰ Activity & Consistency — For the most persistent! (30 days in a row?)
🎲 Fun & Extras — For the most creative! (use all custom emojis?)
🌙 Discord Lunatic — For the craziest! (online at dawn?)

Unlock all 50 achievements and become a Discord legend! Less than 1% can do it... Will you?

Comparison Commands:

```
!compare @user1 @user2
```
— Compares statistics of two users

Server Commands:

```
!serverstats
```
— General server statistics

Silence System Examples:

Temporary Silence:

```
!silence_2h
```
— Silence notifications for 2 hours
```
!silence_1d
```
— Silence notifications for 1 day
```
!silence_7d
```
— Silence notifications for 1 week

Permanent Silence:

```
!silence_always
```
— Permanently silence all bot notifications

Management:

```
!silence_status
```
— Check current silence status
```
!silence_remove
```
— Remove silence and resume notifications

🚀 Installation

Option 1: Docker (Recommended)

The easiest way to run Spy Bot is using Docker Compose, which includes MongoDB:

Clone the repository:

git clone <repository-url>
cd spy-bot

Configure the
```
.env
```
file:
- Copy the example:
```
cp env.example .env
```
- Fill in with your bot token, notification channel ID, and MongoDB credentials.
Run with Docker Compose:
```
docker-compose up -d
```
This will start both the bot and MongoDB automatically.

Option 2: Manual Installation

Clone the repository:

git clone <repository-url>
cd spy-bot

Create the virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Configure the

.env

file:

Copy the example:

cp env.example .env

Fill in with your bot token, notification channel ID, and MongoDB connection string.

⚠️ Important: If you're using

export $(grep -v '^#' .env | xargs)

to load variables, make sure values with spaces are in quotes in the

.env

file:

# Correct (with quotes)
REPORT_TIME="sunday 20:00"

# Incorrect (without quotes)
REPORT_TIME=sunday 20:00

Run the bot:
```
python main.py
```

⚙️ .env
Configuration

For Docker Installation:

# Required Settings
DISCORD_BOT_TOKEN=your_token_here
CANAL_DE_NOTIFICACAO_ID=1234567890123456789

# MongoDB Settings (for Docker)
MONGO_INITDB_ROOT_USERNAME=admin
MONGO_INITDB_ROOT_PASSWORD=password123
MONGO_INITDB_DATABASE=spy
MONGODB_URI=mongodb://admin:password123@alert-mongo:27017/spy?authSource=admin

# Optional Settings
SALA_EXCLUIDA=VACA WORK OS BRABO
CANAL_RELATORIOS_ID=1234567890123456789
CANAL_ALERTAS_ID=1234567890123456789
REPORT_TIME=sunday 20:00
ALERT_INACTIVE_DAYS=7

For Manual Installation:

# Required Settings
DISCORD_BOT_TOKEN=your_token_here
CANAL_DE_NOTIFICACAO_ID=1234567890123456789
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority

# Optional Settings
SALA_EXCLUIDA=VACA WORK OS BRABO
CANAL_RELATORIOS_ID=1234567890123456789
CANAL_ALERTAS_ID=1234567890123456789
REPORT_TIME=sunday 20:00
ALERT_INACTIVE_DAYS=7

Required Settings:

DISCORD_BOT_TOKEN: Your bot token from Discord Developer Portal
CANAL_DE_NOTIFICACAO_ID: ID of the channel where notifications will be sent
MONGODB_URI: MongoDB connection URI (for manual installation)

Docker-specific Settings:

MONGO_INITDB_ROOT_USERNAME: MongoDB root username (for Docker)
MONGO_INITDB_ROOT_PASSWORD: MongoDB root password (for Docker)
MONGO_INITDB_DATABASE: MongoDB database name (for Docker)

Optional Settings:

SALA_EXCLUIDA: Name of the voice channel that will be ignored by monitoring
CANAL_RELATORIOS_ID: ID of the channel where weekly reports will be sent
CANAL_ALERTAS_ID: ID of the channel where inactivity alerts will be sent
REPORT_TIME: Time for sending the weekly report (default: "sunday 20:00")
ALERT_INACTIVE_DAYS: Number of days to consider a user inactive (default: 7)

🕹️ Commands

Basic Commands:

```
!stats
```
— Shows your statistics of time in status and voice channels
```
!clear
```
— Clear all messages from the current channel (requires "Manage Messages" permission)
```
!help
```
— List of all available commands

Silence Commands:

```
!silence
```
— Shows a tutorial on how to mute the channel manually in Discord (via DM).

The !silence command only teaches you how to mute the channel manually. The bot cannot mute channels for you, as this is a personal Discord setting.

Ranking Commands:

```
!top
```
— Ranking of the 10 members with the most online time
```
!top voice
```
— Ranking of the 10 members with the most time in voice channels

Achievement Commands:

```
!achievements
```
— Shows your unlocked achievements
```
!achievements @user
```
— Shows achievements of another user
```
!achievements-categories
```
— Shows all achievement categories and how many there are in each (dare to collect them all!)

Achievement Categories (Examples):

🎤 Voice & Presence — For the most sociable! (e.g., stay 24h in voice?)
💬 Messages & Reactions — For the most active! (1000 messages in a day?)
🦋 Social & Community — For the most popular! (help 50 people?)
📈 Engagement & Usage — For the most dedicated! (7 days online without a break?)
⏰ Activity & Consistency — For the most persistent! (30 days in a row?)
🎲 Fun & Extras — For the most creative! (use all custom emojis?)
🌙 Discord Lunatic — For the craziest! (online at dawn?)

Unlock all 50 achievements and become a Discord legend! Less than 1% can do it... Will you?

Comparison Commands:

```
!compare @user1 @user2
```
— Compares statistics of two users

Server Commands:

```
!serverstats
```
— General server statistics

Silence System Examples:

Temporary Silence:

```
!silence_2h
```
— Silence notifications for 2 hours
```
!silence_1d
```
— Silence notifications for 1 day
```
!silence_7d
```
— Silence notifications for 1 week

Permanent Silence:

```
!silence_always
```
— Permanently silence all bot notifications

Management:

```
!silence_status
```
— Check current silence status
```
!silence_remove
```
— Remove silence and resume notifications

📦 Dependencies

Core Dependencies:

```
discord.py>=2.0.0
```
- Discord API wrapper
```
python-dotenv>=0.19.0
```
- Environment variable management
```
pymongo>=4.0.0
```
- MongoDB driver

Development Dependencies:

```
black>=23.0.0
```
- Code formatter
```
flake8>=6.0.0
```
- Linter
```
isort>=5.12.0
```
- Import sorter
```
bandit>=1.7.5
```
- Security linter
```
pre-commit>=3.0.0
```
- Git hooks

Installation:

# Production dependencies
pip install -r requirements.txt

# Development dependencies
pip install -e .[dev]

💡 Usage Example

Automatic Notifications:

The bot sends automatic and beautiful messages when joining/leaving/changing voice channels:

Personal Statistics:

Use
```
!stats
```
to see your online time, idle time, time in each channel, etc.:

Achievement System:

⏰ First Hour — Stayed online for 1 hour
🔥 Dedicated — Stayed online for 10 hours
👑 Veteran — Stayed online for 50 hours
🎤 Voice Explorer — Spent 1 hour in voice channels
🎵 Voice Master — Spent 10 hours in voice channels
🦋 Social Butterfly — Visited 3 different channels
🏠 Channel Explorer — Visited 10 different channels

Weekly Reports:

Automatically sent every Sunday at 8 PM
Include top users, general statistics, and weekly achievements

🛡️ Security

Never share your
```
.env
```
!
The
```
.env
```
file and sensitive data are in
```
.gitignore
```
.

🔧 Troubleshooting

Environment variables problem:

If you get the error

export: not an identifier

when loading

.env

, it's because some variable contains spaces. Solutions:

Use quotes in the

.env

file:

REPORT_TIME="sunday 20:00"

Or use python-dotenv (recommended):

from dotenv import load_dotenv
load_dotenv()

Or load manually:
```
source .env
```

Bot doesn't respond to commands:

Check if the bot has permission to read messages
Confirm that
```
MESSAGE_CONTENT_INTENT
```
is enabled in the Discord Developer Portal

Reports are not sent:

Check if
```
CANAL_RELATORIOS_ID
```
is configured correctly
Confirm that the bot has permission to send messages in the channel

Docker issues:

MongoDB connection failure: Check if the MongoDB container is running with
```
docker-compose ps
```
Bot doesn't start: Check logs with
```
docker-compose logs alert-bot
```
Environment variables not loaded: Make sure the
```
.env
```
file exists and has correct format
Port conflicts: Change MongoDB port in
```
docker-compose.yml
```
if 27843 is already in use

spy bot

Python

🤖 Spy Bot

🌍 Languages

✨ Features

🎯 Basic Monitoring

🏆 Rankings and Achievements System

📊 Advanced Commands

⚠️ Alerts and Reminders

🔇 Silence System

📈 Automatic Reports

💤 Sleep Mode

Silence Commands:

Ranking Commands:

Achievement Commands:

Achievement Categories (Examples):

Comparison Commands:

Server Commands:

Silence System Examples:

Management:

🚀 Installation

Option 1: Docker (Recommended)

Option 2: Manual Installation

⚙️ .env Configuration

For Docker Installation:

For Manual Installation:

Required Settings:

Docker-specific Settings:

Optional Settings:

🕹️ Commands

Basic Commands:

Silence Commands:

Ranking Commands:

Achievement Commands:

Achievement Categories (Examples):

Comparison Commands:

Server Commands:

Silence System Examples:

Management:

📦 Dependencies

Core Dependencies:

Development Dependencies:

Installation:

💡 Usage Example

Automatic Notifications:

Personal Statistics:

Achievement System:

Weekly Reports:

🛡️ Security

🔧 Troubleshooting

Environment variables problem:

Bot doesn't respond to commands:

Reports are not sent:

Docker issues:

📄 License

⚙️ `.env`
Configuration