thecrux4020/telegram-bot

Telegram Polls

Simple bot to send quizzes to telegram channel
Explore how it works »

Report Bug · Request Feature

Table of Contents

How It Works
Getting Started
Roadmap
Contributing
License
Contact

How It Works

The bot supports 2 different operational modes, jobs and webhooks:

Jobs is designed to run specific tasks, like a crontab job in linux, but the example above is a serverless job.
Webhooks is designed to handle events (messages, audios, images, etc) from telegram. When something happens in the channel, or someone send something to the bot.

Different jobs could run in different lambda functions, or in different environments (for example, a docker image on linux). Each job has a configuration section inside settings.ini, where you can configure all the variables related to it.

Usually, each job has a storage associated with, in the case of polls-job, the storage is a dynamodb table, where all the polls/quizzes are stored.

Each job has a cloudwatch event rule, that triggers the job in a specific point in time, for example, every day at 09:00 AM.

Polls Job

Polls are a way that telegram has to send quizzes or questions to a channel. You can send a quizz with multiple answer, or just a quiz with one correct answer. After you answer to the quiz, you can see the statistics of it.

Example:

The job has a dynamodb table where job manager (you!) store all the questions that want to send to the channel. With the help of a cloudwatch rule, the lambda function trigger in a specific time of the day, take one question from the dynamodb table, send it to the channel and update the status of the quiz.

The table has a field calle has_been_used; this field is used to avoid send the same question multiple times. The lambda function selects a question randomly, and then sends it to the channel; finally, it marks the question as used.

To know which job will run, you have to configure an environment variable called JOB_NAME (for example, JOB_NAME=POLL). In this way, we could create multiple lambda function with the same code for all of functions, but at deploy time we configure the environment variable to specify which job will run inside de lambda function.

Infrastructure

Inside iac/ directory, you'll find the terraform files needed to deploy the infrastructure inside AWS, but if you want, you can host the bot wherever you like. You just need to adjust the config file and run main.py, like other python apps (don't forget installing dependencies and setting environment variables).

Project Structure

app: source code of the app
- helpers: common functions
- jobs: all the jobs, each job has one class
- repository: classes for interact with storage
iac: terraform files
- main.tf: configuration stuff
- poll_job.tf: poll job infrastructure definition
- provider.tf: provider configuration
- variables.tf: variables used in code
images: images for README.md
scripts: usefull scripts
- build.sh: generate build file to deploy in lambda (run before deploy in terraform)
settings.ini: configuration file
main.py: main file of the app, all setup stuff of python app
requirements.txt: dependencies file

Getting Started

Here we go!

lets see the steps to install and run the project...

Prerequisites

First of all, we need to install python and pip. After that, we could use virtualenv to install all dependencies inside virtualenv.

Install pip

sudo apt-get install python3-pip

Install virtualenv

sudo pip3 install virtualenv

Create a telegram bot and join to channel
- How to setup telegram bot

Installation

The steps described here are for running the project locally, if you want to run it inside AWS, see deploy on AWS

Clone the repository

git clone https://github.com/thecrux4020/telegram-bot

Now create virtualenv in the venv directory

virtualenv -p python3 venv

Activate the virtual environment

source venv/bin/activate

Install all dependecies

pip3 install -r requirements.txt

Configure environment variables

export JOB_NAME=POLL && export TELEGRAM_TOKEN=mytoken

replace "mytoken" with the token obtained from telegram bot setup

Replace channel_id and table_name in settings.ini file, with your parameters.

Deploy on AWS

For the AWS deploy, we will use terraform as IaC (Infrastructure As Code) tool to deploy the bot in AWS.

Install terraform
Create bucket to save terraform state: How to create bucket on AWS

Grant s3 permission to your actual IAM user:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "s3:ListBucket",
               "Resource": "arn:aws:s3:::mybucket"
           },
           {
               "Effect": "Allow",
               "Action": ["s3:GetObject", "s3:PutObject"],
               "Resource": "arn:aws:s3:::mybucket/path/to/my/key"
           }
       ]
   }

Initialize terraform
```
terraform init
```
Deploy changes in AWS (your user must have permissions to create resources)
```
terraform apply
```

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Leandro Mantovani - leandro.mantovani93@gmail.com

Project Link: https://github.com/thecrux4020/telegram-bot

thecrux4020 / telegram-bot