BLA-BOT - A Friendly Telegram Bot

An open-source Telegram Bot written in Python - Tailored for universities/higher education institute groups.

UPDATE: Since Heroku is no longer providing free dynos, Render is now the recommended platform for deploying this bot.

Features
Screenshots
Supported Commands in BOT
Basic Requirements
Installation
- Using pip
- Using Poetry
Usage
To-Do
Contributing
Credits
License & Copyrights
Disclaimer

Features

Free & Open Source
Easy to customize & use
Support for data encryption
Enhanced performance with caching
Intelligent search & indexing
Logging enabled
Secure & Private

Screenshots

Why use BLA-BOT in your academic group?

Easy to use: The bot is easy to use and understand. You can add BLA-BOT to your academic group and easily provide information to your fellow students.
Cool features: BLA-BOT has some cool features like GPA info, birthday wishes, announce to your group as bot, additional academic resources and much more.
Easy to customize: The bot is easy to customize and modify according to your needs.
Secure: The bot is secure and private. Users only see the data they are authorized to see. Even though any other 3rd party can add your bot to their group, they won't be able to utilize some of the bot's features. (like results, student info, etc.) Some of the features are only available to the group admins. Additionally, if any unauthorized person tries to access the bot's data, they won't be able to do so. The data is encrypted and only the bot can decrypt it.
Unauthorized access alert: The bot will alert the group admins about the unauthorized access attempts via dm (This only works if you have already interacted with your bot via dm previously).
Documentation: The bot is well documented and has a detailed README file. You can easily understand how the bot works and how to customize it according to your needs.

Supported Commands in BOT

General Commands

/start or /help - See all the commands
/whois - Get info about someone
/about - Read about the bot
/cancel - Cancel any running operation

Academic Related Commands

/gpa - Show your gpa & results
/staff - Get staff info
/{UNI_NAME_SHORT} - Read about institute
/resources - Explore academic/other resources

Other Commands

/tasks - Manage scheduled tasks (Admin only)
/announce - Broadcast a message (Admin only)

Basic Requirements

Python3 and Pip
Git

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
Render Account (either free or paid) - https://render.com/

-- OR --

Your preferred cloud platform (such as Heroku) - Ex: Heroku Account & Heroku CLI if you're willing to use Heroku, Here they have explained all the steps for getting started with python apps.
Code Editor (such as VS Code)
GitHub/GitLab Account for deploying the bot with Render

Installation

First fork this repository and clone it to your local machine.
Navigate to the directory.
```
cd bla-bot
```

Using pip

Create a virtual environment.
```
python3 -m venv virtualenv
```

Activate virtual environment.

Linux:

source virtualenv/bin/activate

Windows:

virtualenv\Scripts\activate

Install dependencies.
```
pip install -r requirements.txt
```
Now go ahead and configure your bot according to your needs. (See Usage)
Whenever you need to properly exit from the virtual environment, just run the following command:
```
deactivate
```

Using Poetry

Resolve and install all the dependencies.
```
poetry install
```
To start a new shell and activate the virtual environment:
```
poetry shell
```
Now go ahead and configure your bot according to your needs. (See Usage)
Whenever you need to properly exit from the shell and the virtual environment run the following command :
```
exit
```

Usage

Make sure to install the dependencies using above steps first.
Configure the BOT INFO, TIMEZONE DATA and UNIVERSITY INFO in bla_bot.py.
- To choose the correct time zone for TIME_ZONE, you can query all the supported time zones like this (run this in a separate terminal):
```
python3 -c "import pytz; print(pytz.all_timezones)"
```
  Type the name of the time zone you want to use in TIME_ZONE variable.
- Replace university name, short name, and other info in UNIVERSITY_INFO section.
The data files (inside /DATA directory) must be filled and formatted as requested, before encrypting. Then run encrypt_data.py file (inside /DATA directory) to properly encrypt all the data. (Read More)
Obtain a telegram bot token from BotFather (This will be needed as we proceed further.). Start a conversation with BotFather on Telegram and follow the instructions to create a new bot. You will receive a token that you can use to authorize your bot and send requests to the Bot API.
Obtain your personal chat id (This is what we call DEV_CHAT_ID) and group chat id (This is what we call GROUP_CHAT_ID, id of the group that you're going to add the bot) using IDBot (These ids will be needed as we proceed further.). Start a conversation with IDBot on Telegram and follow the instructions to get your chat ids.

Testing on your Local Machine

NOTE: Following environment variables are used to configure the bot in LOCAL ENVIRONMENT.

TELEGRAM_TOKEN -> Telegram bot token.
DEV_CHAT_ID -> The chat id of the developer where the bot will send debug messages.
GROUP_CHAT_ID -> The chat id of your group.
SECRET_KEY -> The secret key for the file decryption process (You can find your key inside DATA directory).

Create a .env file in the root directory of the project and add the following environment variables to it:

DEV_CHAT_ID=use_your_chat_id_here_obtained_from_idbot
ENV=dev # Use 'prod' for production environment
GROUP_CHAT_ID=use_your_group_chat_id_here_obtained_from_idbot
PORT=8443
RENDER_APP_URL=use_your_render_app_url_here_obtained_from_render_dashboard # Keep this empty if you're running the bot locally
SECRET_KEY=use_your_secret_key_here_obtained_from_encrypting_data
TELEGRAM_TOKEN=use_your_telegram_token_obtained_from_botfather_earlier

Run the bot using the following command:

On Linux:
```
python3 bla_bot.py
```
On Windows:
```
py bla_bot.py
```
On Linux using Poetry:
```
poetry run python3 bla_bot.py
```
Cool! Now you can start using your bot.
Open the Telegram app and search for your bot and start a conversation with it. Send /help to your bot to see the list of commands. Test all other features and make sure everything is working as expected.
Press Ctrl-C on the command line to stop the bot.

Deploying on Render

Render is a cloud platform that allows you to deploy your apps in a few clicks. It's free for small projects and has a generous free tier.

NOTE: If you're planning to use Render Cloud Platform, under the free plan, the bot will be automatically stopped after some time of inactivity (~15 minutes). As a work-around, you can use a service like Cron-Job.ORG (Totally Free) to keep the bot alive in certain times.

If you have made any changes to the source code, commit those changes using git add . followed by git commit -m "your-commit-message" and then push those changes to your REMOTE branch on either GitHub or GitLab (This is a mandatory requirement).

Deploy Using Blueprint

If you have already pushed your changes (your data files) to the remote repository; now you can deploy your bot on Render in just a few clicks. We have provided a render app blueprint specification which makes the deployment process much easier. Just click on the button below and sign into your Render account.

You will have to provide the necessary values for the environment variables at first (You can refer the following table for details about the environment variables), except for RENDER_APP_URL. Make sure to update that later. You can find environment variables section in the Environment tab of your web service for updating that.
Deploy Manually
1. Login to your Render account.
2. Click on New Service and select web service.
3. Now you can connect your GitHub or GitLab repository to Render.
After this process, you have to configure the environment variables as mentioned above. You can find environment variables section in the Environment tab of your web service.

Add these keys and respective values to the environment variables:

Key	Value
DEV_CHAT_ID	Your chat id obtained from idbot
ENV	`prod`
GROUP_CHAT_ID	Your group chat id obtained from idbot
RENDER_APP_URL	The url of the Render app. (Ex: `https://your-bot-name.onrender.com`) - Can obtain from Render Dashboard
PORT	`8443`
SECRET_KEY	Your secret key here obtained after data encryption procedure
TELEGRAM_TOKEN	Your Telegram token obtained from botfather earlier

Now click on Save Changes and your bot will be deployed on Render.

Final Steps

Now open your web browser and visit the following URL - Make sure to replace the string {YOUR-BOT-TOKEN} with your bot's token and the {RENDER-URL} with your web service URL.

https://api.telegram.org/bot{YOUR-BOT-TOKEN}/setWebhook?url={RENDER-URL}

You can verify webhook information using following URL:
https://api.telegram.org/bot{YOUR-BOT-TOKEN}/getWebhookInfo

If everything goes well, you can start using your bot right away. Open the Telegram app and search for your bot and start a conversation with it. Send /help to your bot to see the list of commands. Test all other features and make sure everything is working as expected.

Then add your bot to your group and start using it.

NOTE:
You can use BotFather to change the bot's name and profile picture. Also do not forget to add all the commands to your bot using BotFather (Edit Commands). So, users can easily browse all the commands.

Deploying on Heroku Cloud Platform [Deprecated]

Heroku Update
Starting November 28th, 2022, free Heroku Dynos, free Heroku Postgres, and free Heroku Data for Redis® will no longer be available.

Steps to configure on Heroku

NOTE: If you're planning to use Heroku Cloud Platform, under the free plan, the bot will be automatically stopped after some time of inactivity. As a work-around, you can use a service like Cron-Job.ORG (Totally Free) to keep the bot alive in certain times.

If you have made any changes to the source code, commit those changes using git add . followed by git commit -m "commit-message"

If you're willing to use Heroku cloud platform, here's how to do that: (A Heroku account, Heroku CLI and Git will be needed - Read Basic Requirements)

Login to Heroku.
```
heroku login
```
Create a heroku app.
```
heroku create YOUR-APP-NAME
```
Next deploy the app:
```
git push heroku main
```

Now set the environment variables (You can also set them on your Heroku dashboard):

  ```bash
    heroku config:set TELEGRAM_TOKEN=YOUR-TELEGRAM-TOKEN
    heroku config:set DEV_CHAT_ID=YOUR-DEV-CHAT-ID
    heroku config:set GROUP_CHAT_ID=YOUR-GROUP-CHAT-ID
    heroku config:set SECRET_KEY=YOUR-SECRET-KEY
    heroku config:set PORT=8443
    heroku config:set HEROKU_APP_URL=YOUR-HEROKU-APP-URL
    heroku config:set ENV=prod
  ```

To-Do

New Features
- User management (Softban/Ban, Mute, Unban, etc.)
- Add/Link GPA Calculator base code & modules

Contributing

Got an idea? Found a bug? Feel free to open an issue or submit a pull request.

Fork the repository, make your changes and submit a pull request. It's that much easy! If you're not sure how to do that, here's a guide.

Credits

Python-Telegram-Bot

This library provides a pure Python, asynchronous interface for the Telegram Bot API. It's compatible with Python versions 3.7+.

python-telegram-bot is distributed under a LGPLv3 license.

License & Copyrights

The MIT License

This program is free software: you can redistribute it and/or modify it under the terms of the MIT License

** Render, Heroku, Telegram, VS Code are copyrights and/or trademarks of their respective owners.

Disclaimer

The output data of this program is not guaranteed to be correct. Due to unexpected errors in calculations or in other steps, such output data may not be 100% accurate. The author is not responsible for any such faults or any damage caused by this program.

Dilshan-H/bla-bot