Tuition Listings Monitor

Once a day, scans your tuition channels for listings mentioning P3/P4/P5/P6 Math/Science, and sends you a compiled report. Runs once and exits — no need to keep anything running 24/7.

Why a "user" client instead of a bot?

Telegram bots can only read messages in a channel if the channel owner explicitly makes the bot an admin. Since these are external tuition-listing channels you don't control, that's not an option. Instead, this script logs in as your own Telegram account (the same way Telegram Desktop or Web does) and reads channels you've already joined — same as scrolling them yourself, just automated.

Your login session is stored locally in a .session file on your machine. Nothing is sent to me or any third party — this all runs on whatever computer/server you run it on.

How the daily scan works

• First run for each channel: scans the last 24 hours of posts (since there's no baseline yet).
• Every run after that: picks up exactly where the last run left off, using a saved "last seen message ID" per channel (stored in state.json). So even if you only run it once a day, it will never miss a message posted between runs — no live connection needed.
• If the script doesn't run on a given day for some reason, the next run will just catch up on everything since the last successful scan.

Setup

1. Get API credentials (one-time, free):

   • Go to https://my.telegram.org
   • Log in with the phone number of the account you want to use
   • Go to "API development tools", create an app (any name/platform is fine)
   • Copy the api_id and api_hash values

2. Install dependencies

   pip install -r requirements.txt

3. Edit config.py:

   • Paste in your API_ID and API_HASH

4. Join the tuition channels with the Telegram account you're using (via the app, just like normal), if you haven't already.

5. Find the exact channel identifiers:

   python list_my_channels.py

   This logs you in (first time: it'll ask for your phone number, then a login code sent to your Telegram app) and prints all channels you're in. Copy the usernames (or IDs for private channels without a username) into config.py -> CHANNELS.

6. Test it manually first:

   python main.py

   First time, this logs in (phone + code) and creates a .session file so future runs don't need to log in again. It scans the last 24h, sends you the report, and exits.

Scheduling it to run daily at 10 AM

You don't need the script running continuously — just schedule it to run once a day.

On Linux/Mac (cron):

crontab -e

Add this line (adjust the paths to match where you saved the files):

0 10 * * * cd /path/to/tuition_bot && /usr/bin/python3 main.py >> run.log 2>&1

This runs it every day at 10:00 AM.

On Windows (Task Scheduler):

• Open Task Scheduler → Create Basic Task
• Trigger: Daily at 10:00 AM
• Action: Start a program → python.exe with argument main.py, "Start in" set to the tuition_bot folder

Cloud option: if you don't want to rely on your own computer being on at 10 AM, a free-tier scheduled job (e.g. a cron-triggered function on a small always-available VPS, or a scheduled GitHub Action with the session file stored as a secret) works too — let me know if you'd like help setting one of those up.

Files

• config.py — all settings (credentials, channels, keywords)
• matcher.py — keyword matching logic
• main.py — one-shot scan + report sender (run this daily)
• state.py — tracks last-seen message ID per channel between runs
• list_my_channels.py — one-time helper to find channel usernames/IDs
• state.json — created automatically, don't edit by hand
• matches_log.jsonl — backup log of every match ever found (created automatically)

Adjusting keywords

matcher.py already handles variations like "P4", "p4", "Primary 4", "primary4" and "Math"/"Maths"/"Science". If you want to add more subjects or levels, edit the LEVELS and SUBJECTS lists in config.py.