telegram-periodic-msg-bot


Nametelegram-periodic-msg-bot JSON
Version 0.3.4 PyPI version JSON
download
home_pagehttps://github.com/ebellocchia/telegram_periodic_msg_bot
SummaryTelegram bot for sending periodic messages
upload_time2024-02-09 18:43:20
maintainerEmanuele Bellocchia
docs_urlNone
authorEmanuele Bellocchia
requires_python>=3.7
licenseMIT
keywords telegram bot telegram bot periodic messages
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Telegram Periodic Message Bot

| |
|---|
| [![PyPI - Version](https://img.shields.io/pypi/v/telegram_periodic_msg_bot.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/telegram_periodic_msg_bot/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/telegram_periodic_msg_bot.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/telegram_periodic_msg_bot/) [![GitHub License](https://img.shields.io/github/license/ebellocchia/telegram_periodic_msg_bot?label=License)](https://github.com/ebellocchia/telegram_periodic_msg_bot?tab=MIT-1-ov-file) |
| [![Build](https://github.com/ebellocchia/telegram_periodic_msg_bot/actions/workflows/build.yml/badge.svg)](https://github.com/ebellocchia/telegram_periodic_msg_bot/actions/workflows/build.yml) |
| [![Codacy grade](https://img.shields.io/codacy/grade/d1cc7c1692de4939a23e626981923e83?label=Codacy%20Grade)](https://app.codacy.com/gh/ebellocchia/telegram_periodic_msg_bot/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/ebellocchia/telegram_periodic_msg_bot?label=CodeFactor%20Grade)](https://www.codefactor.io/repository/github/ebellocchia/telegram_periodic_msg_bot) |
| |

## Introduction

Telegram bot for sending periodic messages in groups based on *pyrogram*.\
A single bot instance can be used with multiple periodic messages (with different periods) and in multiple groups.

## Setup

### Create Telegram app

In order to use the bot, in addition to the bot token you also need an APP ID and hash.\
To get them, create an app using the following website: [https://my.telegram.org/apps](https://my.telegram.org/apps).

### Installation

The package requires Python 3, it is not compatible with Python 2.\
To install it:
- Using *setuptools*:

        python setup.py install

- Using *pip*:

        pip install telegram_periodic_msg_bot

To run the bot, edit the configuration file by specifying the API ID/hash and bot token. Then, move to the *app* folder and run the *bot.py* script:

    cd app
    python bot.py

When run with no parameter, *conf/config.ini* will be the default configuration file (in this way it can be used for different groups).\
To specify a different configuration file:

    python bot.py -c another_conf.ini
    python bot.py --config another_conf.ini

Of course, the *app* folder can be moved elsewhere if needed.

## Configuration

An example of configuration file is provided in the *app/conf* folder.\
The list of all possible fields that can be set is shown below.

|Name|Description|
|---|---|
|**[pyrogram]**|Configuration for pyrogram|
|`session_name`|Session name of your choice|
|`api_id`|API ID from [https://my.telegram.org/apps](https://my.telegram.org/apps)|
|`api_hash`|API hash from [https://my.telegram.org/apps](https://my.telegram.org/apps)|
|`bot_token`|Bot token from BotFather|
|**[app]**|Configuration for app|
|`app_is_test_mode`|True to activate test mode false otherwise|
|`app_lang_file`|Language file in XML format (default: English)|
|**[task]**|Configuration for tasks|
|`tasks_max_num`|Maximum number of running tasks (totally, in all groups). Default: 20.|
|**[message]**|Configuration for message|
|`message_max_len`|Maximum message length in characters. Default: 4000.|
|**[logging]**|Configuration for logging|
|`log_level`|Log level, same of python logging (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Default: `INFO`.|
|`log_console_enabled`|True to enable logging to console, false otherwise (default: `true`)|
|`log_file_enabled`|True to enable logging to file, false otherwise (default: `false`). If false, all the next fields will be skipped.|
|`log_file_name`|Log file name|
|`log_file_use_rotating`|True for using a rotating log file, false otherwise|
|`log_file_max_bytes`|Maximum size in bytes for a log file. When reached, a new log file is created up to `log_file_backup_cnt`. Valid only if `log_file_use_rotating` is true.|
|`log_file_backup_cnt`|Maximum number of log files. Valid only if `log_file_use_rotating` is true.|
|`log_file_append`|True to append to log file, false to start from a new file each time. Valid only if `log_file_use_rotating` is false.|

## Supported Commands

List of supported commands:
- `help`: show this message
- `alive`: show if bot is active
- `msgbot_set_test_mode true/false`: enable/disable test mode
- `msgbot_is_test_mode`: show if test mode is enabled
- `msgbot_version`: show bot version
- `msgbot_task_start MSG_ID PERIOD_HOURS [START_HOUR] MSG`: start a message task in the current chat. If the task `MSG_ID` already exists in the current chat, an error message will be shown. To start it again, it shall be stopped with the `msgbot_task_stop` command.\
Parameters:
    - `MSG_ID`: Message ID
    - `PERIOD_HOURS`: Task period in hours, it shall be between 1 and 24
    - `START_HOUR` (optional): Task start hour, it shall be between 0 and 23. Default value: 0.
    - `MSG`: Message to be sent periodically, it shall be on a new line
- `msgbot_task_stop MSG_ID`: stop the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\
Parameters:
    - `MSG_ID`: CoinGecko *ID*
- `msgbot_task_stop_all`: stop all message tasks in the current chat
- `msgbot_task_pause MSG_ID`: pause the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\
Parameters:
    - `MSG_ID`: Message ID
- `msgbot_task_resume MSG_ID`: resume the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\
Parameters:
    - `MSG_ID`: Message ID
- `msgbot_task_get MSG_ID`: show the message set for the specified message task in the current chat.\
Parameters:
    - `MSG_ID`: Message ID
- `msgbot_task_set MSG_ID MSG`: set the message of the specified message task in the current chat.\
Parameters:
    - `MSG_ID`: Message ID
    - `MSG`: Message to be sent periodically, it shall be on a new line
- `msgbot_task_delete_last_msg MSG_ID true/false`: enable/disable the deletion of last messages for the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\
Parameters:
    - `MSG_ID`: Message ID
    - `flag`: true or false
- `msgbot_task_info`: show the list of active message tasks in the current chat

Messages can contain HTML tags if needed (e.g. for bold/italic text), while Markdown tags are not supported.\
By default, a message task will delete the last sent message when sending a new one. This can be enabled/disabled with the `msgbot_task_delete_last_msg` command.

The task period starts from the specified starting hour (be sure to set the correct time on the VPS), for example:
- A task period of 8 hours starting from 00:00 will send the message at: 00:00, 08:00 and 16:00
- A task period of 6 hours starting from 08:00 will send the message at: 08:00, 14:00, 20:00 and 02:00

**Examples**

Send a periodical message every 8 hours starting from 00:00 in the current chat:

    /msgbot_task_start test_msg 8
    Hi,
    This is a <i>periodic message</i>.
    <b>Bye!</b>

Pause/Resume/Stop the previous task:

    /msgbot_task_pause test_msg
    /msgbot_task_resume test_msg
    /msgbot_task_stop test_msg

Show the message set for the previous task:

    /msgbot_task_get test_msg

Set a new message set for the previous task:

    /msgbot_task_set test_msg
    Hello,
    This is a <i>different periodic message</i>.
    <b>Bye bye!</b>

Set task so that it doesn't delete the last sent message:

    /msgbot_task_delete_last_msg test_msg false

Send a periodical message every 6 hours starting from 10:00 in the current chat:

    /msgbot_task_start test_msg 6 10
    Periodic message with start hour

## Run the Bot

It'd be better if the bot is an administrator of the group. This is mandatory if it needs to delete the last sent messages.\
In order to send messages periodically, the bot shall run 24h/24h so it's suggested to run it on a VPS (there is no performance requirements, so a cheap VPS will suffice).

## Test Mode

During test mode, the bot will work as usual but the task period will be applied in minutes instead of hours. This allows to quickly check if it is working.

## Translation

The messages sent by the bot on Telegram can be translated into different languages (the default language is English) by providing a custom XML file.\
The XML file path is specified in the configuration file (`app_lang_file` field).\
An example XML file in italian is provided in the folder *app/lang*.

# License

This software is available under the MIT license.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/ebellocchia/telegram_periodic_msg_bot",
    "name": "telegram-periodic-msg-bot",
    "maintainer": "Emanuele Bellocchia",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "ebellocchia@gmail.com",
    "keywords": "telegram,bot,telegram bot,periodic messages",
    "author": "Emanuele Bellocchia",
    "author_email": "ebellocchia@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/ac/1e/cd8b60dce7e4d09ff472a483e940f78c43341b4b982624a661ad3883b255/telegram_periodic_msg_bot-0.3.4.tar.gz",
    "platform": "any",
    "description": "# Telegram Periodic Message Bot\r\n\r\n| |\r\n|---|\r\n| [![PyPI - Version](https://img.shields.io/pypi/v/telegram_periodic_msg_bot.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/telegram_periodic_msg_bot/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/telegram_periodic_msg_bot.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/telegram_periodic_msg_bot/) [![GitHub License](https://img.shields.io/github/license/ebellocchia/telegram_periodic_msg_bot?label=License)](https://github.com/ebellocchia/telegram_periodic_msg_bot?tab=MIT-1-ov-file) |\r\n| [![Build](https://github.com/ebellocchia/telegram_periodic_msg_bot/actions/workflows/build.yml/badge.svg)](https://github.com/ebellocchia/telegram_periodic_msg_bot/actions/workflows/build.yml) |\r\n| [![Codacy grade](https://img.shields.io/codacy/grade/d1cc7c1692de4939a23e626981923e83?label=Codacy%20Grade)](https://app.codacy.com/gh/ebellocchia/telegram_periodic_msg_bot/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/ebellocchia/telegram_periodic_msg_bot?label=CodeFactor%20Grade)](https://www.codefactor.io/repository/github/ebellocchia/telegram_periodic_msg_bot) |\r\n| |\r\n\r\n## Introduction\r\n\r\nTelegram bot for sending periodic messages in groups based on *pyrogram*.\\\r\nA single bot instance can be used with multiple periodic messages (with different periods) and in multiple groups.\r\n\r\n## Setup\r\n\r\n### Create Telegram app\r\n\r\nIn order to use the bot, in addition to the bot token you also need an APP ID and hash.\\\r\nTo get them, create an app using the following website: [https://my.telegram.org/apps](https://my.telegram.org/apps).\r\n\r\n### Installation\r\n\r\nThe package requires Python 3, it is not compatible with Python 2.\\\r\nTo install it:\r\n- Using *setuptools*:\r\n\r\n        python setup.py install\r\n\r\n- Using *pip*:\r\n\r\n        pip install telegram_periodic_msg_bot\r\n\r\nTo run the bot, edit the configuration file by specifying the API ID/hash and bot token. Then, move to the *app* folder and run the *bot.py* script:\r\n\r\n    cd app\r\n    python bot.py\r\n\r\nWhen run with no parameter, *conf/config.ini* will be the default configuration file (in this way it can be used for different groups).\\\r\nTo specify a different configuration file:\r\n\r\n    python bot.py -c another_conf.ini\r\n    python bot.py --config another_conf.ini\r\n\r\nOf course, the *app* folder can be moved elsewhere if needed.\r\n\r\n## Configuration\r\n\r\nAn example of configuration file is provided in the *app/conf* folder.\\\r\nThe list of all possible fields that can be set is shown below.\r\n\r\n|Name|Description|\r\n|---|---|\r\n|**[pyrogram]**|Configuration for pyrogram|\r\n|`session_name`|Session name of your choice|\r\n|`api_id`|API ID from [https://my.telegram.org/apps](https://my.telegram.org/apps)|\r\n|`api_hash`|API hash from [https://my.telegram.org/apps](https://my.telegram.org/apps)|\r\n|`bot_token`|Bot token from BotFather|\r\n|**[app]**|Configuration for app|\r\n|`app_is_test_mode`|True to activate test mode false otherwise|\r\n|`app_lang_file`|Language file in XML format (default: English)|\r\n|**[task]**|Configuration for tasks|\r\n|`tasks_max_num`|Maximum number of running tasks (totally, in all groups). Default: 20.|\r\n|**[message]**|Configuration for message|\r\n|`message_max_len`|Maximum message length in characters. Default: 4000.|\r\n|**[logging]**|Configuration for logging|\r\n|`log_level`|Log level, same of python logging (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Default: `INFO`.|\r\n|`log_console_enabled`|True to enable logging to console, false otherwise (default: `true`)|\r\n|`log_file_enabled`|True to enable logging to file, false otherwise (default: `false`). If false, all the next fields will be skipped.|\r\n|`log_file_name`|Log file name|\r\n|`log_file_use_rotating`|True for using a rotating log file, false otherwise|\r\n|`log_file_max_bytes`|Maximum size in bytes for a log file. When reached, a new log file is created up to `log_file_backup_cnt`. Valid only if `log_file_use_rotating` is true.|\r\n|`log_file_backup_cnt`|Maximum number of log files. Valid only if `log_file_use_rotating` is true.|\r\n|`log_file_append`|True to append to log file, false to start from a new file each time. Valid only if `log_file_use_rotating` is false.|\r\n\r\n## Supported Commands\r\n\r\nList of supported commands:\r\n- `help`: show this message\r\n- `alive`: show if bot is active\r\n- `msgbot_set_test_mode true/false`: enable/disable test mode\r\n- `msgbot_is_test_mode`: show if test mode is enabled\r\n- `msgbot_version`: show bot version\r\n- `msgbot_task_start MSG_ID PERIOD_HOURS [START_HOUR] MSG`: start a message task in the current chat. If the task `MSG_ID` already exists in the current chat, an error message will be shown. To start it again, it shall be stopped with the `msgbot_task_stop` command.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n    - `PERIOD_HOURS`: Task period in hours, it shall be between 1 and 24\r\n    - `START_HOUR` (optional): Task start hour, it shall be between 0 and 23. Default value: 0.\r\n    - `MSG`: Message to be sent periodically, it shall be on a new line\r\n- `msgbot_task_stop MSG_ID`: stop the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\\\r\nParameters:\r\n    - `MSG_ID`: CoinGecko *ID*\r\n- `msgbot_task_stop_all`: stop all message tasks in the current chat\r\n- `msgbot_task_pause MSG_ID`: pause the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n- `msgbot_task_resume MSG_ID`: resume the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n- `msgbot_task_get MSG_ID`: show the message set for the specified message task in the current chat.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n- `msgbot_task_set MSG_ID MSG`: set the message of the specified message task in the current chat.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n    - `MSG`: Message to be sent periodically, it shall be on a new line\r\n- `msgbot_task_delete_last_msg MSG_ID true/false`: enable/disable the deletion of last messages for the specified message task in the current chat. If the task `MSG_ID` does not exist in the current chat, an error message will be shown.\\\r\nParameters:\r\n    - `MSG_ID`: Message ID\r\n    - `flag`: true or false\r\n- `msgbot_task_info`: show the list of active message tasks in the current chat\r\n\r\nMessages can contain HTML tags if needed (e.g. for bold/italic text), while Markdown tags are not supported.\\\r\nBy default, a message task will delete the last sent message when sending a new one. This can be enabled/disabled with the `msgbot_task_delete_last_msg` command.\r\n\r\nThe task period starts from the specified starting hour (be sure to set the correct time on the VPS), for example:\r\n- A task period of 8 hours starting from 00:00 will send the message at: 00:00, 08:00 and 16:00\r\n- A task period of 6 hours starting from 08:00 will send the message at: 08:00, 14:00, 20:00 and 02:00\r\n\r\n**Examples**\r\n\r\nSend a periodical message every 8 hours starting from 00:00 in the current chat:\r\n\r\n    /msgbot_task_start test_msg 8\r\n    Hi,\r\n    This is a <i>periodic message</i>.\r\n    <b>Bye!</b>\r\n\r\nPause/Resume/Stop the previous task:\r\n\r\n    /msgbot_task_pause test_msg\r\n    /msgbot_task_resume test_msg\r\n    /msgbot_task_stop test_msg\r\n\r\nShow the message set for the previous task:\r\n\r\n    /msgbot_task_get test_msg\r\n\r\nSet a new message set for the previous task:\r\n\r\n    /msgbot_task_set test_msg\r\n    Hello,\r\n    This is a <i>different periodic message</i>.\r\n    <b>Bye bye!</b>\r\n\r\nSet task so that it doesn't delete the last sent message:\r\n\r\n    /msgbot_task_delete_last_msg test_msg false\r\n\r\nSend a periodical message every 6 hours starting from 10:00 in the current chat:\r\n\r\n    /msgbot_task_start test_msg 6 10\r\n    Periodic message with start hour\r\n\r\n## Run the Bot\r\n\r\nIt'd be better if the bot is an administrator of the group. This is mandatory if it needs to delete the last sent messages.\\\r\nIn order to send messages periodically, the bot shall run 24h/24h so it's suggested to run it on a VPS (there is no performance requirements, so a cheap VPS will suffice).\r\n\r\n## Test Mode\r\n\r\nDuring test mode, the bot will work as usual but the task period will be applied in minutes instead of hours. This allows to quickly check if it is working.\r\n\r\n## Translation\r\n\r\nThe messages sent by the bot on Telegram can be translated into different languages (the default language is English) by providing a custom XML file.\\\r\nThe XML file path is specified in the configuration file (`app_lang_file` field).\\\r\nAn example XML file in italian is provided in the folder *app/lang*.\r\n\r\n# License\r\n\r\nThis software is available under the MIT license.\r\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Telegram bot for sending periodic messages",
    "version": "0.3.4",
    "project_urls": {
        "Download": "https://github.com/ebellocchia/telegram_periodic_msg_bot/archive/v0.3.4.tar.gz",
        "Homepage": "https://github.com/ebellocchia/telegram_periodic_msg_bot"
    },
    "split_keywords": [
        "telegram",
        "bot",
        "telegram bot",
        "periodic messages"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "12231c00f6f7c5bd769037214373b0e5705a62e2dde38a649a39a6eb62e2da36",
                "md5": "3e3c7e6502fb005a359a20661ebcb054",
                "sha256": "2a632dc816c19b0e5f88a3523da4caed60a1a4faaa4fcc33cf30c057aacb4b0d"
            },
            "downloads": -1,
            "filename": "telegram_periodic_msg_bot-0.3.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3e3c7e6502fb005a359a20661ebcb054",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 57206,
            "upload_time": "2024-02-09T18:43:18",
            "upload_time_iso_8601": "2024-02-09T18:43:18.481807Z",
            "url": "https://files.pythonhosted.org/packages/12/23/1c00f6f7c5bd769037214373b0e5705a62e2dde38a649a39a6eb62e2da36/telegram_periodic_msg_bot-0.3.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ac1ecd8b60dce7e4d09ff472a483e940f78c43341b4b982624a661ad3883b255",
                "md5": "ebf1b7c7ff5106260d2461f592169113",
                "sha256": "3df5bf7e3ce9f29e1d0e5c6178c435c9da27fc7c9a306a121ec3330765e3c488"
            },
            "downloads": -1,
            "filename": "telegram_periodic_msg_bot-0.3.4.tar.gz",
            "has_sig": false,
            "md5_digest": "ebf1b7c7ff5106260d2461f592169113",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 30257,
            "upload_time": "2024-02-09T18:43:20",
            "upload_time_iso_8601": "2024-02-09T18:43:20.468620Z",
            "url": "https://files.pythonhosted.org/packages/ac/1e/cd8b60dce7e4d09ff472a483e940f78c43341b4b982624a661ad3883b255/telegram_periodic_msg_bot-0.3.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-09 18:43:20",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ebellocchia",
    "github_project": "telegram_periodic_msg_bot",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "tox": true,
    "lcname": "telegram-periodic-msg-bot"
}
        
Elapsed time: 0.24535s