-
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Mustafa Asaad
committed
Mar 23, 2022
1 parent
4a1b014
commit 660895f
Showing
1 changed file
with
114 additions
and
91 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,148 +1,171 @@ | ||
| # tgbotapi | ||
|
|
||
| The Ultimate [Telegram Bot API](https://core.telegram.org/bots/api) Client Framework | ||
| The Ultimate [Telegram Bot API](https://core.telegram.org/bots/api) Framework | ||
|
|
||
| [](https://github.com/ma24th/tgbotapi/blob/master/LICENSE) | ||
| [](https://pypi.org/project/tgbotapi/) | ||
|  | ||
|  | ||
| []() | ||
| []() | ||
| [](https://t.me/GuardBotc) | ||
|
|
||
| > Based On [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) | ||
| ## How to Use | ||
| ### Installation | ||
| There are two ways to install the framework: | ||
| * Installation using pip (a Python package manager)*: | ||
| ```bash | ||
| $ pip install tgbotapi | ||
| ``` | ||
| * Installation from source (requires git): | ||
|
|
||
| ```bash | ||
| $ git clone https://github.com/ma24th/tgbotapi.git | ||
| $ cd tgbotapi | ||
| $ python setup.py install | ||
| ``` | ||
|
|
||
| It is generally recommended to use the first option. | ||
|
|
||
| *While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling `pip install tgbotapi --upgrade`* | ||
| > Based On [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) | ||
| ## Writing your first bot | ||
| ## How to Use | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| It is presumed that you [have obtained an API token with @BotFather](https://core.telegram.org/bots#botfather). We will call this token `TOKEN`. | ||
| Furthermore, you have basic knowledge of the Python programming language and more importantly [the Telegram Bot API](https://core.telegram.org/bots/api). | ||
| > Presumed you have obtained a bot token with [@BotFather](https://core.telegram.org/bots#botfather) | ||
| ### A simple echo bot | ||
|
|
||
| The Bot class (defined in \__init__.py) encapsulates all API calls in a single class. It provides functions such as `send_xyz` (`send_message`, `send_document` etc.) and several ways to listen for incoming messages. | ||
| The Bot class encapsulates all API calls in a single class, It provides functions such as `send_xyz` (`send_message` | ||
| , `send_document` etc.) | ||
| and several ways to listen for incoming messages. | ||
|
|
||
| Create a file called `echo_bot.py`. Then, open the file and create an instance of the Bot class. | ||
|
|
||
| Create a file called `echo_bot.py`. | ||
| Then, open the file and create an instance of the TBot class. | ||
| ```python | ||
| import tgbotapi | ||
|
|
||
| bot = tgbotapi.Bot(based_url="https://api.telegram.org/bot"+ "BOT_TOKEN") | ||
| ``` | ||
| *Note: Make sure to actually replace TOKEN with your own API token.* | ||
| # Note: Make sure to actually replace TOKEN with your own API token | ||
| bot = tgbotapi.Bot(access_token="TOKEN") | ||
|
|
||
| After that declaration, we need to register some so-called message handlers. | ||
| Message handlers define filters which a message must pass. If a message passes the filter, | ||
| the decorated function is called and the incoming message is passed as an argument. | ||
|
|
||
| Let's define a message handler which handles incoming `/start` and `/help` bot_command. | ||
| ```python | ||
| @bot.update_handler(update_type='message', bot_command=['start', 'help']) | ||
| # After that declaration, we need to register some so-called update handler. | ||
| # update_type define filters which can be a message, If a message passes the filter, | ||
| # the decorated function is called and the incoming message is passed as an argument. | ||
|
|
||
| # Let's define an update handler which handles incoming `/start` and `/help` bot_command. | ||
| @bot.update_handler(update_type='message', bot_command=['/start', '/help']) | ||
| # A function which is decorated by an update handler can have an arbitrary name, | ||
| # however, it must have only one parameter (the msg) | ||
| def send_welcome(msg): | ||
| bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, | ||
| bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, | ||
| disable_web_page_preview=False, disable_notification=False, reply_to_message_id=msg.message_id, | ||
| allow_sending_without_reply=True, reply_markup=None) | ||
| ``` | ||
| A function which is decorated by a message handler __can have an arbitrary name, however, it must have only one parameter (the message)__. | ||
|
|
||
| Let's add another handler: | ||
| ```python | ||
|
|
||
| # This one echoes all incoming text messages back to the sender. | ||
| # It uses a lambda function to test a message. If the lambda returns True, | ||
| # the message is handled by the decorated function. | ||
| # Since we want all text messages to be handled by this function, | ||
| # so it simply always return True. | ||
| @bot.update_handler(update_type='message', func=lambda message: message.text) | ||
| def echo_all(msg): | ||
| bot.send_message(chat_id=msg.chat.uid, text=msg.text, parse_mode=None, entities=None, | ||
| disable_web_page_preview=False, disable_notification=False, reply_to_message_id=None, | ||
| allow_sending_without_reply=True, reply_markup=None) | ||
|
|
||
| ``` | ||
| This one echoes all incoming text messages back to the sender. It uses a lambda function to test a message. If the lambda returns True, the message is handled by the decorated function. Since we want all messages to be handled by this function, we simply always return True. | ||
|
|
||
| *Note: all handlers are tested in the order in which they were declared* | ||
|
|
||
| We now have a basic bot which replies a static message to "/start" and "/help" commands and which echoes the rest of the sent messages. To start the bot, add the following to our source file: | ||
| ```python | ||
| # Finally, we call long polling function | ||
| bot.polling() | ||
| ``` | ||
| Alright, that's it! Our source file now looks like this: | ||
|
|
||
| Alright, that's it! Our source file, To start the bot, simply open up a terminal and enter `python echo_bot.py` to run | ||
| the bot! | ||
| Test it by sending commands ('/start' and '/help') and arbitrary text messages. | ||
|
|
||
| ### ChangeLog | ||
|
|
||
| **_version 5.7_** | ||
|
|
||
| - Added support for Video Stickers. Added the field is_video to the classes Sticker and StickerSet. | ||
| - Added the parameter webm_sticker to the methods createNewStickerSet and addStickerToSet. | ||
|
|
||
| **_Fixes_** | ||
|
|
||
| - No Issues until Now | ||
|
|
||
| ### Framework Explanation | ||
|
|
||
| A `handler` is a function that is decorated with the `update_handler` decorator of a Bot instance, handlers consist of | ||
| one or multiple filters, Each filter match returns True for a certain message in order for an update handler to become | ||
| eligible. | ||
|
|
||
| Here are some examples of using the filters and handlers: | ||
|
|
||
| | update_type | filters | return types | function argument | | ||
| |-----------------------|----------------------------------------------|---------------------|-------------------| | ||
| | `message` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | | ||
| | `message_edited` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | | ||
| | `channel_post` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | | ||
| | `edited_channel_post` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | | ||
| | `inline_query` | `regexp`, `func` | `InlineQuery` | `query` | | ||
| | `chosen_inline_query` | `regexp`, `func` | `ChosenInlineQuery` | `query` | | ||
| | `callback_query` | `regexp`, `func` | `CallbackQuery` | `query` | | ||
| | `shipping_query` | `regexp`, `func` | `ShippingQuery` | `query` | | ||
| | `per_checkout_query` | `regexp`, `func` | `PreCheckoutQuery` | `query` | | ||
| | `poll` | `regexp`, `func` | `Poll` | `poll` | | ||
| | `poll_answer` | `regexp`, `func` | `PollAnswer` | `poll` | | ||
| | `my_chat_member` | `regexp`, `func` | `ChatMemberUpdated` | `member` | | ||
| | `chat_member` | `regexp`, `func` | `ChatMemberUpdated` | `member` | | ||
| | `chat_join_request` | `regexp`, `func` | `ChatJoinRequest` | `member` | | ||
|
|
||
| A message handler is declared in the following way: | ||
|
|
||
| ```python | ||
| import tgbotapi | ||
|
|
||
| bot = tgbotapi.Bot(based_url="https://api.telegram.org/bot"+ "BOT_TOKEN") | ||
| bot = tgbotapi.Bot(access_token="TOKEN") | ||
|
|
||
| @bot.update_handler(update_type='message', bot_command=['start', 'help']) | ||
| def send_welcome(msg): | ||
| bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, | ||
| disable_web_page_preview=False, disable_notification=False, reply_to_message_id=msg.message_id, | ||
| allow_sending_without_reply=True, reply_markup=None) | ||
|
|
||
| @bot.update_handler(update_type='message') # filters | ||
| def function_name(message): | ||
| bot.send_message(chat_id=message.chat.uid, text="This is a message handler") | ||
| ``` | ||
|
|
||
| @bot.update_handler(update_type='message', func=lambda message: message.text) | ||
| def echo_all(msg): | ||
| bot.send_message(chat_id=msg.chat.uid, text=msg.text, parse_mode=None, entities=None, | ||
| disable_web_page_preview=False, disable_notification=False, reply_to_message_id=None, | ||
| allow_sending_without_reply=True, reply_markup=None) | ||
| `function_name` is not bound to any restrictions. Any function name is permitted with update handlers. The function must | ||
| accept at most one argument, which will be the message that the function must handle. | ||
|
|
||
| `filters` is a list of keyword arguments. A filter is declared in the following manner: `name=argument`. One handler may | ||
| have multiple filters. | ||
|
|
||
| bot.polling() | ||
| ``` | ||
| To start the bot, simply open up a terminal and enter `python echo_bot.py` to run the bot! Test it by sending commands ('/start' and '/help') and arbitrary text messages. | ||
| Bot supports the following filters: | ||
|
|
||
| ### ChangeLog | ||
| **_version 5.7_** | ||
| Added support for Video Stickers. | ||
| Added the field is_video to the classes Sticker and StickerSet. | ||
| Added the parameter webm_sticker to the methods createNewStickerSet and addStickerToSet. | ||
| | name | argument(s) | Condition | | ||
| |:-----------:|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | ||
| | update_type | list of strings or string (default `['message']`) | `True` if `update.message` is present. | | ||
| | chat_type | list of strings or string (`private`, `channel`, `group`, `supergroup`) | `True` if `message.chat.ttype` in `chat_type` | | ||
| | bot_command | list of strings or string (`/start`) | `True` if `message.entities[0].bot_command` and `message.text` starts with a command | | ||
| | regex | a regular expression as a string | `True` if `re.search(regexp_arg)` returns `True` | | ||
| | func | a function (lambda or function reference) | `True` if the lambda or function reference returns `True` | | ||
|
|
||
| **_Fixes_** | ||
| - No Issues until Now | ||
|
|
||
| ### Guide | ||
| For more explanation goto [Wiki Tab](https://github.com/MA24th/tgbotapi/wiki). | ||
|
|
||
| `Logging` You can use the tgbotapi module logger to log debug info about Bot. | ||
|
|
||
| It is possible to add custom logging Handlers to the logger, | ||
| Refer to the [Python logging](https://docs.python.org/3/library/logging.html) for more info. | ||
|
|
||
| ```python | ||
| import logging | ||
| from tgbotapi import logger | ||
|
|
||
| logger.setLevel(logging.DEBUG) # Outputs debug messages to console. | ||
| ``` | ||
|
|
||
| ## How to Contribute | ||
| - You must follow [Contributing](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CONTRIBUTING.md) Guidelines. | ||
| - We are committed to providing a friendly community, for more experience read [Code Of Conduct](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CODE_OF_CONDUCT.md). | ||
|
|
||
| - You must follow [Contributing](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CONTRIBUTING.md) | ||
| Guidelines. | ||
| - We are committed to providing a friendly community, for more experience | ||
| read [Code Of Conduct](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CODE_OF_CONDUCT.md). | ||
|
|
||
| ## How to Communicate | ||
| You're welcome to drop in and ask questions, | ||
| discuss bugs and such, Check [Communication](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/COMMUNICATION.md) Methods. | ||
|
|
||
| You're welcome to drop in and ask questions, discuss bugs and such, | ||
| Check [Communication](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/COMMUNICATION.md) Methods. | ||
|
|
||
| ## Frequently Asked Questions | ||
| - How can I distinguish a User and a GroupChat in message.chat? | ||
| >Telegram Bot API supports new type Chat for message.chat. | ||
| Check the ```ttype``` attribute in ```Chat``` object: | ||
| ```python | ||
| if message.chat.ttype == "private": | ||
| # private chat message | ||
|
|
||
| if message.chat.ttype == "group": | ||
| # group chat message | ||
| - How can I distinguish a User and a GroupChat in Message Chat? | ||
|
|
||
| > Telegram Bot API supports type Chat for message Check the ```ttype``` attribute in ```Chat``` object | ||
| if message.chat.ttype == "supergroup": | ||
| # supergroup chat message | ||
| ``` | ||
| ## Attribution | ||
| These Documents are adapted for [MA24th Open Source Software](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/), | ||
| For more information [contact me](mailto:ma24th@yahoo.com) with any additional questions or comments. | ||
|
|
||
| ## Support | ||
| Join our channel on [](https://t.me/GuardBotc) | ||
| and [](https://discord.gg/g65AqbPK6g) . | ||
| These Documents are adapted | ||
| for [MA24th Open Source Software](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/), | ||
|
|
||
| For more information [Contact](mailto:ma24th@yahoo.com) with any additional questions or comments. |