GitHub - GlobalTechInfo/MEGA-MDX: High performance multi-device WhatsApp bot

250+ Commands · Multi-Platform · Multi-Database · Plugin Architecture

📦 Installation · 🔐 Session Setup · ⚙️ Configuration · 🚀 Deployment · 🔌 Plugins

🌍 Deploy on your favourite platform

📋 Table of Contents

✨ Features
📌 Requirements
⚡ Quick Start
🔐 Getting Your Session ID
⚙️ Configuration
📦 Installation
🚀 Deployment
🗄️ Storage Backends
🛠️ Environment Variables
📜 npm Scripts
🔌 Plugin System
🔧 Troubleshooting
🤝 Contributing

✨ Features

	Feature	Description
🔌	Auto-loading Plugins	Drop a `.ts` file in `plugins/` — it loads automatically, zero registration
💬	250+ Commands	Group management, privacy, moderation, fun, AI, media, utilities
🗄️	5 Storage Backends	MongoDB, PostgreSQL, MySQL, SQLite, or JSON files
🛡️	Group Protection	Anti-spam, bad word filter, link detection, anti-tag abuse
👑	Role System	Owner, Sudo, Admin, and User permission levels
⏰	Scheduled Messages	Schedule messages with natural time input
🤖	AI Chatbot	Per-chat AI conversation mode
🔒	Privacy Controls	Full WhatsApp privacy management via commands
📊	Polls & Voting	Create polls with live vote tracking in groups
📡	Broadcast	Bulk message all groups or all DM contacts at once
🔁	Auto-Reply	Configurable trigger-based auto responses with `{name}` support
🎮	Games	TicTacToe and more built in
⏳	Disappearing Messages	Set per-chat or default timers via commands
📱	Multi-Platform	Runs on Termux, VPS, Railway, Render, Heroku, Koyeb, Fly.io, Replit

📌 Requirements

Requirement	Version	Notes
	20.x or higher	Required
	8.x or higher	Included with Node.js
	Any recent	For cloning
	Latest	Media processing
	Latest	Sharp image processing
	Latest	Sticker creation

Warning

Never use your personal WhatsApp number for the bot. Always use a dedicated number.

⚡ Quick Start

git clone https://github.com/GlobalTechInfo/MEGA-MDX.git
cd MEGA-MDX
npm install
cp sample.env .env
# Edit .env → add SESSION_ID and OWNER_NUMBER
npm run build
npm start

🔐 Getting Your Session ID

Important

The bot uses a Session ID to connect to WhatsApp without scanning QR every time. Generate it once and paste it in .env.

Step 1 — Open the session generator

🌐 https://mega-pairing.onrender.com

Step 2 — Generate your session

Option A — Pair Code (Recommended)

Enter your bot's WhatsApp number with country code (e.g. 923001234567)
Click Generate Pair Code
An 8-character code appears (e.g. J38K-4PNS)
On your phone: WhatsApp → ⋮ Menu → Linked Devices → Link a Device → Link with phone number
Enter the code — session is created
Copy the Session ID shown on the page

Option B — QR Code

Click the QR Code tab
Scan the QR code with your WhatsApp
Copy the Session ID shown after scanning

Step 3 — Add to `.env`

SESSION_ID=GlobalTechInfo/MEGA-MD_xxxxxxxxxxxxxxxxxxxxxxxx

Alternative — Pairing via terminal

Leave SESSION_ID empty and set:

PAIRING_NUMBER=923001234567

Note

The bot will print an 8-character pairing code in the terminal on startup. Link it via WhatsApp → Linked Devices → Link with phone number within 60 seconds.

⚙️ Configuration

Copy sample.env to .env:

cp sample.env .env

# ── REQUIRED (choose one) ────────────────────────────────────
SESSION_ID=GlobalTechInfo/MEGA-MD_your_gist_id_here
# OR
PAIRING_NUMBER=923001234567

# ── REQUIRED ─────────────────────────────────────────────────
OWNER_NUMBER=923000000000        # No + sign

# ── BOT IDENTITY ─────────────────────────────────────────────
BOT_NAME=MEGA-MD-PRO
BOT_OWNER=GlobalTechInfo
PACKNAME=MEGA-MD

# ── BEHAVIOUR ────────────────────────────────────────────────
PREFIXES=.,!,/                   # Comma-separated
COMMAND_MODE=public              # public or private
TIMEZONE=Asia/Karachi

# ── OPTIONAL API KEYS ────────────────────────────────────────
REMOVEBG_KEY=                    # https://remove.bg/api
GIPHY_API_KEY=                   # https://developers.giphy.com

# ── PERFORMANCE ──────────────────────────────────────────────
PORT=5000
MAX_STORE_MESSAGES=50

# ── DATABASE (all empty = JSON files) ────────────────────────
MONGO_URL=
POSTGRES_URL=
MYSQL_URL=
DB_URL=                          # SQLite: ./data/baileys.db

📦 Installation

Manual Install

# 1. Clone
git clone https://github.com/GlobalTechInfo/MEGA-MDX.git
cd MEGA-MDX

# 2. Install dependencies
npm install

# 3. Configure
cp sample.env .env
nano .env

# 4. Build TypeScript
npm run build

# 5. Start
npm start

One-Line VPS Installer

sudo bash <(curl -fsSL https://raw.githubusercontent.com/GlobalTechInfo/MEGA-MDX/main/lib/install.sh)

Important

This automatically installs Node.js 20, ffmpeg, libvips, libwebp, PM2, clones the repo, builds it, and sets up data files.

# After install:
nano /root/MEGA-MDX/.env
cd /root/MEGA-MDX && pm2 start dist/index.js --name mega-mdx
pm2 save && pm2 startup

🚀 Deployment

📱 Termux (Android)

# Update packages
pkg update && pkg upgrade -y

# Install proot-distro (recommended for full Linux environment)
pkg install proot-distro -y
proot-distro install ubuntu
proot-distro login ubuntu

# Inside Ubuntu — install dependencies
apt update && apt upgrade -y
apt install -y git ffmpeg build-essential libvips-dev webp nodejs npm curl

# Clone and setup
git clone https://github.com/GlobalTechInfo/MEGA-MDX.git
cd MEGA-MDX
npm install
cp sample.env .env && nano .env
npm run build && npm start

Keep running after closing Termux:

apt install tmux -y

tmux new -s mega-mdx    # Start new session
npm start

# Detach:     Ctrl+B → D
# Re-attach:  tmux attach -t mega-mdx
# List:       tmux ls
# Kill:       tmux kill-session -t mega-mdx

🖥️ VPS / Linux Server

One-line install (recommended):

sudo bash <(curl -fsSL https://raw.githubusercontent.com/GlobalTechInfo/MEGA-MDX/main/lib/install.sh)

Manual:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git ffmpeg libvips-dev libwebp-dev build-essential

git clone https://github.com/GlobalTechInfo/MEGA-MDX.git
cd MEGA-MDX
npm install
cp sample.env .env && nano .env
npm run build

# Keep alive with PM2
npm install -g pm2
pm2 start dist/index.js --name mega-mdx
pm2 save && pm2 startup

PM2 commands:

Command	Description
`pm2 logs mega-mdx`	Live logs
`pm2 restart mega-mdx`	Restart
`pm2 stop mega-mdx`	Stop
`pm2 status`	Status overview

🪟 Windows (WSL)

# In WSL Ubuntu terminal
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git ffmpeg libvips-dev libwebp-dev build-essential

git clone https://github.com/GlobalTechInfo/MEGA-MDX.git
cd MEGA-MDX
npm install
cp sample.env .env && nano .env
npm run build && npm start

🔁 Replit

Note

The repo includes pre-configured .replit and replit.nix.

Go to replit.com → Create Repl → Import from GitHub
Paste: https://github.com/GlobalTechInfo/MEGA-MDX
Open Secrets tab (🔒) and add:

Key Value

SESSION_ID GlobalTechInfo/MEGA-MD_your_gist_id

OWNER_NUMBER 923001234567
Click Run

replit.nix automatically installs: Node.js 20, ffmpeg, imagemagick, libwebp, SQLite, pm2 etc.

Tip

Free Replit instances sleep after inactivity. Use UptimeRobot to ping your Replit URL every 5 minutes to keep it alive. [!NOTE] Production deployment uses npm run start:optimized (512MB memory limit) — configured in .replit's [deployment] section.

🟣 Heroku

Note

The repo includes heroku.yml and app.json for Docker-based deployment.

Either you can deploy via dashboard or using heroku cli

One-line Deployer:

bash <(curl -s https://raw.githubusercontent.com/GlobalTechInfo/MEGA-MDX/main/lib/heroku.sh)

Manual:

heroku login
heroku create your-bot-name
heroku stack:set container

heroku config:set SESSION_ID=GlobalTechInfo/MEGA-MD_your_gist_id
heroku config:set OWNER_NUMBER=923001234567
heroku config:set MONGO_URL=your_mongodb_url   # Recommended

git push heroku main
heroku ps:scale web=1
heroku logs --tail

Important

Heroku's filesystem is ephemeral — data is lost on restart. Use MongoDB or PostgreSQL for persistent storage. [!NOTE] Heroku uses heroku.yml → Docker build → runs npm run start:optimized.

🎨 Render

Note

The repo includes render.yaml for one-click Blueprint deployment.

Fork this repo
render.com → New → Blueprint → connect your fork
Render reads render.yaml automatically
Set environment variables in the dashboard:
- SESSION_ID
- OWNER_NUMBER
Deploy

Important

Render uses Docker (Dockerfile) and runs npm run start:optimized. Use a database for persistent storage on Render's free tier.

🚂 Railway

Fork this repo
railway.app → New Project → Deploy from GitHub Repo
Select your fork
Variables tab → add:

Key Value

SESSION_ID GlobalTechInfo/MEGA-MD_your_gist_id

OWNER_NUMBER 923001234567
Railway auto-builds via Dockerfile and deploys

☁️ Koyeb

Note

The repo includes koyeb.json with port 5000 pre-configured.

Fork this repo
app.koyeb.com → Create App → GitHub
Select your fork — Koyeb reads koyeb.json
Set SESSION_ID and OWNER_NUMBER in env vars
Deploy

🪂 Fly.io

Note

The repo includes fly.toml pre-configured (512MB RAM, port 5000, region: US East).

Either deploy via dashboard or using cli

One-line Deployer:

bash <(curl -s https://raw.githubusercontent.com/GlobalTechInfo/MEGA-MDX/main/lib/fly.sh)

Manual:

curl -L https://fly.io/install.sh | sh
fly auth login

fly launch --no-deploy
fly secrets set SESSION_ID=GlobalTechInfo/MEGA-MD_your_gist_id
fly secrets set OWNER_NUMBER=923001234567
fly deploy

fly logs   # View logs

fly.toml settings: auto-start enabled, auto-stop disabled so the bot stays running 24/7.

🐳 Dockerfile

Note

The repo includes a Dockerfile for any Docker-compatible platform.

# Build image
docker build -t mega-mdx .

# Run
docker run -d \
  -e SESSION_ID=GlobalTechInfo/MEGA-MD_your_gist_id \
  -e OWNER_NUMBER=923001234567 \
  -p 5000:5000 \
  --name mega-mdx \
  mega-mdx

# Logs
docker logs -f mega-mdx

🎮 Discord Panels (Pterodactyl)

Important

For Pterodactyl-based hosting panels (Fosshost, Skynode, Optiklink etc.): Use brave browser or any adguard to avoid ads from hosting panels

Create server with a Node.js 20+ egg

Set startup command:

npm install && npm run build && npm start

Upload files via SFTP or file manager
Add env vars in the Startup tab: SESSION_ID, OWNER_NUMBER
Start the server

Important

Ensure the egg uses Node.js 20 or newer. If your panel supports Docker, use the included Dockerfile instead for best compatibility.

🗄️ Storage Backends

Note

Set one database URL in .env. If all are empty, JSON file storage is used automatically — no setup needed.

Backend	Badge	Best For
JSON Files		Local, Termux
MongoDB		Cloud (recommended)
PostgreSQL		Cloud / VPS
MySQL		Cloud / VPS
SQLite		VPS (no external DB)

# MongoDB
MONGO_URL=mongodb+srv://user:password@cluster.mongodb.net/megamd

# PostgreSQL
POSTGRES_URL=postgresql://user:password@host:5432/megamd

# MySQL
MYSQL_URL=mysql://user:password@host:3306/megamd

# SQLite
DB_URL=./data/baileys.db

Tip

Get a free MongoDB cluster at MongoDB Atlas — best choice for cloud deployments where the filesystem resets.

🛠️ Environment Variables

Variable	Required	Default	Description
`SESSION_ID`	✅ one of	—	From mega-pairing.onrender.com
`PAIRING_NUMBER`	✅ one of	—	Phone number for terminal pairing
`OWNER_NUMBER`	✅	`923051391007`	Your number, no `+`
`BOT_NAME`	❌	`MEGA-MD`	Bot display name
`BOT_OWNER`	❌	`Qasim Ali`	Owner display name
`PACKNAME`	❌	`MEGA-MD`	Sticker pack name
`PREFIXES`	❌	`.,!,/,#`	Comma-separated prefixes
`COMMAND_MODE`	❌	`public`	`public` or `private`
`TIMEZONE`	❌	`Asia/Karachi`	Your timezone
`PORT`	❌	`5000`	HTTP server port
`MAX_STORE_MESSAGES`	❌	`20`	Messages stored per chat
`REMOVEBG_KEY`	❌	—	remove.bg API key
`GIPHY_API_KEY`	❌	—	Giphy API key
`MONGO_URL`	❌	—	MongoDB connection string
`POSTGRES_URL`	❌	—	PostgreSQL connection string
`MYSQL_URL`	❌	—	MySQL connection string
`DB_URL`	❌	—	SQLite file path
`CLEANUP_INTERVAL`	❌	`3600000`	Temp cleanup interval (ms)
`STORE_WRITE_INTERVAL`	❌	`10000`	Store write interval (ms)

📜 npm Scripts

Script	Description
`npm start`	Start the bot
`npm run start:optimized`	Start with 512MB memory cap (cloud use)
`npm run start:fresh`	Reset data files then start
`npm run build`	Compile TypeScript → `dist/`
`npm run rebuild`	Clean + rebuild
`npm run clean`	Delete `dist/`
`npm run dev`	Watch mode with auto-restart
`npm run setup`	Build + init data files
`npm run reset-data`	Re-initialize all JSON data files
`npm run reset-session`	Delete `session/` folder
`npm run typecheck`	Type check without compiling
`npm run lint`	Run ESLint
`npm test`	Run all tests

🔌 Plugin System

Important

Plugins live in plugins/ and are auto-loaded on startup — no registration needed. Each file must export a default object.

Plugin Template

export default {
    command: 'mycommand',
    aliases: ['mc', 'mycmd'],
    category: 'utility',
    description: 'Does something cool',
    usage: '.mycommand <input>',

    // Optional permission flags
    ownerOnly: false,      // Owner/sudo only
    groupOnly: false,      // Groups only
    adminOnly: false,      // Group admins only
    isPrefixless: true,    // Works without prefix too
    cooldown: 5,           // Cooldown in seconds

    async handler(sock: any, message: any, args: any[], context: any = {}) {
        const {
            chatId,           // Chat JID
            senderId,         // Sender JID
            isGroup,          // boolean
            isSenderAdmin,    // boolean
            isBotAdmin,       // boolean
            senderIsOwnerOrSudo, // boolean
            rawText,          // Full message text
            userMessage,      // Lowercase message
            config,           // Bot configuration 
            channelInfo       // MEGA-MD branding spread
        } = context;

        await sock.sendMessage(chatId, {
            text: `You said: ${args.join(' ')}`,
            ...channelInfo
        }, { quoted: message });
    }
};

🔧 Troubleshooting

Bot not connecting

Important

Verify SESSION_ID starts with GlobalTechInfo/MEGA-MD_
If using PAIRING_NUMBER, link within 60 seconds of the code appearing
Reset session and reconnect: npm run reset-session && npm start

`myAppStateKey not present` (pin/star broken)

Session lost its app state keys. Fix:

node -e "
const fs = require('fs');
const c = JSON.parse(fs.readFileSync('session/creds.json','utf8'));
delete c.myAppStateKeyId;
fs.writeFileSync('session/creds.json', JSON.stringify(c, null, 2));
console.log('Done');
"
npm start

Send any message to the bot — WhatsApp re-syncs keys automatically. They are now preserved across restarts.

Commands not responding

Check you're using the right prefix (default .)
COMMAND_MODE=private → only owner can use commands
OWNER_NUMBER must have no + sign

Build errors

rm -rf dist && npm run build

Data lost after restart

Caution

Cloud platforms reset the filesystem on redeploy. Add MONGO_URL to use MongoDB — MongoDB Atlas has a free tier.

Port conflict

PORT=3000 npm start

🧪 Testing

The codebase has a comprehensive test suite covering all core systems:

npm test                # Run all 178 tests
npm run test:coverage   # Run with coverage report
npm run test:watch      # Watch mode during development

Test Suite	What's Covered
Unit — `myfunc`	21 utility function tests with real input/output assertions
Unit — `commandHandler`	Command registration, alias routing, toggle, suggestions
Unit — `isOwner`	JID matching, device suffix stripping, sudo checks
Unit — `isBanned`	File-based ban list read/write
Unit — `paths`	Data directory resolution
Integration — plugins	ALL plugins load, no duplicate commands/aliases, correct field types
Integration — `messageHandler`	Full message flow, banned users, error handling
Integration — group events	add/remove/promote/demote without crashing
Integration — call handling	Anticall reject, warn, empty call safety

Uses Vitest with a custom Baileys socket mock that simulates real WhatsApp message flows without requiring a live connection.

🤝 Contributing

Fork the repo
Create your plugin in plugins/yourfeature.ts
Follow the plugin template above
Test thoroughly
Open a Pull Request

📞 Support

⚠️ Disclaimer

Caution

This project is not affiliated with WhatsApp Inc. Use responsibly and within WhatsApp's Terms of Service. The developers are not responsible for account bans or misuse.

📄 License

MIT License · Made with ❤️ by Qasim Ali · GlobalTechInfo

⭐ If this project helped you, please give it a star! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 182 Commits
assets		assets
data		data
lib		lib
plugins		plugins
test		test
.gitignore		.gitignore
.replit		.replit
Dockerfile		Dockerfile
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
app.json		app.json
config.ts		config.ts
declarations.d.ts		declarations.d.ts
eslint.config.mjs		eslint.config.mjs
fly.toml		fly.toml
heroku.yml		heroku.yml
index.ts		index.ts
koyeb.json		koyeb.json
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
railway.json		railway.json
render.yaml		render.yaml
replit.nix		replit.nix
reset-data.ts		reset-data.ts
sample.env		sample.env
tsconfig.json		tsconfig.json
types.d.ts		types.d.ts
vitest.config.ts		vitest.config.ts

Key	Value
`SESSION_ID`	`GlobalTechInfo/MEGA-MD_your_gist_id`
`OWNER_NUMBER`	`923001234567`

Folders and files

Latest commit

History

Repository files navigation

🌍 Deploy on your favourite platform

📋 Table of Contents

✨ Features

📌 Requirements

⚡ Quick Start

🔐 Getting Your Session ID

Step 1 — Open the session generator

Step 2 — Generate your session

Step 3 — Add to .env

Alternative — Pairing via terminal

⚙️ Configuration

📦 Installation

Manual Install

One-Line VPS Installer

🚀 Deployment

📱 Termux (Android)

🖥️ VPS / Linux Server

🪟 Windows (WSL)

🔁 Replit

🟣 Heroku

🎨 Render

🚂 Railway

☁️ Koyeb

🪂 Fly.io

🐳 Dockerfile

🎮 Discord Panels (Pterodactyl)

🗄️ Storage Backends

🛠️ Environment Variables

📜 npm Scripts

🔌 Plugin System

Plugin Template

🔧 Troubleshooting

Bot not connecting

myAppStateKey not present (pin/star broken)

Commands not responding

Build errors

Data lost after restart

Port conflict

🧪 Testing

🤝 Contributing

📞 Support

⚠️ Disclaimer

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Step 3 — Add to `.env`

`myAppStateKey not present` (pin/star broken)

Packages