Scrapes job postings from JIIT’s SuperSet placement portal, stores them in MongoDB, and broadcasts them to registered Telegram users, so you don’t have to keep refreshing the portal.

The bot runs at @SupersetNotificationBot. Send /start to register and you’ll get job posting notifications. The companion site is jiit-placement-updates.tashif.codes.

• Register with /start, unsubscribe with /stop
• Logs into SuperSet and pulls the latest job postings
• Skips duplicates by exact content match
• Reformats posts for Telegram
• Stores users and posts in MongoDB
• Updates hourly from 8 AM to 11 PM IST plus midnight, and scrapes official placement data at 12 PM
• Sends to every registered user at once
• Runs in the background with logging

• /start register for notifications
• /status check your subscription
• /placement_year choose which placement year you follow
• /stats placement statistics
• /noticestats notice statistics
• /web links to JIIT tools
• /help show help
• /stop unsubscribe

The live bot above works as is. Run your own if you want to customize it or learn from it.

Prerequisites#

• Python 3.12+
• MongoDB, local or Atlas
• Telegram bot token
• SuperSet credentials

Step 1: Clone the repository#

git clone https://github.com/tashifkhan/placement-alerts-superset-telegram-notification-bot.git
cd placement-alerts-superset-telegram-notification-bot

Step 2: Install dependencies#

cd app
uv sync

# or with pip
pip install -r requirements.txt

Step 3: Telegram credentials#

Create a bot:

1. Message @BotFather on Telegram
2. Send /newbot
3. Pick a name when prompted
4. Copy the token BotFather returns into .env

Find your chat ID:

• Personal use: message @userinfobot and use the user_id it replies with as TELEGRAM_CHAT_ID.
• Channel or group: add the bot as an admin, post a message, then open https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates and look for "chat":{"id":-1001234567890}. Group and channel IDs are negative.

Step 4: Set up MongoDB#

1. Create a free MongoDB Atlas account
2. Create a cluster; the free tier is enough
3. Click Connect and choose “Connect your application”
4. Copy the connection string and fill in your username, password, and database name
5. Put it in .env

Step 5: Configure environment variables#

Copy .env.example to .env and fill in every placeholder. Protected webhook routes fail closed unless WEBHOOK_API_KEY is set. Admin bot commands also fail closed unless your Telegram user ID is listed in ADMIN_TELEGRAM_USER_IDS.

# MongoDB
MONGO_CONNECTION_STR=mongodb+srv://username:[email protected]/database
MONGO_DATABASE_NAME=2025-26
GLOBAL_DATABASE_NAME=PlacementBotGlobal
ACTIVE_PLACEMENT_YEAR=202526
DEFAULT_PLACEMENT_YEAR=202526
PLACEMENT_YEARS=["202526", "202627"]

# Telegram Configuration
TELEGRAM_BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ
TELEGRAM_CHAT_ID=your_chat_id
ADMIN_TELEGRAM_USER_IDS=[123456789]

# SuperSet credentials grouped by ingestion year
SUPERSET_CREDENTIALS=[]
SUPERSET_CREDENTIALS_BY_YEAR={"202526":[{"email":"[email protected]","password":"replace-me"}],"202627":[{"email":"[email protected]","password":"replace-me"}]}

# Protected webhook API
WEBHOOK_API_KEY=generate_a_long_random_secret
CORS_ORIGINS=["https://your-dashboard.example.com"]

Placement-year settings#

• PLACEMENT_YEARS lists the years shown in the bot UI and used for notification routing.
• SUPERSET_CREDENTIALS_BY_YEAR lists the years that update and update-supersets scrape. Every year you want scraped needs a key here with at least one credential.
• ACTIVE_PLACEMENT_YEAR is the fallback year for operations.
• DEFAULT_PLACEMENT_YEAR is the year assigned to new users until they pick one.

Without --year, an update scrapes every year present in SUPERSET_CREDENTIALS_BY_YEAR. To scrape one year:

cd app
uv run main.py update --year 202627

Email ingestion reads the year from a recipient alias such as [email protected]. An unread email with no valid year alias goes to ACTIVE_PLACEMENT_YEAR unless --year sets another fallback.

Step 6: Run the bot#

The bot server handles user commands. The scheduler runs scraping and broadcasting on a timer. Run both for a complete setup.

cd app

python main.py bot                  # bot server, foreground
python main.py scheduler            # scheduled jobs, foreground

python main.py bot --daemon         # bot server, background
python main.py scheduler --daemon   # scheduled jobs, background

Daemon control:

python main.py status               # both daemons
python main.py stop bot             # stop the bot daemon
python main.py stop scheduler

One-off runs, useful for testing:

python main.py update               # fetch and process updates
python main.py send --telegram      # send unsent notices via Telegram
python main.py send --web           # send unsent notices via Web Push
python main.py send --both
python main.py                      # update + send (legacy)

Step 7: Test the setup#

cd app
pytest

Step 8: Manage users#

Users register and unsubscribe through the bot. Admin commands require your Telegram user ID in ADMIN_TELEGRAM_USER_IDS.

Step 9: Deploy#

The full guide is in docs/DEPLOYMENT.md. On a VPS, run both daemons:

cd app
python main.py bot --daemon
python main.py scheduler --daemon
python main.py status

Or supervise them with PM2:

npm install -g pm2
pm2 start main.py --name superset-bot --interpreter python3.12 -- bot
pm2 start main.py --name superset-scheduler --interpreter python3.12 -- scheduler
pm2 save
pm2 startup

Scheduled scraping and broadcasting run inside python main.py scheduler. The workflow files under .github/workflows/ are disabled (.legacy).

placement-alerts-superset-telegram-notification-bot/
├── app/
│   ├── clients/     # External clients (SuperSet, Google Groups, Telegram, DB)
│   ├── core/        # Settings, logging, LLM helpers, daemon utilities
│   ├── data/        # JSON fixtures and seed data
│   ├── model/       # Pydantic document models
│   ├── runners/     # Update and notification runners
│   ├── scripts/     # One-off migration scripts
│   ├── servers/     # Bot, webhook, and scheduler servers
│   ├── services/    # Business logic
│   ├── tests/       # pytest suite
│   ├── main.py      # CLI entry point
│   ├── pyproject.toml
│   └── requirements.txt
├── docs/            # Architecture, config, database, deployment docs
├── .github/workflows/
└── README.md

• ARCHITECTURE.md
• CONFIGURATION.md
• DATABASE.md
• NOTICES_AND_JOBS.md
• OFFICIAL_SCRAPER.md
• STATS.md
• DEPLOYMENT.md
• API.md
• TROUBLESHOOTING.md
• DEVELOPMENT.md

Logs live in logs/ at the repo root. Foreground runs print to the console and append to logs/superset_bot.log. The bot daemon logs to logs/superset_bot.log and captures stdout in logs/bot.log; the scheduler daemon logs to logs/scheduler.log. Set LOG_LEVEL to DEBUG, INFO, WARNING, or ERROR.

• Support placement portals beyond SuperSet
• Alert filters by company or role
• Web form for user registration

Pull requests are welcome.

GPL-3.0