🏆 Contest Alert Bot

A Telegram bot that sends alerts ~2 hours before coding contests on:

• 🟦 Codeforces
• 🟨 LeetCode (optional extension)
• 🟫 CodeChef (optional / unstable API)

🚀 Fully serverless — runs on GitHub Actions (FREE) ⚡ No backend required 🔔 No spam (duplicate-safe)

---

📁 Project Structure

your-repo/
├── contest_alert.py
├── sent.json
└── .github/
    └── workflows/
        └── contest_alert.yml

---

🚀 Setup (5 Minutes)

1️⃣ Create Telegram Bot

1. Open Telegram → search @BotFather
2. Send /newbot
3. Follow steps → copy your Bot Token

---

2️⃣ Get Chat ID

1. Start chat with your bot (send "hi")
2. Open:

https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

3. Find:

"chat": { "id": 123456789 }

---

3️⃣ Create GitHub Repo

• Go to GitHub → New Repository

• Upload:

  • contest_alert.py
  • .github/workflows/contest_alert.yml

---

4️⃣ Add Secrets

Go to:

Repo → Settings → Secrets → Actions

Add:

Name	Value
TELEGRAM_BOT_TOKEN	your bot token
TELEGRAM_CHAT_ID	your chat id

---

5️⃣ Enable GitHub Actions

• Open Actions tab
• Enable workflows
• Click Run workflow (for testing)

---

⚙️ How It Works

• Runs every 30 minutes (optimized for free tier)
• Checks contests starting in:

105 to 125 minutes (≈ 2 hours)

• Sends alert via Telegram
• Stores sent contests in sent.json to avoid duplicates

---

🔔 Example Alert

⏰ Contest Alert — 112 mins left!

🔵 Codeforces Round 987 (Div. 2)
📌 Platform: Codeforces
🕐 Starts: 2026-04-10 14:35 UTC
🔗 https://codeforces.com/contest/987

---

🧠 Features

• ✅ Serverless (GitHub Actions)
• ✅ Duplicate prevention
• ✅ Free forever (within limits)
• ✅ Easy setup (5 min)
• ✅ Extendable

---

⚠️ Free Tier Limits (Important)

GitHub provides:

2000 minutes/month

Usage:

Runs every 30 min → 48 runs/day
→ ~1440 min/month ✅ SAFE

❌ Do NOT use 15 min cron (will exceed limit)

---

🛠 Troubleshooting

Issue	Fix
No alerts	Run workflow manually & check logs
Telegram 401	Invalid bot token
Telegram 400	Start chat with bot first
No contests detected	Check API response / timing window

---

💡 Advanced Ideas

• 🔔 10-minute reminder before contest
• 👥 Multi-user support (multiple chat IDs)
• 🧠 AI contest recommendations
• 📅 Google Calendar sync
• 📊 Difficulty-based filtering

---

📌 Notes

• Codeforces API is reliable ✅
• LeetCode uses GraphQL (can be added)
• CodeChef API is unstable ⚠️

---

🤝 Contributing

Pull requests are welcome! Feel free to add:

• New platforms
• UI improvements
• Smarter alerts

---

⭐ Support

If you like this project:

• ⭐ Star the repo
• 🍴 Fork it
• 📢 Share with friends

---

🏁 Final

Build once. Never miss a contest again.

Happy Coding 🚀