devadathanmb/ktu-bot

A telegram bot to view KTU exam results and notifications easily.

KTU Bot

Welcome to the KTU Bot! This Telegram bot helps students check their exam results, find latest KTU notifications, academic calendars, exam time tables and alert users when new notifications arrive.

Find the bot here

Table of Contents

• KTU Bot
  • Features
  • Commands
  • Inline Query
  • Local development setup
    • Running Locally (Without Docker - Not preferred)
    • Running with Docker Compose (Preferred)
  • Production setup
    • Pre-requisites
    • Steps
  • Contributing
  • Bugs and Feedback
  • License

Features

• Check Results: Easily check latest published KTU results.
• Check old results: Check any results ever published in the history of KTU (yeah for real).
• Download published KTU notifications: Browse and download any published KTU notification.
• Dowbload published academic calendars: Browse and download any published KTU academic calendars.
• Download published exam time tables: Browse and download any published KTU exam time tables.
• Subscribe to latest KTU notifications: Get alerted when new notifications arrive.
• Filtered notifications: Only recieve notifications that you care about. No trash.
• Live search notifications: Search and download published notifications using the keyword.

Commands

• /start: Start the bot and get a welcome message.

• /help: Show a help message with available commands.

• /result: Fetch your exam results.

• /olresults: Fetch previously published exam results.

• /notifications: Find and download latest KTU notifications.

• /calendar: Find and download published KTU academic calendars.

• /timetable: Find and download published KTU exam time tables.

• /subscribe: Subscribe to recieve latest KTU notifications as they arrive.

• /unsubscribe: Unsubscribe from recieving KTU notifications.

• /changefilter: Change currently set notification filter.

• /cancel: Cancel ongoing process.

• /code : See project source code.

Inline Query

Use inline query to live search the notification you want to. No more pain of scrolling through the webpage for the notification.

eg: @ktu_results_bot calendar : This returns all the results that matches word "calendar" like Academic calendars etc.

Local development setup

Note

The bot makes use of BullMQ, a redis based nodejs queue, for the live notifications feature. Thus, it requires you to have a redis db instance running. The docker compose method below already does that for you.

Running Locally (Without Docker - Not preferred)

1. Install Node.js and npm on your machine.

2. Clone the repository:

   git clone https://github.com/devadathanmb/ktu-bot.git

3. Navigate to the project directory:

   cd ktu-bot

4. Install dependencies:

   npm install

5. Set up your Telegram bot token:

   • Create a new bot on Telegram using the BotFather.

   • Copy the bot token.

   • Create a .env file in the project root and add:

     BOT_TOKEN="your-telegram-bot-token"

     See env.example file for example

6. Create a Firebase project and setup a Firestore database in Firebase console

7. Download the serviceAccountKey.json file, minify it and base64 encode it using

   jq -r tostring serviceAccountKey.json  | base64

8. Copy the base64 encoded serviceAccountKey.json string to .env

   FIREBASE_SERVICE_ACCOUNT="base64 encoded string"
   

9. Set the ENV_TYPE variable to DEVELOPMENT in .env

   ENV_TYPE="DEVELOPMENT"
   

10. Build the bot:

    npm run build

11. Start the bot:

    npm run start

Running with Docker Compose (Preferred)

1. Install Docker and Docker Compose on your machine.

2. Clone the repository:

   git clone https://github.com/devadathanmb/ktu-bot.git

3. Navigate to the project directory:

   cd ktu-bot

4. Create a .env file in the project root and add:

   BOT_TOKEN="your-telegram-bot-token"

5. Create a Firebase project and setup a Firestore database in Firebase console

6. Download the serviceAccountKey.json file, minify it and base64 encode it using

   jq -r tostring serviceAccountKey.json  | base64

7. Copy the base64 encoded serviceAccountKey.json string to .env

   FIREBASE_SERVICE_ACCOUNT="base64 encoded string"
   

8. Set the ENV_TYPE variable to DEVELOPMENT in .env

   ENV_TYPE="DEVELOPMENT"
   

9. Make sure to add all necessary environment variables to .env mentioned in env.example

10. Run the application using Docker Compose:

    docker-compose up

The bot should now be running and accessible on Telegram.

Production setup

This bot makes use of Telegram bot API's webhook mechanism in production.

This is because of certain performance benefits that webhook offers with high concurrent load during peak times. For more info see this.

Note

Using webhooks in production is optional but recommended if your bot has heavy concurrent traffic. If you don't want to setup webhooks, just follow the above development setup guide and you are good to go.

Pre-requisites

To run the bot using webhooks in production, some pre-requisites are required. They are mentioned below:

• A VPS
• A domain
• SSL certificate for the domain (you can use let's encrypt for that)
• Docker
• A reverse proxy (like nginx)

Note

The below guide makes use of nginx as the reverse proxy and assumes that you have reverse proxy configured for the webhook endpoint with HTTPS traffic handling

Steps

1. Set up an nginx reverse proxy for the webhook endpoint. See this for more information. Checkout basic example in webhook.conf

2. Clone the repository using

   git clone https://github.com/devadathanmb/ktu-bot.git && cd ktu-bot/

3. Set ENV_TYPE=PRODUCTION in .env file. See env.example

4. Make sure to add all necessary environment variables to .env mentioned in env.example

5. Build and run the docker using docker compose up -d

6. Start the nginx server (eg : sudo systemctl restart nginx)

That's it. Your bot should be running now in webhook mode.

Contributing

If you encounter any issues, have feature suggestions, or want to contribute to the project, please feel free to fork and make a PR.

Bugs and Feedback

If you find any bugs or have feedback, please open an issue on GitHub.

License

This project is licensed under the GPL 3.0 License - see the LICENSE.md file for details.