Skip to content

README.md

Latest commit

 

History

History
163 lines (129 loc) · 6.46 KB

README.md

File metadata and controls

163 lines (129 loc) · 6.46 KB

STEM Telebot

Python Telegram PTB aiohttp gspread Platform PRs Welcome

A high-performance, bilingual Telegram bot built for the STEM USAS student organization. It simplifies membership verification and provides administrative tools to manage the student registry via Google Sheets.

Note

Real-time Sync: The bot acts as a bridge between Telegram and a Google Sheets backend. It features automated alerts for new registrations and handles member approvals with dedicated administrative layers.

Features

  • Multi-lingual Interface: Full support for English and Bahasa Melayu (Switch via /settings or the menu).
  • Membership Verification: 2-step verification using Matric Number and IC Last 4 Digits against official records.
  • Interactive Registration Info: View membership benefits and follow guided registration prompts.
  • Admin Command Suite:
    • Member Search: Find students by Name, Matric, or IC with "Simple" or "Detailed" result views.
    • Broadcast System: Send announcements to all registered users with de-duplication and delivery reports.
    • Status Management: List members, view detailed profiles, or remove entries directly via bot.
    • Manual Registration Check: Trigger an immediate scan of the sheet for new signups.
  • Superadmin Control Panel:
    • Maintenance Mode: Lock the bot for everyone except admins.
    • System Health: Monitor CPU usage, RAM, and Bot Uptime in real-time.
    • Admin Management: Add or remove secondary admins via Telegram ID.
    • Log Reporting: Receive automated daily activity log reports on your Telegram.

Installation

  1. Clone the repository

    git clone https://github.com/zis3c/STEM-Telebot.git
cd STEM-Telebot

  2. Create and activate virtual environment

    python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# Linux/macOS
# source .venv/bin/activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Configure environment

    copy .env.example .env   # Windows
# cp .env.example .env   # Linux/macOS

  5. Setup Google Cloud

    • Place your service_account.json in the project root.
    • Share your Google Sheet with the Service Account email.

  6. Run bot

    python bot.py

Environment Variables

Core:

  • TELEGRAM_TOKEN - Bot token from @BotFather
  • PORT - Local health endpoint port (default 10000)
  • WEBHOOK_URL - Optional (leave empty for polling mode)

Google Sheets:

  • SHEET_ID - The unique ID of the STEM Google Spreadsheet
  • GOOGLE_CREDENTIALS - (Optional) JSON string of your service account key

Access Control:

  • SUPERADMIN_IDS - Comma-separated Telegram IDs for Superadmins
  • ADMIN_IDS - Comma-separated Telegram IDs for Admins

Deploy to DigitalOcean (Recommended)

This project is optimized for deployment on a DigitalOcean Droplet using systemd.

  1. Clone the repo and install dependencies.
  2. Configure .env and service_account.json.
  3. Create a systemd service (e.g., /etc/systemd/system/stem-telebot.service).
  4. Enable and start: 
    sudo systemctl daemon-reload
sudo systemctl enable --now stem-telebot

Auto Deploy (GitHub Actions)

Push to main triggers .github/workflows/deploy-digitalocean.yml. Ensure you have set the following GitHub Secrets:

  • DROPLET_HOST
  • DROPLET_USER (e.g., deploy)
  • DROPLET_SSH_KEY

Project Structure

STEM-Telebot/
|- bot.py                # Main entrypoint, polling/webhook bootstrap
|- handlers.py           # Core user flows (Verification, Registration, Logs)
|- admin.py              # Admin panel actions (Search, Broadcast, Stats)
|- superadmin.py         # Superadmin controls (Maint, Health, Admin management)
|- database.py           # Google Sheets API wrapper and activity logging
|- keyboards.py          # Reply/Inline keyboard layouts
|- strings.py            # User-facing text (EN/MS)
|- states.py             # Conversation flow state constants
|- demographic_stats_template.py # Web demographic dashboard HTML template
|- membership_card_template.py   # Web membership card HTML template
|- google_apps_script.js # Optional sheet automation helper
`- requirements.txt      # Project dependencies

Web UI Templates

  • Membership web card UI is rendered from membership_card_template.py.
  • Demographic web dashboard UI is rendered from demographic_stats_template.py.
  • bot.py now calls these template modules to keep the main file cleaner and easier to maintain.

Commands

Command Description
/start Open main menu
/help Show usage and info
/settings Open language/settings menu
/admin Open admin dashboard (Admins only)
/superadmin Open superadmin panel (Superadmins only)
/check_pending Scan for pending registrations
/cancel Cancel current operation

How It Works

  1. User Interaction: Users check membership by entering their Matric and IC last 4 digits.
  2. Sheet Verification: The bot searches the Google Sheet and returns the verification status.
  3. Admin Monitoring: Background jobs track new registration rows and notify admins instantly.
  4. Member Management: Admins can search, list, or delete members and broadcast messages to all users.
  5. System Oversight: Superadmins monitor system health and receive daily activity logs.

Troubleshooting

  • Bot not responding: Check if the TELEGRAM_TOKEN is correct.
  • Sheets Error: Ensure the service account email has Editor access to the sheet.
  • Admin Access: Verify your ID is in ADMIN_IDS or SUPERADMIN_IDS.
  • Service Fails: Check logs using journalctl -u stem-telebot -n 100.

Additional Docs

Built with 🔥 by @zis3c