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

Features

• Check Results: Use the /result command to fetch your exam results.
• Download latest KTU notifications: Use the /notifications command to fetch KTU notifications and download them.
• Dowbload published academic calendars: Use the /calendar command to fetch published KTU academic calendars and download them.
• Download exam time tables: Use the /timetable command to fetch published KTU exam time tables and download them.
• Subscribe to latest KTU notifications: Use the /subscribe command to recieve new notifications as they arrive.
• Help: Get help using the /help command.
• Live search notifications: Live search and find KTU notifications using inline queries.
• Set course filter for notifications : Use /changefilter command to set course based filter for notifications.

Commands

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

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

• /result: Fetch your 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 current process (only works when inside /notifications or /result wizard)

• /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 :
  1. If you don't want or don't want to work on the notification feature and don't want to setup the database, then just comment out the corresponding calls in app.ts and skip the firebase configuration part below.
  2. The bot makes use of bull queue, 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. 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

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. Build and run the docker using docker compose up -d

5. 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.