Introduction to the bot

In this section of the wiki you will see the structure of the app relative to the bot.

Modules

There is two main modules in src folder: bot and model. The last one will be described in its wiki. This subsection goes about bot and its submodule handlers.

Bot

Let's focus on the main and only file of bot module: bot.py

Line 23 to 53 define the bot Class, Scheduler_Bot. This class describe the bot and configure it. There is only TWO things that can be changed:

1. Persistence of the data
2. How the bot fetch updates from Telegram API

1- Persistence of the data

In case that you aren't interested in save the data of the bot, you can simply erase or comment line 29 and remove the argument persistence of the line 31:

self.updater = Updater(self.token, persistence=persistance, use_context=True)

Leave it as:

self.updater = Updater(self.token, use_context=True)

We don't recommend disabling data persistence as this is the guarantee that the bot will not has any unexpected behavior or malfunction due to data loss.

Keep in mind that without persistence, all data is saved in RAM and if the bot ever has a network or server problem, this data will be loss.

If you want to test or use another type of persistence different that using Pickle, then reach the docs of python-telegram-bot to know how to proceed.

2- How the bot fetch updates from Telegram API

Actually the bot use start_polling() method (line 47) to fetch the updates from Telegram. This method periodically connects to Telegram's servers to check for new updates. If the bot receives a lot of traffic, it might slow down the response times. So if you want to improve this, or want to change the current method, then you might want to use webhooks. Feel free to investigate other methods.

---

The bot runs indefinitely due to self.updater.idle() in line 53. To stop the Bot by press Ctrl+C or send a signal to the Bot process. Reach us if you have a issue with this in your current OS.

The following function:

def set_commands(bot):
    bot.set_my_commands([
        ('create'      , 'Crea una nueva discusión del calendario.'),
        ('config'      , 'Configura las opciones de la discución.'),
        ('vote'        , 'Toma parte en la discusión actual.'),
        ('close'       , 'Cierra la discusión actual.'),
        ('cancel'      , 'Cancela una acción en la configuración o la votación actual si se usa en el grupo.'),
        ('start'       , 'Inicia el bot.'),
        ('help'        , 'Muestra la ayuda.'),
        ('list'        , 'Lista los usuarios que han votado.'),
        ('models'      , 'Lista los modelos disponibles para usar.'),
        ('list_models' , 'Lista los modelos disponibles para usar.'),
    ])

describe the commands available for the bot. In case you want to add a command, you must add it to this list with a proper description. Don't worry, we'll get into the details on creating a new command or handler for the bot soon.

The UI of the bot is intended for a spanish public. Feel free to translate it in a fork for another public.

Handlers

This submodule contains the handlers or commands. Each command has a wiki page with the details. You can find them it the sidebar.

If you want to add a new handler, please follow the following steps:

1. Create a my_command.py in src/bot/handlers or in src\bot\handlers for Windows users. We'll refer to the work within this file from now on.
2. Create a function that serves as callback for the command, i.e what you want the bot to do, as this:

def my_command_callback(update, context):
    # Your code ...

Read the docs of python-telegram-bot to know how to interact with the Telegram API

3. Add:

from telegram.ext import CommandHandler

4. Create a CommandHandler object than can be exported as this:

my_command_handler = CommandHandler('my_command', my_command_callback)

5. Update src/bot/handlers/__init__.py with your new command:

bot_handlers = [
    create_handler, 
    config_handler,
    list_group_handler,
    vote_register_handler,
    vote_select_handler,
    vote_select_callback,
    vote_callback,
    start_handler,
    cancel_handler,
    close_handler,
    list_models_handler,
    set_model_handler,
    my_command_handler,  # Here !!!
]

And now you have a fully functional new command. Remember to update the /help command of the bot with your new command. For details on how to do this, check the help wiki.

Remember to read the docs of python-telegram-bot to know how to interact with the Telegram API and for learn about more complex handlers