MegaChat 🤖

Anonymous peer-to-peer Telegram chat bot with matchmaking, gamification, subscriptions and a public Spotlight board.

---

Table of Contents

• Overview
• Features
• Tech Stack
• Prerequisites
• Installation
• Configuration
• Database Setup
• Running the Bot
• Deploy as a System Service
• Commands Reference
• Subscription Tiers
• Project Structure
• Contributing
• License

---

Overview

MegaChat connects anonymous users on Telegram for one-on-one text and media chats based on shared interests. Users earn XP by chatting, level up to unlock titles, and can boost their visibility through the public Spotlight board.

The bot supports Italian and English, handles Telegram Stars payments for subscriptions and XP packs, and includes a full reporting and moderation foundation.

---

Features

Core

Feature	Description
🔍 Smart Matchmaking	Pairs users by language, gender preference, and shared interests (interest-score priority)
💬 Anonymous Chat	Full message relay: text, photos, videos, voice, stickers, GIFs, video notes
💣 Flash Mode	Self-destructing photos/videos (spoiler + auto-delete after 15 s)
📢 Spotlight Board	Spend XP to post a public message in a channel; anyone can connect directly via deep link
🏆 Gamification	Earn XP per message, level up through 5 tiers, unlock exclusive titles
👍 Rating System	Upvote/downvote partners after each chat; upvote recipient gets +50 XP and a notification
🚨 Report System	/report during an active chat; reports are stored with reason and counted per user
🥇 Leaderboard	Top 5 users by XP, visible to everyone

Monetisation (Telegram Stars)

Product	Stars	Benefit
Premium subscription	100 ⭐/mo	20 chats/day
Gold subscription	250 ⭐/mo	Unlimited chats
Ultra subscription	500 ⭐/mo	Unlimited + VIP
500 XP pack	50 ⭐	Instant XP boost
1 500 XP pack	120 ⭐	Instant XP boost
5 000 XP pack	350 ⭐	Instant XP boost

Security

• Credentials loaded from environment variables (never hardcoded)
• html.escape() on all user-supplied text embedded in HTML messages
• Atomic matchmaking updates (AND status='waiting') prevent race conditions
• Per-user rate limiting on queue commands
• Input validation and length caps on all free-text fields

---

Tech Stack

• Runtime — Python 3.10+
• Bot framework — python-telegram-bot 21.x (async, with JobQueue)
• Database — MySQL 8.0+ via mysql-connector-python
• Config — python-dotenv
• Deployment — systemd service (Linux)

---

Prerequisites

• Python 3.10 or newer
• MySQL 8.0 or newer
• A Telegram bot token from @BotFather
• A Telegram channel for the Spotlight board (bot must be admin)

---

Installation

# 1. Clone the repository
git clone https://github.com/your-username/megachat.git
cd megachat

# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

---

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

# .env
MEGACHAT_TOKEN=123456789:ABCdef...   # Bot token from @BotFather

DB_HOST=localhost
DB_USER=megachat
DB_PASSWORD=your_password
DB_NAME=megachat
DB_POOL_SIZE=10

SPOTLIGHT_CHANNEL=@YourChannel
SPOTLIGHT_CHANNEL_ID=-100123456789   # Numeric ID of the channel

Never commit .env to version control. It is already listed in .gitignore.

---

Database Setup

Fresh install

mysql -u root -p < database.sql

Migrating from v2.0

If you already have a running database, use the migration script instead:

# Always back up first
mysqldump -u megachat -p megachat > backup_$(date +%Y%m%d).sql

# Run the migration (idempotent — safe to re-run)
mysql -u megachat -p megachat < migrate.sql

The migration script:

• Adds the new report_count column
• Creates performance indexes (status, tier, xp)
• Creates the reports table
• Fixes the old Italian default title (Novellino → Beginner)
• Cleans up inconsistent chat states
• Prints a verification report at the end

---

Running the Bot

# Activate your virtual environment first
source venv/bin/activate

python main.py

You should see:

MegaChat v2.1 is running...

---

Deploy as a System Service

The included setup_service.sh automates the full server setup:

sudo bash setup_service.sh

It will:

1. Create the virtual environment if missing
2. Install all dependencies from requirements.txt
3. Warn if .env is absent
4. Write a systemd unit file (with EnvironmentFile pointing to .env)
5. Enable and start the service

Useful commands after deployment:

# Live logs
sudo journalctl -u megachat -f

# Restart after a code change
sudo systemctl restart megachat

# Check current status
sudo systemctl status megachat

---

Commands Reference

Command	Description
/start	Register or return to dashboard
/search	Enter the matchmaking queue
/stop	Leave queue or end current chat
/next	End current chat and immediately search for a new one
/profile	View your stats (level, XP, likes, tier, …)
/report [reason]	Report current chat partner
/leaderboard	Top 5 users by XP
/shop	Browse subscriptions and XP packs
/settings	Edit bio, switch language, delete account
/menu	Return to the main dashboard
/help	Usage guide
/info	About and privacy notice
/cancel	Cancel active registration or spotlight flow

---

Subscription Tiers

Tier	Daily chats	Price
Free	5	—
Premium	20	100 ⭐ / 30 days
Gold	Unlimited	250 ⭐ / 30 days
Ultra	Unlimited + VIP	500 ⭐ / 30 days

Subscriptions are checked and downgraded automatically every 24 hours by a background job.

---

Project Structure

megachat/
├── main.py            # Bot handlers, matchmaking, relay, payments
├── db.py              # Database abstraction (queries, XP, leaderboard, reports)
├── config.py          # Settings loaded from environment variables
├── texts.py           # Bilingual (IT/EN) translation strings
├── database.sql       # Fresh-install schema
├── migrate.sql        # v2.0 → v2.1 migration (idempotent)
├── broadcast.py       # One-off mass-message utility (migration helper)
├── setup_service.sh   # Automated Linux service installer
├── requirements.txt   # Python dependencies
├── .env.example       # Environment variable template
└── .gitignore

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request.

---

License

This project is licensed under the MIT License — see LICENSE for details.