Merge pull request #1409 from Badiboy/master

Bugfix in send_data

.github/workflows/setup_python.yml

@@ -0,0 +1,35 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Setup
+
+# Controls when the action will run. 
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  #workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  all-setups:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.6','3.7','3.8','3.9', 'pypy-3.6', 'pypy-3.7' ] #'pypy-3.8', 'pypy-3.9' NOT SUPPORTED NOW
+    name: ${{ matrix.python-version }} and tests
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+      - run: |
+          pip3 install -r requirements.txt
+          python setup.py install
+          cd tests && py.test

.gitignore

@@ -25,6 +25,7 @@ var/
 
 .idea/
 venv/
+.venv/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -58,4 +59,8 @@ docs/_build/
 
 # PyBuilder
 target/
-testMain.py
+testMain.py
+
+#VS Code
+.vscode/
+.DS_Store

.travis.yml

@@ -1,11 +1,9 @@
 language: python
 python:
-    - "2.6"
-    - "2.7"
-    - "3.3"
-    - "3.4"
-    - "3.5"
-    - "pypy"
+    - "3.7"
+    - "3.8"
+    - "3.9"
+    - "3.10"
     - "pypy3"
 install: "pip install -r requirements.txt"
 script:

README.md

@@ -1,11 +1,19 @@
+
+[![PyPi Package Version](https://img.shields.io/pypi/v/pyTelegramBotAPI.svg)](https://pypi.python.org/pypi/pyTelegramBotAPI)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pyTelegramBotAPI.svg)](https://pypi.python.org/pypi/pyTelegramBotAPI)
+[![Build Status](https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master)](https://travis-ci.org/eternnoir/pyTelegramBotAPI)
+[![PyPi downloads](https://img.shields.io/pypi/dm/pyTelegramBotAPI.svg)](https://pypi.org/project/pyTelegramBotAPI/)
+
 # <p align="center">pyTelegramBotAPI
 
-<p align="center">A simple, but extensible Python implementation for the [Telegram Bot API](https://core.telegram.org/bots/api).
+<p align="center">A simple, but extensible Python implementation for the <a href="https://core.telegram.org/bots/api">Telegram Bot API</a>.</p>
+<p align="center">Supports both sync and async ways.</p>
 
-[![Download Month](https://img.shields.io/pypi/v/pyTelegramBotAPI.svg)](https://pypi.python.org/pypi/pyTelegramBotAPI)
-[![Build Status](https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master)](https://travis-ci.org/eternnoir/pyTelegramBotAPI)
+## <p align="center">Supporting Bot API version: <a href="https://core.telegram.org/bots/api#december-30-2021">5.6</a>!
 
-  * [Getting started.](#getting-started)
+## Contents
+
+  * [Getting started](#getting-started)
   * [Writing your first bot](#writing-your-first-bot)
     * [Prerequisites](#prerequisites)
     * [A simple echo bot](#a-simple-echo-bot)
@@ -14,27 +22,49 @@
     * [Methods](#methods)
     * [General use of the API](#general-use-of-the-api)
       * [Message handlers](#message-handlers)
+      * [Edited Message handler](#edited-message-handler)
+      * [Channel Post handler](#channel-post-handler)
+      * [Edited Channel Post handler](#edited-channel-post-handler)
       * [Callback Query handlers](#callback-query-handler)
+      * [Shipping Query Handler](#shipping-query-handler)
+      * [Pre Checkout Query Handler](#pre-checkout-query-handler)
+      * [Poll Handler](#poll-handler)
+      * [Poll Answer Handler](#poll-answer-handler)
+      * [My Chat Member Handler](#my-chat-member-handler)
+      * [Chat Member Handler](#chat-member-handler)
+      * [Chat Join request handler](#chat-join-request-handler)
+    * [Inline Mode](#inline-mode)
+      * [Inline handler](#inline-handler)
+      * [Chosen Inline handler](#chosen-inline-handler)
+      * [Answer Inline Query](#answer-inline-query)
+    * [Additional API features](#additional-api-features)
+      * [Middleware handlers](#middleware-handlers)
+      * [Custom filters](#custom-filters)
       * [TeleBot](#telebot)
       * [Reply markup](#reply-markup)
-      * [Inline Mode](#inline-mode)
   * [Advanced use of the API](#advanced-use-of-the-api)
-    * [Asynchronous delivery of messages](#asynchronous-delivery-of-messages)
+    * [Using local Bot API Server](#using-local-bot-api-sever)
+    * [Asynchronous TeleBot](#asynchronous-telebot)
     * [Sending large text messages](#sending-large-text-messages)
     * [Controlling the amount of Threads used by TeleBot](#controlling-the-amount-of-threads-used-by-telebot)
     * [The listener mechanism](#the-listener-mechanism)
     * [Using web hooks](#using-web-hooks)
     * [Logging](#logging)
+    * [Proxy](#proxy)
+    * [Testing](#testing)
+  * [API conformance](#api-conformance)
+  * [AsyncTeleBot](#asynctelebot)
   * [F.A.Q.](#faq)
-    * [Bot 2.0](#bot-20)
     * [How can I distinguish a User and a GroupChat in message.chat?](#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat)
+    * [How can I handle reocurring ConnectionResetErrors?](#how-can-i-handle-reocurring-connectionreseterrors)
   * [The Telegram Chat Group](#the-telegram-chat-group)
+  * [Telegram Channel](#telegram-channel)
   * [More examples](#more-examples)
   * [Bots using this API](#bots-using-this-api)
 
-## Getting started.
+## Getting started
 
-This API is tested with Python 2.6, Python 2.7, Python 3.4, Pypy and Pypy 3.
+This API is tested with Python 3.6-3.10 and Pypy 3.
 There are two ways to install the library:
 
 * Installation using pip (a Python package manager)*:
@@ -70,7 +100,7 @@ Then, open the file and create an instance of the TeleBot class.
 ```python
 import telebot
 
-bot = telebot.TeleBot("TOKEN")
+bot = telebot.TeleBot("TOKEN", parse_mode=None) # You can set parse_mode by default. HTML or MARKDOWN
 ```
 *Note: Make sure to actually replace TOKEN with your own API token.*
 
@@ -96,13 +126,13 @@ This one echoes all incoming text messages back to the sender. It uses a lambda
 
 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
-bot.polling()
+bot.infinity_polling()
 ```
 Alright, that's it! Our source file now looks like this:
 ```python
 import telebot
 
-bot = telebot.TeleBot("TOKEN")
+bot = telebot.TeleBot("YOUR_BOT_TOKEN")
 
 @bot.message_handler(commands=['start', 'help'])
 def send_welcome(message):
@@ -112,7 +142,7 @@ def send_welcome(message):
 def echo_all(message):
 	bot.reply_to(message, message.text)
 
-bot.polling()
+bot.infinity_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.
 
@@ -123,7 +153,11 @@ To start the bot, simply open up a terminal and enter `python echo_bot.py` to ru
 All types are defined in types.py. They are all completely in line with the [Telegram API's definition of the types](https://core.telegram.org/bots/api#available-types), except for the Message's `from` field, which is renamed to `from_user` (because `from` is a Python reserved token). Thus, attributes such as `message_id` can be accessed directly with `message.message_id`. Note that `message.chat` can be either an instance of `User` or `GroupChat` (see [How can I distinguish a User and a GroupChat in message.chat?](#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat)).
 
 The Message object also has a `content_type`attribute, which defines the type of the Message. `content_type` can be one of the following strings:
-`text`, `audio`, `document`, `photo`, `sticker`, `video`, `voice`, `location`, `contact`, `new_chat_member`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`, `supergroup_chat_created`, `channel_chat_created`, `migrate_to_chat_id`, `migrate_from_chat_id`, `pinned_message`.
+`text`, `audio`, `document`, `photo`, `sticker`, `video`, `video_note`, `voice`, `location`, `contact`, `new_chat_members`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`, `supergroup_chat_created`, `channel_chat_created`, `migrate_to_chat_id`, `migrate_from_chat_id`, `pinned_message`.
+
+You can use some types in one function. Example:
+
+```content_types=["text", "sticker", "pinned_message", "photo", "audio"]```
 
 ### Methods
 
@@ -135,7 +169,7 @@ Outlined below are some general use cases of the API.
 
 #### Message handlers
 A message handler is a function that is decorated with the `message_handler` decorator of a TeleBot instance. Message handlers consist of one or multiple filters.
-Each filter much return True for a certain message in order for a message handler to become eligible to handle that message. A message handler is declared in the following way (provided `bot` is an instance of TeleBot):
+Each filter must return True for a certain message in order for a message handler to become eligible to handle that message. A message handler is declared in the following way (provided `bot` is an instance of TeleBot):
 ```python
 @bot.message_handler(filters)
 def function_name(message):
@@ -149,10 +183,11 @@ TeleBot supports the following filters:
 |name|argument(s)|Condition|
 |:---:|---| ---|
 |content_types|list of strings (default `['text']`)|`True` if message.content_type is in the list of strings.|
-|regexp|a regular expression as a string|`True` if `re.search(regexp_arg)` returns `True` and `message.content_type == 'text'` (See [Python Regular Expressions](https://docs.python.org/2/library/re.html)|
+|regexp|a regular expression as a string|`True` if `re.search(regexp_arg)` returns `True` and `message.content_type == 'text'` (See [Python Regular Expressions](https://docs.python.org/2/library/re.html))|
 |commands|list of strings|`True` if `message.content_type == 'text'` and `message.text` starts with a command that is in the list of strings.|
-|func|a function (lambda or function reference)|`True` if the lambda or function reference returns `True`
-
+|chat_types|list of chat types|`True` if `message.chat.type` in your filter|
+|func|a function (lambda or function reference)|`True` if the lambda or function reference returns `True`|
+	
 Here are some examples of using the filters and message handlers:
 
 ```python
@@ -174,17 +209,17 @@ def handle_docs_audio(message):
 def handle_message(message):
 	pass
 
-#Handles all messages for which the lambda returns True
+# Handles all messages for which the lambda returns True
 @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', content_types=['document'])
 def handle_text_doc(message):
 	pass
 
-#Which could also be defined as:
+# Which could also be defined as:
 def test_message(message):
-	return message.document.mime_type == 'text/plan'
+	return message.document.mime_type == 'text/plain'
 
 @bot.message_handler(func=test_message, content_types=['document'])
-def handle_text_doc(message)
+def handle_text_doc(message):
 	pass
 
 # Handlers can be stacked to create a function which will be called if either message_handler is eligible
@@ -196,19 +231,156 @@ def send_something(message):
 ```
 **Important: all handlers are tested in the order in which they were declared**
 
-#### Edited Message handlers
+#### Edited Message handler
+Handle edited messages
+`@bot.edited_message_handler(filters) # <- passes a Message type object to your function`
 
-Same as Message handlers
+#### Channel Post handler
+Handle channel post messages
+`@bot.channel_post_handler(filters) # <- passes a Message type object to your function`
+
+#### Edited Channel Post handler
+Handle edited channel post messages
+`@bot.edited_channel_post_handler(filters) # <- passes a Message type object to your function`
 
 #### Callback Query Handler
-
-In bot2.0 update. You can get `callback_query` in update object. In telebot use `callback_query_handler` to process callback_querys.
-
+Handle callback queries
 ```python
 @bot.callback_query_handler(func=lambda call: True)
-def  test_callback(call):
+def test_callback(call): # <- passes a CallbackQuery type object to your function
     logger.info(call)
-``` 
+```
+
+#### Shipping Query Handler
+Handle shipping queries
+`@bot.shipping_query_handeler() # <- passes a ShippingQuery type object to your function`
+
+#### Pre Checkout Query Handler
+Handle pre checkoupt queries
+`@bot.pre_checkout_query_handler() # <- passes a PreCheckoutQuery type object to your function`
+
+#### Poll Handler
+Handle poll updates
+`@bot.poll_handler() # <- passes a Poll type object to your function`
+
+#### Poll Answer Handler
+Handle poll answers
+`@bot.poll_answer_handler() # <- passes a PollAnswer type object to your function`
+
+#### My Chat Member Handler
+Handle updates of a the bot's member status in a chat
+`@bot.my_chat_member_handler() # <- passes a ChatMemberUpdated type object to your function`
+
+#### Chat Member Handler
+Handle updates of a chat member's status in a chat
+`@bot.chat_member_handler() # <- passes a ChatMemberUpdated type object to your function`
+*Note: "chat_member" updates are not requested by default. If you want to allow all update types, set `allowed_updates` in `bot.polling()` / `bot.infinity_polling()` to `util.update_types`*
+
+#### Chat Join Request Handler	
+Handle chat join requests using:
+`@bot.chat_join_request_handler() # <- passes ChatInviteLink type object to your function`
+
+### Inline Mode
+
+More information about [Inline mode](https://core.telegram.org/bots/inline).
+
+#### Inline handler
+
+Now, you can use inline_handler to get inline queries in telebot.
+
+```python
+
+@bot.inline_handler(lambda query: query.query == 'text')
+def query_text(inline_query):
+    # Query message is text
+```
+
+#### Chosen Inline handler
+
+Use chosen_inline_handler to get chosen_inline_result in telebot. Don't forgot add the /setinlinefeedback
+command for @Botfather.
+
+More information : [collecting-feedback](https://core.telegram.org/bots/inline#collecting-feedback)
+
+```python
+@bot.chosen_inline_handler(func=lambda chosen_inline_result: True)
+def test_chosen(chosen_inline_result):
+    # Process all chosen_inline_result.
+```
+
+#### Answer Inline Query
+
+```python
+@bot.inline_handler(lambda query: query.query == 'text')
+def query_text(inline_query):
+    try:
+        r = types.InlineQueryResultArticle('1', 'Result', types.InputTextMessageContent('Result message.'))
+        r2 = types.InlineQueryResultArticle('2', 'Result2', types.InputTextMessageContent('Result message2.'))
+        bot.answer_inline_query(inline_query.id, [r, r2])
+    except Exception as e:
+        print(e)
+
+```
+
+### Additional API features
+
+#### Middleware Handlers
+
+A middleware handler is a function that allows you to modify requests or the bot context as they pass through the 
+Telegram to the bot. You can imagine middleware as a chain of logic connection handled before any other handlers are
+executed. Middleware processing is disabled by default, enable it by setting `apihelper.ENABLE_MIDDLEWARE = True`. 
+
+```python
+apihelper.ENABLE_MIDDLEWARE = True
+
+@bot.middleware_handler(update_types=['message'])
+def modify_message(bot_instance, message):
+    # modifying the message before it reaches any other handler 
+    message.another_text = message.text + ':changed'
+
+@bot.message_handler(commands=['start'])
+def start(message):
+    # the message is already modified when it reaches message handler
+    assert message.another_text == message.text + ':changed'
+```
+There are other examples using middleware handler in the [examples/middleware](examples/middleware) directory.
+	
+	
+#### Custom filters
+Also, you can use built-in custom filters. Or, you can create your own filter.	
+
+[Example of custom filter](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/custom_filters/general_custom_filters.py)
+	
+Also, we have examples on them. Check this links:
+	
+You can check some built-in filters in source [code](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/telebot/custom_filters.py)
+	
+Example of [filtering by id](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/custom_filters/id_filter_example.py)
+	
+Example of [filtering by text](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/custom_filters/text_filter_example.py)
+	
+If you want to add some built-in filter, you are welcome to add it in custom_filters.py file.
+	
+Here is example of creating filter-class:
+	
+```python
+class IsAdmin(telebot.custom_filters.SimpleCustomFilter):
+    # Class will check whether the user is admin or creator in group or not
+    key='is_admin'
+    @staticmethod
+    def check(message: telebot.types.Message):
+        return bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator']
+	
+# To register filter, you need to use method add_custom_filter.
+bot.add_custom_filter(IsAdmin())
+	
+# Now, you can use it in handler.
+@bot.message_handler(is_admin=True)
+def admin_of_group(message):
+	bot.send_message(message.chat.id, 'You are admin of this group!')
+
+```
+	
 
 #### TeleBot
 ```python
@@ -218,11 +390,10 @@ TOKEN = '<token_string>'
 tb = telebot.TeleBot(TOKEN)	#create a new Telegram Bot object
 
 # Upon calling this function, TeleBot starts polling the Telegram servers for new messages.
-# - none_stop: True/False (default False) - Don't stop polling when receiving an error from the Telegram servers
-# - interval: True/False (default False) - The interval between polling requests
-#           Note: Editing this parameter harms the bot's response time
-# - block: True/False (default True) - Blocks upon calling this function
-tb.polling(none_stop=False, interval=0, block=True)
+# - interval: int (default 0) - The interval between polling requests
+# - timeout: integer (default 20) - Timeout in seconds for long polling.
+# - allowed_updates: List of Strings (default None) - List of update types to request 
+tb.infinity_polling(interval=0, timeout=20)
 
 # getMe
 user = tb.get_me()
@@ -234,10 +405,14 @@ tb.remove_webhook()
 
 # getUpdates
 updates = tb.get_updates()
+# or
 updates = tb.get_updates(1234,100,20) #get_Updates(offset, limit, timeout):
 
 # sendMessage
-tb.send_message(chatid, text)
+tb.send_message(chat_id, text)
+
+# editMessageText
+tb.edit_message_text(new_text, chat_id, message_id)
 
 # forwardMessage
 tb.forward_message(to_chat_id, from_chat_id, message_id)
@@ -276,6 +451,11 @@ video = open('/tmp/video.mp4', 'rb')
 tb.send_video(chat_id, video)
 tb.send_video(chat_id, "FILEID")
 
+# sendVideoNote
+videonote = open('/tmp/videonote.mp4', 'rb')
+tb.send_video_note(chat_id, videonote)
+tb.send_video_note(chat_id, "FILEID")
+
 # sendLocation
 tb.send_location(chat_id, lat, lon)
 
@@ -295,7 +475,7 @@ file = requests.get('https://api.telegram.org/file/bot{0}/{1}'.format(API_TOKEN,
 
 ```
 #### Reply markup
-All `send_xyz` functions of TeleBot take an optional `reply_markup` argument. This argument must be an instance of `ReplyKeyboardMarkup`, `ReplyKeyboardHide` or `ForceReply`, which are defined in types.py.
+All `send_xyz` functions of TeleBot take an optional `reply_markup` argument. This argument must be an instance of `ReplyKeyboardMarkup`, `ReplyKeyboardRemove` or `ForceReply`, which are defined in types.py.
 
 ```python
 from telebot import types
@@ -328,12 +508,12 @@ tb.send_message(chat_id, "Choose one letter:", reply_markup=markup)
 ```
 The last example yields this result:
 
-![ReplyKeyboardMarkup](https://pp.vk.me/c624430/v624430512/473e5/_mxxW7FPe4U.jpg "ReplyKeyboardMarkup")
+![ReplyKeyboardMarkup](https://farm3.staticflickr.com/2933/32418726704_9ef76093cf_o_d.jpg "ReplyKeyboardMarkup")
 
 ```python
-# ReplyKeyboardHide: hides a previously sent ReplyKeyboardMarkup
+# ReplyKeyboardRemove: hides a previously sent ReplyKeyboardMarkup
 # Takes an optional selective argument (True/False, default False)
-markup = types.ReplyKeyboardHide(selective=False)
+markup = types.ReplyKeyboardRemove(selective=False)
 tb.send_message(chat_id, message, reply_markup=markup)
 ```
 
@@ -345,52 +525,11 @@ tb.send_message(chat_id, "Send me another word:", reply_markup=markup)
 ```
 ForceReply:
 
-![ForceReply](https://pp.vk.me/c624430/v624430512/473ec/602byyWUHcs.jpg "ForceReply")
-
-### Inline Mode
-
-More information about [Inline mode](https://core.telegram.org/bots/inline).
-
-#### inline_handler
-
-Now, you can use inline_handler to get inline_query in telebot.
-
-```python
-
-@bot.inline_handler(lambda query: query.query == 'text')
-def query_text(inline_query):
-    # Query message is text
-```
+![ForceReply](https://farm4.staticflickr.com/3809/32418726814_d1baec0fc2_o_d.jpg "ForceReply")
 
 
-#### chosen_inline_handler
-
-Use chosen_inline_handler to get chosen_inline_result in telebot. Don't forgot add the /setinlinefeedback
-command for @Botfather.
-
-More information : [collecting-feedback](https://core.telegram.org/bots/inline#collecting-feedback)
-
-```python
-@bot.chosen_inline_handler(func=lambda chosen_inline_result: True)
-def test_chosen(chosen_inline_result):
-    # Process all chosen_inline_result.
-```
-
-#### answer_inline_query
-
-```python
-@bot.inline_handler(lambda query: query.query == 'text')
-def query_text(inline_query):
-    try:
-        r = types.InlineQueryResultArticle('1', 'Result', types.InputTextMessageContent('Result message.'))
-        r2 = types.InlineQueryResultArticle('2', 'Result2', types.InputTextMessageContent('Result message2.'))
-        bot.answer_inline_query(inline_query.id, [r, r2])
-    except Exception as e:
-        print(e)
-
-```
-###Working with entities:
-This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc. 
+### Working with entities
+This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc.
 Attributes:
 * `type`
 * `url`
@@ -407,26 +546,38 @@ Refer [Bot Api](https://core.telegram.org/bots/api#messageentity) for extra deta
 
 ## Advanced use of the API
 
-### Asynchronous delivery of messages
-There exists an implementation of TeleBot which executes all `send_xyz` and the `get_me` functions asynchronously. This can speed up you bot __significantly__, but it has unwanted side effects if used without caution.
+### Using local Bot API Sever
+Since version 5.0 of the Bot API, you have the possibility to run your own [Local Bot API Server](https://core.telegram.org/bots/api#using-a-local-bot-api-server).
+pyTelegramBotAPI also supports this feature.
+```python
+from telebot import apihelper
+
+apihelper.API_URL = "http://localhost:4200/bot{0}/{1}"
+```
+**Important: Like described [here](https://core.telegram.org/bots/api#logout), you have to log out your bot from the Telegram server before switching to your local API server. in pyTelegramBotAPI use `bot.log_out()`**
+
+*Note: 4200 is an example port*
+
+### Asynchronous TeleBot
+New: There is an asynchronous implementation of telebot.
 To enable this behaviour, create an instance of AsyncTeleBot instead of TeleBot.
 ```python
 tb = telebot.AsyncTeleBot("TOKEN")
 ```
-Now, every function that calls the Telegram API is executed in a separate Thread. The functions are modified to return an AsyncTask instance (defined in util.py). Using AsyncTeleBot allows you to do the following:
+Now, every function that calls the Telegram API is executed in a separate asynchronous task.
+Using AsyncTeleBot allows you to do the following:
 ```python
 import telebot
 
 tb = telebot.AsyncTeleBot("TOKEN")
-task = tb.get_me() # Execute an API call
-# Do some other operations...
-a = 0
-for a in range(100):
-	a += 10
 
-result = task.wait() # Get the result of the execution
+@tb.message_handler(commands=['start'])
+async def start_message(message):
+	await bot.send_message(message.chat.id, 'Hello!')
+
 ```
-*Note: if you execute send_xyz functions after eachother without calling wait(), the order in which messages are delivered might be wrong.*
+
+See more in [examples](https://github.com/eternnoir/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot)
 
 ### Sending large text messages
 Sometimes you must send messages that exceed 5000 characters. The Telegram API can not handle that many characters in one request, so we need to split the message in multiples. Here is how to do that using the API:
@@ -437,6 +588,19 @@ large_text = open("large_text.txt", "rb").read()
 # Split the text each 3000 characters.
 # split_string returns a list with the splitted text.
 splitted_text = util.split_string(large_text, 3000)
+
+for text in splitted_text:
+	tb.send_message(chat_id, text)
+```
+
+Or you can use the new `smart_split` function to get more meaningful substrings:
+```python
+from telebot import util
+large_text = open("large_text.txt", "rb").read()
+# Splits one string into multiple strings, with a maximum amount of `chars_per_string` (max. 4096)
+# Splits by last '\n', '. ' or ' ' in exactly this priority.
+# smart_split returns a list with the splitted text.
+splitted_text = util.smart_split(large_text, chars_per_string=3000)
 for text in splitted_text:
 	tb.send_message(chat_id, text)
 ```
@@ -447,7 +611,10 @@ The TeleBot constructor takes the following optional arguments:
    TeleBot should execute message handlers on it's polling Thread.
 
 ### The listener mechanism
-As an alternative to the message handlers, one can also register a function as a listener to TeleBot. Example:
+As an alternative to the message handlers, one can also register a function as a listener to TeleBot.
+
+NOTICE: handlers won't disappear! Your message will be processed both by handlers and listeners. Also, it's impossible to predict which will work at first because of threading. If you use threaded=False, custom listeners will work earlier, after them handlers will be called. 
+Example:
 ```python
 def handle_messages(messages):
 	for message in messages:
@@ -455,16 +622,15 @@ def handle_messages(messages):
 		bot.reply_to(message, 'Hi')
 
 bot.set_update_listener(handle_messages)
-bot.polling()
+bot.infinity_polling()
 ```
 
-### Using webhooks
+### Using web hooks
 When using webhooks telegram sends one Update per call, for processing it you should call process_new_messages([update.message]) when you recieve it.
 
-There are some examples using webhooks in the *examples/webhook_examples* directory.
+There are some examples using webhooks in the [examples/webhook_examples](examples/webhook_examples) directory.
 
 ### Logging
-
 You can use the Telebot module logger to log debug info about Telebot. Use `telebot.logger` to get the logger of the TeleBot module.
 It is possible to add custom logging Handlers to the logger. Refer to the [Python logging module page](https://docs.python.org/2/library/logging.html) for more info.
 
@@ -475,41 +641,153 @@ logger = telebot.logger
 telebot.logger.setLevel(logging.DEBUG) # Outputs debug messages to console.
 ```
 
+### Proxy
+You can use proxy for request. `apihelper.proxy` object will use by call `requests` proxies argument.
+
+```python
+from telebot import apihelper
+
+apihelper.proxy = {'http':'http://127.0.0.1:3128'}
+```
+
+If you want to use socket5 proxy you need install dependency `pip install requests[socks]` and make sure, that you have the latest version of `gunicorn`, `PySocks`, `pyTelegramBotAPI`, `requests` and `urllib3`.
+
+```python
+apihelper.proxy = {'https':'socks5://userproxy:password@proxy_address:port'}
+```
+
+### Testing
+You can disable or change the interaction with real Telegram server by using
+```python
+apihelper.CUSTOM_REQUEST_SENDER = your_handler
+```
+parameter. You can pass there your own function that will be called instead of _requests.request_.
+
+For example:
+```python
+def custom_sender(method, url, **kwargs):
+    print("custom_sender. method: {}, url: {}, params: {}".format(method, url, kwargs.get("params")))
+    result = util.CustomRequestResponse('{"ok":true,"result":{"message_id": 1, "date": 1, "chat": {"id": 1, "type": "private"}}}')
+    return result
+```
+
+Then you can use API and proceed requests in your handler code.
+```python
+apihelper.CUSTOM_REQUEST_SENDER = custom_sender
+tb = TeleBot("test")
+res = tb.send_message(123, "Test")
+```
+
+Result will be:
+
+`custom_sender. method: post, url: https://api.telegram.org/botololo/sendMessage, params: {'chat_id': '123', 'text': 'Test'}`
+
+
+
+## API conformance
+
+* ✔ [Bot API 5.6](https://core.telegram.org/bots/api#december-30-2021)
+* ✔ [Bot API 5.5](https://core.telegram.org/bots/api#december-7-2021)
+* ✔ [Bot API 5.4](https://core.telegram.org/bots/api#november-5-2021)
+* ➕ [Bot API 5.3](https://core.telegram.org/bots/api#june-25-2021) - ChatMember* classes are full copies of ChatMember
+* ✔ [Bot API 5.2](https://core.telegram.org/bots/api#april-26-2021)
+* ✔ [Bot API 5.1](https://core.telegram.org/bots/api#march-9-2021)
+* ✔ [Bot API 5.0](https://core.telegram.org/bots/api-changelog#november-4-2020)
+* ✔ [Bot API 4.9](https://core.telegram.org/bots/api-changelog#june-4-2020)
+* ✔ [Bot API 4.8](https://core.telegram.org/bots/api-changelog#april-24-2020)
+* ✔ [Bot API 4.7](https://core.telegram.org/bots/api-changelog#march-30-2020)
+* ✔ [Bot API 4.6](https://core.telegram.org/bots/api-changelog#january-23-2020)
+* ➕ [Bot API 4.5](https://core.telegram.org/bots/api-changelog#december-31-2019) - No nested MessageEntities and Markdown2 support
+* ✔ [Bot API 4.4](https://core.telegram.org/bots/api-changelog#july-29-2019)
+* ✔ [Bot API 4.3](https://core.telegram.org/bots/api-changelog#may-31-2019)
+* ✔ [Bot API 4.2](https://core.telegram.org/bots/api-changelog#april-14-2019)
+* ➕ [Bot API 4.1](https://core.telegram.org/bots/api-changelog#august-27-2018) - No Passport support
+* ➕ [Bot API 4.0](https://core.telegram.org/bots/api-changelog#july-26-2018)   - No Passport support
+
+
+## AsyncTeleBot
+### Asynchronous version of telebot
+We have a fully asynchronous version of TeleBot.
+This class is not controlled by threads. Asyncio tasks are created to execute all the stuff.
+
+### EchoBot
+Echo Bot example on AsyncTeleBot:
+	
+```python
+# This is a simple echo bot using the decorator mechanism.
+# It echoes any incoming text messages.
+
+from telebot.async_telebot import AsyncTeleBot
+import asyncio
+bot = AsyncTeleBot('TOKEN')
+
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message, """\
+Hi there, I am EchoBot.
+I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
+""")
+
+
+# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
+@bot.message_handler(func=lambda message: True)
+async def echo_message(message):
+    await bot.reply_to(message, message.text)
+
+
+asyncio.run(bot.polling())
+```
+As you can see here, keywords are await and async. 
+	
+### Why should I use async?
+Asynchronous tasks depend on processor performance. Many asynchronous tasks can run parallelly, while thread tasks will block each other.
+
+### Differences in AsyncTeleBot
+AsyncTeleBot has different middlewares. See example on [middlewares](https://github.com/coder2020official/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot/middleware)
+	
+### Examples
+See more examples in our [examples](https://github.com/coder2020official/pyTelegramBotAPI/tree/master/examples/asynchronous_telebot) folder
+	
+
 ## F.A.Q.
 
-### Bot 2.0
-
-April 9,2016 Telegram release new bot 2.0 API, which has a drastic revision especially for the change of method's interface.If you want to update to the latest version, please make sure you've switched bot's code to bot 2.0 method interface.
-
-[More information about pyTelegramBotAPI support bot2.0](https://github.com/eternnoir/pyTelegramBotAPI/issues/130)
-
 ### How can I distinguish a User and a GroupChat in message.chat?
 Telegram Bot API support new type Chat for message.chat.
 
 - Check the ```type``` attribute in ```Chat``` object:
-- 
+-
 ```python
-if message.chat.type == “private”:
-	# private chat message
+if message.chat.type == "private":
+    # private chat message
 
-if message.chat.type == “group”:
+if message.chat.type == "group":
 	# group chat message
-	
-if message.chat.type == “supergroup”:
+
+if message.chat.type == "supergroup":
 	# supergroup chat message
 
-if message.chat.type == “channel”:
+if message.chat.type == "channel":
 	# channel message
 
 ```
 
+### How can I handle reocurring ConnectionResetErrors?
+
+Bot instances that were idle for a long time might be rejected by the server when sending a message due to a timeout of the last used session. Add `apihelper.SESSION_TIME_TO_LIVE = 5 * 60` to your initialisation to force recreation after 5 minutes without any activity. 
+
 ## The Telegram Chat Group
 
 Get help. Discuss. Chat.
 
 * Join the [pyTelegramBotAPI Telegram Chat Group](https://telegram.me/joinchat/Bn4ixj84FIZVkwhk2jag6A)
-* We now have a Telegram Channel as well! Keep yourself up to date with API changes, and [join it](https://telegram.me/pytelegrambotapi).
+	
+## Telegram Channel
 
+Join the [News channel](https://t.me/pyTelegramBotAPI). Here we will post releases and updates.
+	
 ## More examples
 
 * [Echo Bot](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/echo_bot.py)
@@ -519,18 +797,51 @@ Get help. Discuss. Chat.
 ## Bots using this API
 * [SiteAlert bot](https://telegram.me/SiteAlert_bot) ([source](https://github.com/ilteoood/SiteAlert-Python)) by *ilteoood* - Monitors websites and sends a notification on changes
 * [TelegramLoggingBot](https://github.com/aRandomStranger/TelegramLoggingBot) by *aRandomStranger*
-* [Send to Kindle Bot](https://telegram.me/Send2KindleBot) by *GabrielRF* - Send to Kindle files or links to files.
-* [Telegram LMGTFY_bot](https://github.com/GabrielRF/telegram-lmgtfy_bot) ([source](https://github.com/GabrielRF/telegram-lmgtfy_bot)) by *GabrielRF* - Let me Google that for you.
-* [Telegram UrlProBot](https://github.com/GabrielRF/telegram-urlprobot) ([source](https://github.com/GabrielRF/telegram-urlprobot)) by *GabrielRF* - URL shortener and URL expander.
-* [Telegram Proxy Bot](https://bitbucket.org/master_groosha/telegram-proxy-bot) by *Groosha* - A simple BITM (bot-in-the-middle) for Telegram acting as some kind of "proxy".
-* [Telegram Proxy Bot](https://github.com/mrgigabyte/proxybot) by *mrgigabyte* - `Credits for the original version of this bot goes to` **Groosha** `, simply added certain features which I thought were needed`.
+* [Telegram LMGTFY_bot](https://github.com/GabrielRF/telegram-lmgtfy_bot) by *GabrielRF* - Let me Google that for you.
+* [Telegram Proxy Bot](https://github.com/mrgigabyte/proxybot) by *mrgigabyte* 
 * [RadRetroRobot](https://github.com/Tronikart/RadRetroRobot) by *Tronikart* - Multifunctional Telegram Bot RadRetroRobot.
-* [League of Legends bot](https://telegram.me/League_of_Legends_bot) ([source](https://github.com/i32ropie/lol)) by *i32ropie* 
-* [NeoBot](https://github.com/neoranger/NeoBot) by *neoranger*
-* [TagAlertBot](https://github.com/pitasi/TagAlertBot) by *pitasi*
+* [League of Legends bot](https://telegram.me/League_of_Legends_bot) ([source](https://github.com/i32ropie/lol)) by *i32ropie*
+* [NeoBot](https://github.com/neoranger/NeoBot) by [@NeoRanger](https://github.com/neoranger)
+* [ColorCodeBot](https://t.me/colorcodebot) ([source](https://github.com/andydecleyre/colorcodebot)) - Share code snippets as beautifully syntax-highlighted HTML and/or images.
 * [ComedoresUGRbot](http://telegram.me/ComedoresUGRbot) ([source](https://github.com/alejandrocq/ComedoresUGRbot)) by [*alejandrocq*](https://github.com/alejandrocq) - Telegram bot to check the menu of Universidad de Granada dining hall.
-* [picpingbot](https://web.telegram.org/#/im?p=%40picpingbot) - Fun anonymous photo exchange by Boogie Muffin.
-* [TheZigZagProject](https://github.com/WebShark025/TheZigZagProject) - The 'All In One' bot for Telegram! by WebShark025
 * [proxybot](https://github.com/p-hash/proxybot) - Simple Proxy Bot for Telegram. by p-hash
-
-Want to have your bot listed here? Send a Telegram message to @eternnoir or @pevdh.
+* [DonantesMalagaBot](https://github.com/vfranch/DonantesMalagaBot) - DonantesMalagaBot facilitates information to Malaga blood donors about the places where they can donate today or in the incoming days. It also records the date of the last donation so that it helps the donors to know when they can donate again. - by vfranch
+* [DuttyBot](https://github.com/DmytryiStriletskyi/DuttyBot) by *Dmytryi Striletskyi* - Timetable for one university in Kiev.
+* [wat-bridge](https://github.com/rmed/wat-bridge) by [*rmed*](https://github.com/rmed) - Send and receive messages to/from WhatsApp through Telegram
+* [filmratingbot](http://t.me/filmratingbot)([source](https://github.com/jcolladosp/film-rating-bot)) by [*jcolladosp*](https://github.com/jcolladosp) - Telegram bot using the Python API that gets films rating from IMDb and metacritic
+* [Send2Kindlebot](http://t.me/Send2KindleBot) ([source](https://github.com/GabrielRF/Send2KindleBot)) by *GabrielRF* - Send to Kindle service.
+* [RastreioBot](http://t.me/RastreioBot) ([source](https://github.com/GabrielRF/RastreioBot)) by *GabrielRF* - Bot used to track packages on the Brazilian Mail Service.
+* [Spbu4UBot](http://t.me/Spbu4UBot)([link](https://github.com/EeOneDown/spbu4u)) by *EeOneDown* - Bot with timetables for SPbU students.
+* [SmartySBot](http://t.me/ZDU_bot)([link](https://github.com/0xVK/SmartySBot)) by *0xVK* - Telegram timetable bot, for Zhytomyr Ivan Franko State University students.
+* [LearnIt](https://t.me/LearnItbot)([link](https://github.com/tiagonapoli/LearnIt)) - A Telegram Bot created to help people to memorize other languages’ vocabulary.
+* [Bot-Telegram-Shodan ](https://github.com/rubenleon/Bot-Telegram-Shodan) by [rubenleon](https://github.com/rubenleon)
+* [VigoBusTelegramBot](https://t.me/vigobusbot) ([GitHub](https://github.com/Pythoneiro/VigoBus-TelegramBot)) - Bot that provides buses coming to a certain stop and their remaining time for the city of Vigo (Galicia - Spain)
+* [kaishnik-bot](https://t.me/kaishnik_bot) ([source](https://github.com/airatk/kaishnik-bot)) by *airatk* - bot which shows all the necessary information to KNTRU-KAI students.
+* [Robbie](https://t.me/romdeliverybot) ([source](https://github.com/FacuM/romdeliverybot_support)) by @FacuM - Support Telegram bot for developers and maintainers.
+* [AsadovBot](https://t.me/asadov_bot) ([source](https://github.com/desexcile/BotApi)) by @DesExcile - Сatalog of poems by Eduard Asadov.
+* [thesaurus_com_bot](https://t.me/thesaurus_com_bot) ([source](https://github.com/LeoSvalov/words-i-learn-bot)) by @LeoSvalov - words and synonyms from [dictionary.com](https://www.dictionary.com) and [thesaurus.com](https://www.thesaurus.com) in the telegram.
+* [InfoBot](https://t.me/info2019_bot) ([source](https://github.com/irevenko/info-bot)) by @irevenko - An all-round bot that displays some statistics (weather, time, crypto etc...)
+* [FoodBot](https://t.me/ChensonUz_bot) ([source](https://github.com/Fliego/old_restaurant_telegram_chatbot)) by @Fliego - a simple bot for food ordering
+* [Sporty](https://t.me/SportydBot) ([source](https://github.com/0xnu/sporty)) by @0xnu - Telegram bot for displaying the latest news, sports schedules and injury updates.
+* [JoinGroup Silencer Bot](https://t.me/joingroup_silencer_bot) ([source](https://github.com/zeph1997/Telegram-Group-Silencer-Bot)) by [@zeph1997](https://github.com/zeph1997) - A Telegram Bot to remove "join group" and "removed from group" notifications.
+* [TasksListsBot](https://t.me/TasksListsBot) ([source](https://github.com/Pablo-Davila/TasksListsBot)) by [@Pablo-Davila](https://github.com/Pablo-Davila) - A (tasks) lists manager bot for Telegram.
+* [MyElizaPsychologistBot](https://t.me/TasksListsBot) ([source](https://github.com/Pablo-Davila/MyElizaPsychologistBot)) by [@Pablo-Davila](https://github.com/Pablo-Davila) - An implementation of the famous Eliza psychologist chatbot.
+* [Frcstbot](https://t.me/frcstbot) ([source](https://github.com/Mrsqd/frcstbot_public)) by [Mrsqd](https://github.com/Mrsqd). A Telegram bot that will always be happy to show you the weather forecast.
+* [MineGramBot](https://github.com/ModischFabrications/MineGramBot) by [ModischFabrications](https://github.com/ModischFabrications). This bot can start, stop and monitor a minecraft server.
+* [Tabletop DiceBot](https://github.com/dexpiper/tabletopdicebot) by [dexpiper](https://github.com/dexpiper). This bot can roll multiple dices for RPG-like games, add positive and negative modifiers and show short descriptions to the rolls.
+* [BarnameKon](https://t.me/BarnameKonBot) by [Anvaari](https://github.com/anvaari). This Bot make "Add to google calendar" link for your events. It give information about event and return link. It work for Jalali calendar and in Tehran Time. [Source code](https://github.com/anvaari/BarnameKon)
+* [Translator bot](https://github.com/AREEG94FAHAD/translate_text_bot) by Areeg Fahad. This bot can be used to translate texts. 
+* [Digital Cryptocurrency bot](https://github.com/AREEG94FAHAD/currencies_bot) by Areeg Fahad. With this bot, you can now monitor the prices of more than 12 digital Cryptocurrency. 
+* [Anti-Tracking Bot](https://t.me/AntiTrackingBot) by Leon Heess [(source)](https://github.com/leonheess/AntiTrackingBot). Send any link, and the bot tries its best to remove all tracking from the link you sent.
+* [Developer Bot](https://t.me/IndDeveloper_bot) by [Vishal Singh](https://github.com/vishal2376) [(source code)](https://github.com/vishal2376/telegram-bot) This telegram bot can do tasks like GitHub search & clone,provide c++ learning resources ,Stackoverflow search, Codeforces(profile visualizer,random problems)
+* [oneIPO bot](https://github.com/aaditya2200/IPO-proj) by [Aadithya](https://github.com/aaditya2200) & [Amol Soans](https://github.com/AmolDerickSoans) This Telegram bot provides live updates , data and documents on current and upcoming IPOs(Initial Public Offerings) 
+* [CoronaGraphsBot](https://t.me/CovidGraph_bot) ([source](https://github.com/TrevorWinstral/CoronaGraphsBot)) by *TrevorWinstral* - Gets live COVID Country data, plots it, and briefs the user
+* [ETHLectureBot](https://t.me/ETHLectureBot) ([source](https://github.com/TrevorWinstral/ETHLectureBot)) by *TrevorWinstral* - Notifies ETH students when their lectures have been uploaded
+* [Vlun Finder Bot](https://github.com/resinprotein2333/Vlun-Finder-bot) by [Resinprotein2333](https://github.com/resinprotein2333). This bot can help you to find The information of CVE vulnerabilities.
+* [ETHGasFeeTrackerBot](https://t.me/ETHGasFeeTrackerBot) ([Source](https://github.com/DevAdvik/ETHGasFeeTrackerBot]) by *DevAdvik* - Get Live Ethereum Gas Fees in GWEI
+* [Google Sheet Bot](https://github.com/JoachimStanislaus/Tele_Sheet_bot) by [JoachimStanislaus](https://github.com/JoachimStanislaus). This bot can help you to track your expenses by uploading your bot entries to your google sheet.
+* [GrandQuiz Bot](https://github.com/Carlosma7/TFM-GrandQuiz) by [Carlosma7](https://github.com/Carlosma7). This bot is a trivia game that allows you to play with people from different ages. This project addresses the use of a system through chatbots to carry out a social and intergenerational game as an alternative to traditional game development.
+* [Diccionario de la RAE](https://t.me/dleraebot) ([source](https://github.com/studentenherz/dleraebot)) This bot lets you find difinitions of words in Spanish using [RAE's dictionary](https://dle.rae.es/). It features direct message and inline search.
+* [remoteTelegramShell](https://github.com/EnriqueMoran/remoteTelegramShell) by [EnriqueMoran](https://github.com/EnriqueMoran). Control your LinuxOS computer through Telegram.
+	
+**Want to have your bot listed here? Just make a pull request. Only bots with public source code are accepted.**

README.rst

@@ -1,807 +0,0 @@
-#
-
-.. raw:: html
-
-   <p align="center">
-
-pyTelegramBotAPI
-
-.. raw:: html
-
-   <p align="center">
-
-A simple, but extensible Python implementation for the `Telegram Bot
-API <https://core.telegram.org/bots/api>`__.
-
-|Download Month| |Build Status| |Download Month|
-
--  `Getting started. <#getting-started>`__
--  `Writing your first bot <#writing-your-first-bot>`__
-
-   -  `Prerequisites <#prerequisites>`__
-   -  `A simple echo bot <#a-simple-echo-bot>`__
-
--  `General API Documentation <#general-api-documentation>`__
-
-   -  `Types <#types>`__
-   -  `Methods <#methods>`__
-   -  `General use of the API <#general-use-of-the-api>`__
-   -  `Message handlers <#message-handlers>`__
-   -  `Callback Query handlers <#callback-query-handler>`__
-   -  `TeleBot <#telebot>`__
-   -  `Reply markup <#reply-markup>`__
-   -  `Inline Mode <#inline-mode>`__
-
--  `Advanced use of the API <#advanced-use-of-the-api>`__
-
-   -  `Asynchronous delivery of
-      messages <#asynchronous-delivery-of-messages>`__
-   -  `Sending large text messages <#sending-large-text-messages>`__
-   -  `Controlling the amount of Threads used by
-      TeleBot <#controlling-the-amount-of-threads-used-by-telebot>`__
-   -  `The listener mechanism <#the-listener-mechanism>`__
-   -  `Using web hooks <#using-web-hooks>`__
-   -  `Logging <#logging>`__
-
--  `F.A.Q. <#faq>`__
-
-   -  `Bot 2.0 <#bot-20>`__
-   -  `How can I distinguish a User and a GroupChat in
-      message.chat? <#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat>`__
-
--  `The Telegram Chat Group <#the-telegram-chat-group>`__
--  `More examples <#more-examples>`__
--  `Bots using this API <#bots-using-this-api>`__
-
-Getting started.
-----------------
-
-This API is tested with Python 2.6, Python 2.7, Python 3.4, Pypy and
-Pypy 3. There are two ways to install the library:
-
--  Installation using pip (a Python package manager)\*:
-
-::
-
-    $ pip install pyTelegramBotAPI
-
--  Installation from source (requires git):
-
-::
-
-    $ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
-    $ cd pyTelegramBotAPI
-    $ 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 pytelegrambotapi --upgrade``\ \*
-
-Writing your first bot
-----------------------
-
-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>`__.
-
-A simple echo bot
-~~~~~~~~~~~~~~~~~
-
-The TeleBot 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.
-
-Create a file called ``echo_bot.py``. Then, open the file and create an
-instance of the TeleBot class.
-
-.. code:: python
-
-    import telebot
-
-    bot = telebot.TeleBot("TOKEN")
-
-*Note: Make sure to actually replace TOKEN with your own API 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`` commands.
-
-.. code:: python
-
-    @bot.message_handler(commands=['start', 'help'])
-    def send_welcome(message):
-        bot.reply_to(message, "Howdy, how are you doing?")
-
-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:
-
-.. code:: python
-
-    @bot.message_handler(func=lambda m: True)
-    def echo_all(message):
-        bot.reply_to(message, message.text)
-
-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:
-
-.. code:: python
-
-    bot.polling()
-
-Alright, that's it! Our source file now looks like this:
-
-.. code:: python
-
-    import telebot
-
-    bot = telebot.TeleBot("TOKEN")
-
-    @bot.message_handler(commands=['start', 'help'])
-    def send_welcome(message):
-        bot.reply_to(message, "Howdy, how are you doing?")
-
-    @bot.message_handler(func=lambda message: True)
-    def echo_all(message):
-        bot.reply_to(message, message.text)
-
-    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.
-
-General API Documentation
--------------------------
-
-Types
-~~~~~
-
-All types are defined in types.py. They are all completely in line with
-the `Telegram API's definition of the
-types <https://core.telegram.org/bots/api#available-types>`__, except
-for the Message's ``from`` field, which is renamed to ``from_user``
-(because ``from`` is a Python reserved token). Thus, attributes such as
-``message_id`` can be accessed directly with ``message.message_id``.
-Note that ``message.chat`` can be either an instance of ``User`` or
-``GroupChat`` (see `How can I distinguish a User and a GroupChat in
-message.chat? <#how-can-i-distinguish-a-user-and-a-groupchat-in-messagechat>`__).
-
-The Message object also has a ``content_types``\ attribute, which
-defines the type of the Message. ``content_types`` can be one of the
-following strings: 'text', 'audio', 'document', 'photo', 'sticker',
-'video', 'voice', 'location', 'contact', 'new\_chat\_participant',
-'left\_chat\_participant', 'new\_chat\_title', 'new\_chat\_photo',
-'delete\_chat\_photo', 'group\_chat\_created'.
-
-Methods
-~~~~~~~
-
-All `API
-methods <https://core.telegram.org/bots/api#available-methods>`__ are
-located in the TeleBot class. They are renamed to follow common Python
-naming conventions. E.g. ``getMe`` is renamed to ``get_me`` and
-``sendMessage`` to ``send_message``.
-
-General use of the API
-~~~~~~~~~~~~~~~~~~~~~~
-
-Outlined below are some general use cases of the API.
-
-Message handlers
-^^^^^^^^^^^^^^^^
-
-A message handler is a function that is decorated with the
-``message_handler`` decorator of a TeleBot instance. Message handlers
-consist of one or multiple filters. Each filter much return True for a
-certain message in order for a message handler to become eligible to
-handle that message. A message handler is declared in the following way
-(provided ``bot`` is an instance of TeleBot):
-
-.. code:: python
-
-    @bot.message_handler(filters)
-    def function_name(message):
-        bot.reply_to(message, "This is a message handler")
-
-``function_name`` is not bound to any restrictions. Any function name is
-permitted with message 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. TeleBot supports the following filters:
-
-+--------+------+------+
-| name   | argu | Cond |
-|        | ment | itio |
-|        | (s)  | n    |
-+========+======+======+
-| conten | list | ``Tr |
-| t\_typ | of   | ue`` |
-| es     | stri | if   |
-|        | ngs  | mess |
-|        | (def | age. |
-|        | ault | cont |
-|        | ``[' | ent\ |
-|        | text | _typ |
-|        | ']`` | e    |
-|        | )    | is   |
-|        |      | in   |
-|        |      | the  |
-|        |      | list |
-|        |      | of   |
-|        |      | stri |
-|        |      | ngs. |
-+--------+------+------+
-| regexp | a    | ``Tr |
-|        | regu | ue`` |
-|        | lar  | if   |
-|        | expr | ``re |
-|        | essi | .sea |
-|        | on   | rch( |
-|        | as a | rege |
-|        | stri | xp_a |
-|        | ng   | rg)` |
-|        |      | `    |
-|        |      | retu |
-|        |      | rns  |
-|        |      | ``Tr |
-|        |      | ue`` |
-|        |      | and  |
-|        |      | ``me |
-|        |      | ssag |
-|        |      | e.co |
-|        |      | nten |
-|        |      | t_ty |
-|        |      | pe = |
-|        |      | = 't |
-|        |      | ext' |
-|        |      | ``   |
-|        |      | (See |
-|        |      | `Pyt |
-|        |      | hon  |
-|        |      | Regu |
-|        |      | lar  |
-|        |      | Expr |
-|        |      | essi |
-|        |      | ons  |
-|        |      | <htt |
-|        |      | ps:/ |
-|        |      | /doc |
-|        |      | s.py |
-|        |      | thon |
-|        |      | .org |
-|        |      | /2/l |
-|        |      | ibra |
-|        |      | ry/r |
-|        |      | e.ht |
-|        |      | ml>` |
-|        |      | __   |
-+--------+------+------+
-| comman | list | ``Tr |
-| ds     | of   | ue`` |
-|        | stri | if   |
-|        | ngs  | ``me |
-|        |      | ssag |
-|        |      | e.co |
-|        |      | nten |
-|        |      | t_ty |
-|        |      | pe = |
-|        |      | = 't |
-|        |      | ext' |
-|        |      | ``   |
-|        |      | and  |
-|        |      | ``me |
-|        |      | ssag |
-|        |      | e.te |
-|        |      | xt`` |
-|        |      | star |
-|        |      | ts   |
-|        |      | with |
-|        |      | a    |
-|        |      | comm |
-|        |      | and  |
-|        |      | that |
-|        |      | is   |
-|        |      | in   |
-|        |      | the  |
-|        |      | list |
-|        |      | of   |
-|        |      | stri |
-|        |      | ngs. |
-+--------+------+------+
-| func   | a    | ``Tr |
-|        | func | ue`` |
-|        | tion | if   |
-|        | (lam | the  |
-|        | bda  | lamb |
-|        | or   | da   |
-|        | func | or   |
-|        | tion | func |
-|        | refe | tion |
-|        | renc | refe |
-|        | e)   | renc |
-|        |      | e    |
-|        |      | retu |
-|        |      | rns  |
-|        |      | ``Tr |
-|        |      | ue`` |
-+--------+------+------+
-
-Here are some examples of using the filters and message handlers:
-
-.. code:: python
-
-    import telebot
-    bot = telebot.TeleBot("TOKEN")
-
-    # Handles all text messages that contains the commands '/start' or '/help'.
-    @bot.message_handler(commands=['start', 'help'])
-    def handle_start_help(message):
-        pass
-
-    # Handles all sent documents and audio files
-    @bot.message_handler(content_types=['document', 'audio'])
-    def handle_docs_audio(message):
-        pass
-
-    # Handles all text messages that match the regular expression
-    @bot.message_handler(regexp="SOME_REGEXP")
-    def handle_message(message):
-        pass
-
-    #Handles all messages for which the lambda returns True
-    @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', content_types=['document'])
-    def handle_text_doc(message):
-        pass
-
-    #Which could also be defined as:
-    def test_message(message):
-        return message.document.mime_type == 'text/plan'
-
-    @bot.message_handler(func=test_message, content_types=['document'])
-    def handle_text_doc(message)
-        pass
-
-    # Handlers can be stacked to create a function which will be called if either message_handler is eligible
-    # This handler will be called if the message starts with '/hello' OR is some emoji
-    @bot.message_handler(commands=['hello'])
-    @bot.message_handler(func=lambda msg: msg.text.encode("utf-8") == SOME_FANCY_EMOJI)
-    def send_something(message):
-        pass
-
-**Important: all handlers are tested in the order in which they were
-declared**
-
-Callback Query Handler
-^^^^^^^^^^^^^^^^^^^^^^
-
-In bot2.0 update. You can get ``callback_query`` in update object. In
-telebot use ``callback_query_handler`` to process callback\_querys.
-
-.. code:: python
-
-    @bot.callback_query_handler(func=lambda call: True)
-    def  test_callback(call):
-        logger.info(call)
-
-TeleBot
-^^^^^^^
-
-.. code:: python
-
-    import telebot
-
-    TOKEN = '<token_string>'
-    tb = telebot.TeleBot(TOKEN) #create a new Telegram Bot object
-
-    # Upon calling this function, TeleBot starts polling the Telegram servers for new messages.
-    # - none_stop: True/False (default False) - Don't stop polling when receiving an error from the Telegram servers
-    # - interval: True/False (default False) - The interval between polling requests
-    #           Note: Editing this parameter harms the bot's response time
-    # - block: True/False (default True) - Blocks upon calling this function
-    tb.polling(none_stop=False, interval=0, block=True)
-
-    # getMe
-    user = tb.get_me()
-
-    # setWebhook
-    tb.set_webhook(url="http://example.com", certificate=open('mycert.pem'))
-    # unset webhook
-    tb.remove_webhook()
-
-    # getUpdates
-    updates = tb.get_updates()
-    updates = tb.get_updates(1234,100,20) #get_Updates(offset, limit, timeout):
-
-    # sendMessage
-    tb.send_message(chatid, text)
-
-    # forwardMessage
-    tb.forward_message(to_chat_id, from_chat_id, message_id)
-
-    # All send_xyz functions which can take a file as an argument, can also take a file_id instead of a file.
-    # sendPhoto
-    photo = open('/tmp/photo.png', 'rb')
-    tb.send_photo(chat_id, photo)
-    tb.send_photo(chat_id, "FILEID")
-
-    # sendAudio
-    audio = open('/tmp/audio.mp3', 'rb')
-    tb.send_audio(chat_id, audio)
-    tb.send_audio(chat_id, "FILEID")
-
-    ## sendAudio with duration, performer and title.
-    tb.send_audio(CHAT_ID, file_data, 1, 'eternnoir', 'pyTelegram')
-
-    # sendVoice
-    voice = open('/tmp/voice.ogg', 'rb')
-    tb.send_voice(chat_id, voice)
-    tb.send_voice(chat_id, "FILEID")
-
-    # sendDocument
-    doc = open('/tmp/file.txt', 'rb')
-    tb.send_document(chat_id, doc)
-    tb.send_document(chat_id, "FILEID")
-
-    # sendSticker
-    sti = open('/tmp/sti.webp', 'rb')
-    tb.send_sticker(chat_id, sti)
-    tb.send_sticker(chat_id, "FILEID")
-
-    # sendVideo
-    video = open('/tmp/video.mp4', 'rb')
-    tb.send_video(chat_id, video)
-    tb.send_video(chat_id, "FILEID")
-
-    # sendLocation
-    tb.send_location(chat_id, lat, lon)
-
-    # sendChatAction
-    # action_string can be one of the following strings: 'typing', 'upload_photo', 'record_video', 'upload_video',
-    # 'record_audio', 'upload_audio', 'upload_document' or 'find_location'.
-    tb.send_chat_action(chat_id, action_string)
-
-    # getFile
-    # Downloading a file is straightforward
-    # Returns a File object
-    import requests
-    file_info = tb.get_file(file_id)
-
-    file = requests.get('https://api.telegram.org/file/bot{0}/{1}'.format(API_TOKEN, file_info.file_path))
-
-Reply markup
-^^^^^^^^^^^^
-
-All ``send_xyz`` functions of TeleBot take an optional ``reply_markup``
-argument. This argument must be an instance of ``ReplyKeyboardMarkup``,
-``ReplyKeyboardHide`` or ``ForceReply``, which are defined in types.py.
-
-.. code:: python
-
-    from telebot import types
-
-    # Using the ReplyKeyboardMarkup class
-    # It's constructor can take the following optional arguments:
-    # - resize_keyboard: True/False (default False)
-    # - one_time_keyboard: True/False (default False)
-    # - selective: True/False (default False)
-    # - row_width: integer (default 3)
-    # row_width is used in combination with the add() function.
-    # It defines how many buttons are fit on each row before continuing on the next row.
-    markup = types.ReplyKeyboardMarkup(row_width=2)
-    itembtn1 = types.KeyboardButton('a')
-    itembtn2 = types.KeyboardButton('v')
-    itembtn3 = types.KeyboardButton('d')
-    markup.add(itembtn1, itembtn2, itembtn3)
-    tb.send_message(chat_id, "Choose one letter:", reply_markup=markup)
-
-    # or add strings one row at a time:
-    markup = types.ReplyKeyboardMarkup()
-    itembtna = types.KeyboardButton('a')
-    itembtnv = types.KeyboardButton('v')
-    itembtnc = types.KeyboardButton('c')
-    itembtnd = types.KeyboardButton('d')
-    itembtne = types.KeyboardButton('e')
-    markup.row(itembtna, itembtnv)
-    markup.row(itembtnc, itembtnd, itembtne)
-    tb.send_message(chat_id, "Choose one letter:", reply_markup=markup)
-
-The last example yields this result:
-
-.. figure:: https://pp.vk.me/c624430/v624430512/473e5/_mxxW7FPe4U.jpg
-   :alt: ReplyKeyboardMarkup
-
-   ReplyKeyboardMarkup
-
-.. code:: python
-
-    # ReplyKeyboardHide: hides a previously sent ReplyKeyboardMarkup
-    # Takes an optional selective argument (True/False, default False)
-    markup = types.ReplyKeyboardHide(selective=False)
-    tb.send_message(chat_id, message, reply_markup=markup)
-
-.. code:: python
-
-    # ForceReply: forces a user to reply to a message
-    # Takes an optional selective argument (True/False, default False)
-    markup = types.ForceReply(selective=False)
-    tb.send_message(chat_id, "Send me another word:", reply_markup=markup)
-
-ForceReply:
-
-.. figure:: https://pp.vk.me/c624430/v624430512/473ec/602byyWUHcs.jpg
-   :alt: ForceReply
-
-   ForceReply
-
-Inline Mode
-~~~~~~~~~~~
-
-More information about `Inline
-mode <https://core.telegram.org/bots/inline>`__.
-
-inline\_handler
-^^^^^^^^^^^^^^^
-
-Now, you can use inline\_handler to get inline\_query in telebot.
-
-.. code:: python
-
-
-    @bot.inline_handler(lambda query: query.query == 'text')
-    def query_text(inline_query):
-        # Query message is text
-
-chosen\_inline\_handler
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Use chosen\_inline\_handler to get chosen\_inline\_result in telebot.
-Don't forgot add the /setinlinefeedback command for @Botfather.
-
-More information :
-`collecting-feedback <https://core.telegram.org/bots/inline#collecting-feedback>`__
-
-.. code:: python
-
-    @bot.chosen_inline_handler(func=lambda chosen_inline_result: True)
-    def test_chosen(chosen_inline_result):
-        # Process all chosen_inline_result.
-
-answer\_inline\_query
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: python
-
-    @bot.inline_handler(lambda query: query.query == 'text')
-    def query_text(inline_query):
-        try:
-            r = types.InlineQueryResultArticle('1', 'Result', 'Result message.')
-            r2 = types.InlineQueryResultArticle('2', 'Result2', 'Result message2.')
-            bot.answer_inline_query(inline_query.id, [r, r2])
-        except Exception as e:
-            print(e)
-
-Advanced use of the API
------------------------
-
-Asynchronous delivery of messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There exists an implementation of TeleBot which executes all
-``send_xyz`` and the ``get_me`` functions asynchronously. This can speed
-up you bot **significantly**, but it has unwanted side effects if used
-without caution. To enable this behaviour, create an instance of
-AsyncTeleBot instead of TeleBot.
-
-.. code:: python
-
-    tb = telebot.AsyncTeleBot("TOKEN")
-
-Now, every function that calls the Telegram API is executed in a
-separate Thread. The functions are modified to return an AsyncTask
-instance (defined in util.py). Using AsyncTeleBot allows you to do the
-following:
-
-.. code:: python
-
-    import telebot
-
-    tb = telebot.AsyncTeleBot("TOKEN")
-    task = tb.get_me() # Execute an API call
-    # Do some other operations...
-    a = 0
-    for a in range(100):
-        a += 10
-
-    result = task.wait() # Get the result of the execution
-
-*Note: if you execute send\_xyz functions after eachother without
-calling wait(), the order in which messages are delivered might be
-wrong.*
-
-Sending large text messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes you must send messages that exceed 5000 characters. The
-Telegram API can not handle that many characters in one request, so we
-need to split the message in multiples. Here is how to do that using the
-API:
-
-.. code:: python
-
-    from telebot import util
-    large_text = open("large_text.txt", "rb").read()
-
-    # Split the text each 3000 characters.
-    # split_string returns a list with the splitted text.
-    splitted_text = util.split_string(large_text, 3000)
-    for text in splitted_text:
-        tb.send_message(chat_id, text)
-
-Controlling the amount of Threads used by TeleBot
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The TeleBot constructor takes the following optional arguments:
-
--  create\_threads: True/False (default True). A flag to indicate
-   whether TeleBot should execute message handlers on it's polling
-   Thread.
--  num\_threads: integer (default 4). Controls the amount of
-   WorkerThreads created for the internal thread pool that TeleBot uses
-   to execute message handlers. Is not used when create\_threads is
-   False.
-
-The listener mechanism
-~~~~~~~~~~~~~~~~~~~~~~
-
-As an alternative to the message handlers, one can also register a
-function as a listener to TeleBot. Example:
-
-.. code:: python
-
-    def handle_messages(messages):
-        for message in messsages:
-            # Do something with the message
-            bot.reply_to(message, 'Hi')
-
-    bot.set_update_listener(handle_messages)
-    bot.polling()
-
-Using webhooks
-~~~~~~~~~~~~~~
-
-When using webhooks telegram sends one Update per call, for processing
-it you should call process\_new\_messages([update.message]) when you
-recieve it.
-
-There are some examples using webhooks in the
-*examples/webhook\_examples* directory.
-
-Logging
-~~~~~~~
-
-You can use the Telebot module logger to log debug info about Telebot.
-Use ``telebot.logger`` to get the logger of the TeleBot module. It is
-possible to add custom logging Handlers to the logger. Refer to the
-`Python logging module
-page <https://docs.python.org/2/library/logging.html>`__ for more info.
-
-.. code:: python
-
-    import logging
-
-    logger = telebot.logger
-    telebot.logger.setLevel(logging.DEBUG) # Outputs debug messages to console.
-
-F.A.Q.
-------
-
-Bot 2.0
-~~~~~~~
-
-April 9,2016 Telegram release new bot 2.0 API, which has a drastic
-revision especially for the change of method's interface.If you want to
-update to the latest version, please make sure you've switched bot's
-code to bot 2.0 method interface.
-
-`More information about pyTelegramBotAPI support
-bot2.0 <https://github.com/eternnoir/pyTelegramBotAPI/issues/130>`__
-
-How can I distinguish a User and a GroupChat in message.chat?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Telegram Bot API support new type Chat for message.chat.
-
--  Check the ``type`` attribute in ``Chat`` object:
--  \`\`\`python if message.chat.type == “private”: # private chat
-   message
-
-if message.chat.type == “group”: # group chat message
-
-if message.chat.type == “supergroup”: # supergroup chat message
-
-if message.chat.type == “channel”: # channel message
-
-\`\`\`
-
-The Telegram Chat Group
------------------------
-
-Get help. Discuss. Chat.
-
--  Join the pyTelegramBotAPI Telegram Chat Group
--  Messge to @eternnoir by telegram for Invitation.
--  We now have a Telegram Channel as well! Keep yourself up to date with
-   API changes, and `join it <https://telegram.me/pytelegrambotapi>`__.
-
-More examples
--------------
-
--  `Echo
-   Bot <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/echo_bot.py>`__
--  `Deep
-   Linking <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/deep_linking.py>`__
--  `next\_step\_handler
-   Example <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/step_example.py>`__
-
-Bots using this API
--------------------
-
--  `SiteAlert bot <https://telegram.me/SiteAlert_bot>`__
-   (`source <https://github.com/ilteoood/SiteAlert-Python>`__) by
-   *ilteoood* - Monitors websites and sends a notification on changes
--  `TelegramLoggingBot <https://github.com/aRandomStranger/TelegramLoggingBot>`__
-   by *aRandomStranger*
--  `Telegram
-   LMGTFY\_bot <https://github.com/GabrielRF/telegram-lmgtfy_bot>`__ by
-   *GabrielRF*
--  `Telegram
-   UrlProBot <https://github.com/GabrielRF/telegram-urlprobot>`__ by
-   *GabrielRF*
--  `Telegram Proxy
-   Bot <https://bitbucket.org/master_groosha/telegram-proxy-bot>`__ by
-   *Groosha* - A simple BITM (bot-in-the-middle) for Telegram acting as
-   some kind of "proxy".
--  `Telegram Proxy Bot <https://github.com/mrgigabyte/proxybot>`__ by
-   *mrgigabyte* -
-   ``Credits for the original version of this bot goes to`` **Groosha**
-   ``, simply added certain features which I thought were needed``.
--  `RadRetroRobot <https://github.com/Tronikart/RadRetroRobot>`__ by
-   *Tronikart* - Multifunctional Telegram Bot RadRetroRobot.
--  `League of Legends bot <https://telegram.me/League_of_Legends_bot>`__
-   (`source <https://github.com/i32ropie/lol>`__) by *i32ropie*
--  `NeoBot <https://github.com/neoranger/NeoBot>`__ by *neoranger*
--  `TagAlertBot <https://github.com/pitasi/TagAlertBot>`__ by *pitasi*
-
-Want to have your bot listed here? Send a Telegram message to @eternnoir
-or @pevdh.
-
-.. |Download Month| image:: https://img.shields.io/pypi/v/pyTelegramBotAPI.svg
-   :target: https://pypi.python.org/pypi/pyTelegramBotAPI
-.. |Build Status| image:: https://travis-ci.org/eternnoir/pyTelegramBotAPI.svg?branch=master
-   :target: https://travis-ci.org/eternnoir/pyTelegramBotAPI
-.. |Download Month| image:: https://img.shields.io/pypi/dm/pyTelegramBotAPI.svg
-   :target: https://pypi.python.org/pypi/pyTelegramBotAPI

examples/CallbackData_example.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you how to use CallbackData
+"""
+
+from telebot.callback_data import CallbackData, CallbackDataFilter
+from telebot import types, TeleBot
+from telebot.custom_filters import AdvancedCustomFilter
+
+API_TOKEN = ''
+PRODUCTS = [
+    {'id': '0', 'name': 'xiaomi mi 10', 'price': 400},
+    {'id': '1', 'name': 'samsung s20', 'price': 800},
+    {'id': '2', 'name': 'iphone 13', 'price': 1300}
+]
+
+bot = TeleBot(API_TOKEN)
+products_factory = CallbackData('product_id', prefix='products')
+
+
+def products_keyboard():
+    return types.InlineKeyboardMarkup(
+        keyboard=[
+            [
+                types.InlineKeyboardButton(
+                    text=product['name'],
+                    callback_data=products_factory.new(product_id=product["id"])
+                )
+            ]
+            for product in PRODUCTS
+        ]
+    )
+
+
+def back_keyboard():
+    return types.InlineKeyboardMarkup(
+        keyboard=[
+            [
+                types.InlineKeyboardButton(
+                    text='⬅',
+                    callback_data='back'
+                )
+            ]
+        ]
+    )
+
+
+class ProductsCallbackFilter(AdvancedCustomFilter):
+    key = 'config'
+
+    def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+@bot.message_handler(commands=['products'])
+def products_command_handler(message: types.Message):
+    bot.send_message(message.chat.id, 'Products:', reply_markup=products_keyboard())
+
+
+# Only product with field - product_id = 2
+@bot.callback_query_handler(func=None, config=products_factory.filter(product_id='2'))
+def product_one_callback(call: types.CallbackQuery):
+    bot.answer_callback_query(callback_query_id=call.id, text='Not available :(', show_alert=True)
+
+
+# Any other products
+@bot.callback_query_handler(func=None, config=products_factory.filter())
+def products_callback(call: types.CallbackQuery):
+    callback_data: dict = products_factory.parse(callback_data=call.data)
+    product_id = int(callback_data['product_id'])
+    product = PRODUCTS[product_id]
+
+    text = f"Product name: {product['name']}\n" \
+           f"Product price: {product['price']}"
+    bot.edit_message_text(chat_id=call.message.chat.id, message_id=call.message.message_id,
+                          text=text, reply_markup=back_keyboard())
+
+
+@bot.callback_query_handler(func=lambda c: c.data == 'back')
+def back_callback(call: types.CallbackQuery):
+    bot.edit_message_text(chat_id=call.message.chat.id, message_id=call.message.message_id,
+                          text='Products:', reply_markup=products_keyboard())
+
+
+bot.add_custom_filter(ProductsCallbackFilter())
+bot.infinity_polling()

examples/anonymous_bot.py

@@ -0,0 +1,117 @@
+# This bot is needed to connect two people and their subsequent anonymous communication
+#
+# Avaiable commands:
+# `/start` - Just send you a messsage how to start
+# `/find` - Find a person you can contact
+# `/stop` - Stop active conversation
+
+import telebot
+from telebot import types
+
+# Initialize bot with your token
+bot = telebot.TeleBot(TOKEN)
+
+# The `users` variable is needed to contain chat ids that are either in the search or in the active dialog, like {chat_id, chat_id}
+users = {}
+# The `freeid` variable is needed to contain chat id, that want to start conversation
+# Or, in other words: chat id of user in the search
+freeid = None
+
+# `/start` command handler
+#
+# That command only sends you 'Just use /find command!'
+@bot.message_handler(commands=['start'])
+def start(message: types.Message):
+    bot.send_message(message.chat.id, 'Just use /find command!')
+
+# `/find` command handler
+#
+# That command finds opponent for you
+#
+# That command according to the following principle:
+# 1. You have written `/find` command
+# 2. If you are already in the search or have an active dialog, bot sends you 'Shut up!'
+# 3. If not:
+#   3.1. Bot sends you 'Finding...'
+#   3.2. If there is no user in the search:
+#       3.2.2. `freeid` updated with `your_chat_id`
+#   3.3. If there is user in the search:
+#       3.3.1. Both you and the user in the search recieve the message 'Founded!'
+#       3.3.2. `users` updated with a {user_in_the_search_chat_id, your_chat_id}
+#       3.3.3. `users` updated with a {your_chat_id, user_in_the_search_id}
+#       3.3.4. `freeid` updated with `None`
+@bot.message_handler(commands=['find'])
+def find(message: types.Message):
+    global freeid
+
+    if message.chat.id not in users:
+        bot.send_message(message.chat.id, 'Finding...')
+
+        if freeid == None:
+            freeid = message.chat.id
+        else:
+            # Question:
+            # Is there any way to simplify this like `bot.send_message([message.chat.id, freeid], 'Founded!')`?
+            bot.send_message(message.chat.id, 'Founded!')
+            bot.send_message(freeid, 'Founded!')
+
+            users[freeid] = message.chat.id
+            users[message.chat.id] = freeid
+            freeid = None
+
+        print(users, freeid) # Debug purpose, you can remove that line
+    else:
+        bot.send_message(message.chat.id, 'Shut up!')
+
+# `/stop` command handler
+#
+# That command stops your current conversation (if it exist)
+#
+# That command according to the following principle:
+# 1. You have written `/stop` command
+# 2. If you are not have active dialog or you are not in search, bot sends you 'You are not in search!'
+# 3. If you are in active dialog:
+#   3.1. Bot sends you 'Stopping...'
+#   3.2. Bot sends 'Your opponent is leavin`...' to your opponent
+#   3.3. {your_opponent_chat_id, your_chat_id} removes from `users`
+#   3.4. {your_chat_id, your_opponent_chat_id} removes from `users`
+# 4. If you are only in search:
+#   4.1. Bot sends you 'Stopping...'
+#   4.2. `freeid` updated with `None`
+@bot.message_handler(commands=['stop'])
+def stop(message: types.Message):
+    global freeid
+
+    if message.chat.id in users:
+        bot.send_message(message.chat.id, 'Stopping...')
+        bot.send_message(users[message.chat.id], 'Your opponent is leavin`...')
+
+        del users[users[message.chat.id]]
+        del users[message.chat.id]
+        
+        print(users, freeid) # Debug purpose, you can remove that line
+    elif message.chat.id == freeid:
+        bot.send_message(message.chat.id, 'Stopping...')
+        freeid = None
+
+        print(users, freeid) # Debug purpose, you can remove that line
+    else:
+        bot.send_message(message.chat.id, 'You are not in search!')
+
+# message handler for conversation
+#
+# That handler needed to send message from one opponent to another
+# If you are not in `users`, you will recieve a message 'No one can hear you...'
+# Otherwise all your messages are sent to your opponent
+#
+# Questions:
+# 1. Is there any way to improve readability like `content_types=['all']`?
+# 2. Is there any way to register this message handler only when i found the opponent?
+@bot.message_handler(content_types=['animation', 'audio', 'contact', 'dice', 'document', 'location', 'photo', 'poll', 'sticker', 'text', 'venue', 'video', 'video_note', 'voice'])
+def chatting(message: types.Message):
+    if message.chat.id in users:
+        bot.copy_message(users[message.chat.id], users[users[message.chat.id]], message.id)
+    else:
+        bot.send_message(message.chat.id, 'No one can hear you...')
+
+bot.infinity_polling(skip_pending=True)

examples/asynchronous_telebot/CallbackData_example.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""
+This Example will show you how to use CallbackData
+"""
+
+from telebot.callback_data import CallbackData, CallbackDataFilter
+from telebot import types
+from telebot.async_telebot import AsyncTeleBot
+from telebot.asyncio_filters import AdvancedCustomFilter
+
+API_TOKEN = 'TOKEN'
+PRODUCTS = [
+    {'id': '0', 'name': 'xiaomi mi 10', 'price': 400},
+    {'id': '1', 'name': 'samsung s20', 'price': 800},
+    {'id': '2', 'name': 'iphone 13', 'price': 1300}
+]
+
+bot = AsyncTeleBot(API_TOKEN)
+products_factory = CallbackData('product_id', prefix='products')
+
+
+def products_keyboard():
+    return types.InlineKeyboardMarkup(
+        keyboard=[
+            [
+                types.InlineKeyboardButton(
+                    text=product['name'],
+                    callback_data=products_factory.new(product_id=product["id"])
+                )
+            ]
+            for product in PRODUCTS
+        ]
+    )
+
+
+def back_keyboard():
+    return types.InlineKeyboardMarkup(
+        keyboard=[
+            [
+                types.InlineKeyboardButton(
+                    text='⬅',
+                    callback_data='back'
+                )
+            ]
+        ]
+    )
+
+
+class ProductsCallbackFilter(AdvancedCustomFilter):
+    key = 'config'
+
+    async def check(self, call: types.CallbackQuery, config: CallbackDataFilter):
+        return config.check(query=call)
+
+
+@bot.message_handler(commands=['products'])
+async def products_command_handler(message: types.Message):
+    await bot.send_message(message.chat.id, 'Products:', reply_markup=products_keyboard())
+
+
+# Only product with field - product_id = 2
+@bot.callback_query_handler(func=None, config=products_factory.filter(product_id='2'))
+async def product_one_callback(call: types.CallbackQuery):
+    await bot.answer_callback_query(callback_query_id=call.id, text='Not available :(', show_alert=True)
+
+
+# Any other products
+@bot.callback_query_handler(func=None, config=products_factory.filter())
+async def products_callback(call: types.CallbackQuery):
+    callback_data: dict = products_factory.parse(callback_data=call.data)
+    product_id = int(callback_data['product_id'])
+    product = PRODUCTS[product_id]
+
+    text = f"Product name: {product['name']}\n" \
+           f"Product price: {product['price']}"
+    await bot.edit_message_text(chat_id=call.message.chat.id, message_id=call.message.message_id,
+                          text=text, reply_markup=back_keyboard())
+
+
+@bot.callback_query_handler(func=lambda c: c.data == 'back')
+async def back_callback(call: types.CallbackQuery):
+    await bot.edit_message_text(chat_id=call.message.chat.id, message_id=call.message.message_id,
+                          text='Products:', reply_markup=products_keyboard())
+
+
+bot.add_custom_filter(ProductsCallbackFilter())
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/chat_join_request.py

@@ -0,0 +1,12 @@
+from telebot.async_telebot import AsyncTeleBot
+
+import telebot
+bot = AsyncTeleBot('TOKEN')
+
+@bot.chat_join_request_handler()
+async def make_some(message: telebot.types.ChatJoinRequest):
+    await bot.send_message(message.chat.id, 'I accepted a new user!')
+    await bot.approve_chat_join_request(message.chat.id, message.from_user.id)
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/chat_member_example.py

@@ -0,0 +1,34 @@
+from telebot import types,util
+from telebot.async_telebot import AsyncTeleBot
+
+bot = AsyncTeleBot('TOKEN')
+
+#chat_member_handler. When status changes, telegram gives update. check status from old_chat_member and new_chat_member.
+@bot.chat_member_handler()
+async def chat_m(message: types.ChatMemberUpdated):
+    old = message.old_chat_member
+    new = message.new_chat_member
+    if new.status == "member":
+        await bot.send_message(message.chat.id,"Hello {name}!".format(name=new.user.first_name)) # Welcome message
+
+#if bot is added to group, this handler will work
+@bot.my_chat_member_handler()
+async def my_chat_m(message: types.ChatMemberUpdated):
+    old = message.old_chat_member
+    new = message.new_chat_member
+    if new.status == "member":
+        await bot.send_message(message.chat.id,"Somebody added me to group") # Welcome message, if bot was added to group
+        await bot.leave_chat(message.chat.id)
+
+#content_Type_service is:
+#'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
+#'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
+#'proximity_alert_triggered', 'voice_chat_scheduled', 'voice_chat_started', 'voice_chat_ended', 
+#'voice_chat_participants_invited', 'message_auto_delete_timer_changed'
+# this handler deletes service messages
+
+@bot.message_handler(content_types=util.content_type_service)
+async def delall(message: types.Message):
+    await bot.delete_message(message.chat.id,message.message_id)
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_filters/admin_filter_example.py

@@ -0,0 +1,14 @@
+from telebot.async_telebot import AsyncTeleBot
+from telebot import asyncio_filters
+bot = AsyncTeleBot('TOKEN')
+
+# Handler
+@bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
+async def answer_for_admin(message):
+    await bot.send_message(message.chat.id,"hello my admin")
+
+# Register filter
+bot.add_custom_filter(asyncio_filters.IsAdminFilter(bot))
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_filters/general_custom_filters.py

@@ -0,0 +1,44 @@
+from telebot.async_telebot import AsyncTeleBot
+import telebot
+bot = AsyncTeleBot('TOKEN')
+
+
+# AdvancedCustomFilter is for list, string filter values
+class MainFilter(telebot.asyncio_filters.AdvancedCustomFilter):
+    key='text'
+    @staticmethod
+    async def check(message, text):
+        return message.text in text
+
+# SimpleCustomFilter is for boolean values, such as is_admin=True
+class IsAdmin(telebot.asyncio_filters.SimpleCustomFilter):
+    key='is_admin'
+    @staticmethod
+    async def check(message: telebot.types.Message):
+        result = await bot.get_chat_member(message.chat.id,message.from_user.id)
+        return result.status in ['administrator','creator']
+
+
+@bot.message_handler(is_admin=True, commands=['admin']) # Check if user is admin
+async def admin_rep(message):
+    await bot.send_message(message.chat.id, "Hi admin")
+
+@bot.message_handler(is_admin=False, commands=['admin']) # If user is not admin
+async def not_admin(message):
+    await bot.send_message(message.chat.id, "You are not admin")
+
+@bot.message_handler(text=['hi']) # Response to hi message
+async def welcome_hi(message):
+    await bot.send_message(message.chat.id, 'You said hi')
+
+@bot.message_handler(text=['bye']) # Response to bye message
+async def bye_user(message):
+    await bot.send_message(message.chat.id, 'You said bye')
+
+
+# Do not forget to register filters
+bot.add_custom_filter(MainFilter())
+bot.add_custom_filter(IsAdmin())
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_filters/id_filter_example.py

@@ -0,0 +1,18 @@
+from telebot.async_telebot import AsyncTeleBot
+import telebot
+bot = AsyncTeleBot('TOKEN')
+
+
+# Chat id can be private or supergroups.
+@bot.message_handler(chat_id=[12345678], commands=['admin']) # chat_id checks id corresponds to your list or not.
+async def admin_rep(message):
+    await bot.send_message(message.chat.id, "You are allowed to use this command.")
+
+@bot.message_handler(commands=['admin'])
+async def not_admin(message):
+    await bot.send_message(message.chat.id, "You are not allowed to use this command")
+
+# Do not forget to register
+bot.add_custom_filter(telebot.asyncio_filters.ChatFilter())
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_filters/is_filter_example.py

@@ -0,0 +1,23 @@
+from telebot.async_telebot import AsyncTeleBot
+import telebot
+
+bot = AsyncTeleBot('TOKEN')
+
+
+
+# Check if message is a reply
+@bot.message_handler(is_reply=True)
+async def start_filter(message):
+    await bot.send_message(message.chat.id, "Looks like you replied to my message.")
+
+# Check if message was forwarded
+@bot.message_handler(is_forwarded=True)
+async def text_filter(message):
+    await bot.send_message(message.chat.id, "I do not accept forwarded messages!")
+
+# Do not forget to register filters
+bot.add_custom_filter(telebot.asyncio_filters.IsReplyFilter())
+bot.add_custom_filter(telebot.asyncio_filters.ForwardFilter())
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_filters/text_filter_example.py

@@ -0,0 +1,21 @@
+from telebot.async_telebot import AsyncTeleBot
+import telebot
+bot = AsyncTeleBot('TOKEN')
+
+
+# Check if message starts with @admin tag
+@bot.message_handler(text_startswith="@admin")
+async def start_filter(message):
+    await bot.send_message(message.chat.id, "Looks like you are calling admin, wait...")
+
+# Check if text is hi or hello
+@bot.message_handler(text=['hi','hello'])
+async def text_filter(message):
+    await bot.send_message(message.chat.id, "Hi, {name}!".format(name=message.from_user.first_name))
+
+# Do not forget to register filters
+bot.add_custom_filter(telebot.asyncio_filters.TextMatchFilter())
+bot.add_custom_filter(telebot.asyncio_filters.TextStartsFilter())
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/custom_states.py

@@ -0,0 +1,75 @@
+import telebot
+from telebot import asyncio_filters
+from telebot.async_telebot import AsyncTeleBot
+bot = AsyncTeleBot('TOKEN')
+
+
+
+class MyStates:
+    name = 1
+    surname = 2
+    age = 3
+
+
+
+@bot.message_handler(commands=['start'])
+async def start_ex(message):
+    """
+    Start command. Here we are starting state
+    """
+    await bot.set_state(message.from_user.id, MyStates.name)
+    await bot.send_message(message.chat.id, 'Hi, write me a name')
+ 
+
+ 
+@bot.message_handler(state="*", commands='cancel')
+async def any_state(message):
+    """
+    Cancel state
+    """
+    await bot.send_message(message.chat.id, "Your state was cancelled.")
+    await bot.delete_state(message.from_user.id)
+
+@bot.message_handler(state=MyStates.name)
+async def name_get(message):
+    """
+    State 1. Will process when user's state is 1.
+    """
+    await bot.send_message(message.chat.id, f'Now write me a surname')
+    await bot.set_state(message.from_user.id, MyStates.surname)
+    async with bot.retrieve_data(message.from_user.id) as data:
+        data['name'] = message.text
+ 
+ 
+@bot.message_handler(state=MyStates.surname)
+async def ask_age(message):
+    """
+    State 2. Will process when user's state is 2.
+    """
+    await bot.send_message(message.chat.id, "What is your age?")
+    await bot.set_state(message.from_user.id, MyStates.age)
+    async with bot.retrieve_data(message.from_user.id) as data:
+        data['surname'] = message.text
+ 
+# result
+@bot.message_handler(state=MyStates.age, is_digit=True)
+async def ready_for_answer(message):
+    async with bot.retrieve_data(message.from_user.id) as data:
+        await bot.send_message(message.chat.id, "Ready, take a look:\n<b>Name: {name}\nSurname: {surname}\nAge: {age}</b>".format(name=data['name'], surname=data['surname'], age=message.text), parse_mode="html")
+    await bot.delete_state(message.from_user.id)
+
+#incorrect number
+@bot.message_handler(state=MyStates.age, is_digit=False)
+async def age_incorrect(message):
+    await bot.send_message(message.chat.id, 'Looks like you are submitting a string in the field age. Please enter a number')
+
+# register filters
+
+bot.add_custom_filter(asyncio_filters.StateFilter(bot))
+bot.add_custom_filter(asyncio_filters.IsDigitFilter())
+
+# set saving states into file.
+bot.enable_saving_states() # you can delete this if you do not need to save states
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/download_file_example.py

@@ -0,0 +1,21 @@
+
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+
+
+
+bot = AsyncTeleBot('TOKEN')
+
+
+@bot.message_handler(content_types=['photo'])
+async def new_message(message: telebot.types.Message):
+    result_message = await bot.send_message(message.chat.id, '<i>Downloading your photo...</i>', parse_mode='HTML', disable_web_page_preview=True)
+    file_path = await bot.get_file(message.photo[-1].file_id)
+    downloaded_file = await bot.download_file(file_path.file_path)
+    with open('file.jpg', 'wb') as new_file:
+        new_file.write(downloaded_file)
+    await bot.edit_message_text(chat_id=message.chat.id, message_id=result_message.id, text='<i>Done!</i>', parse_mode='HTML')
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/echo_bot.py

@@ -0,0 +1,27 @@
+#!/usr/bin/python
+
+# This is a simple echo bot using the decorator mechanism.
+# It echoes any incoming text messages.
+
+from telebot.async_telebot import AsyncTeleBot
+bot = AsyncTeleBot('TOKEN')
+
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+async def send_welcome(message):
+    await bot.reply_to(message, """\
+Hi there, I am EchoBot.
+I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
+""")
+
+
+# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
+@bot.message_handler(func=lambda message: True)
+async def echo_message(message):
+    await bot.reply_to(message, message.text)
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/exception_handler.py

@@ -0,0 +1,28 @@
+
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+
+
+import logging
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.DEBUG) # Outputs debug messages to console.
+
+class ExceptionHandler(telebot.ExceptionHandler):
+    def handle(self, exception):
+        logger.error(exception)
+
+bot = AsyncTeleBot('TOKEN',exception_handler=ExceptionHandler())
+
+
+
+
+@bot.message_handler(commands=['photo'])
+async def photo_send(message: telebot.types.Message):
+    await bot.send_message(message.chat.id, 'Hi, this is an example of exception handlers.')
+    raise Exception('test') # Exception goes to ExceptionHandler if it is set
+    
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/middleware/flooding_middleware.py

@@ -0,0 +1,40 @@
+# Just a little example of middleware handlers
+
+import telebot
+from telebot.asyncio_handler_backends import BaseMiddleware
+from telebot.async_telebot import AsyncTeleBot
+from telebot.async_telebot import CancelUpdate
+bot = AsyncTeleBot('TOKEN')
+
+
+class SimpleMiddleware(BaseMiddleware):
+    def __init__(self, limit) -> None:
+        self.last_time = {}
+        self.limit = limit
+        self.update_types = ['message']
+        # Always specify update types, otherwise middlewares won't work
+
+
+    async def pre_process(self, message, data):
+        if not message.from_user.id in self.last_time:
+            # User is not in a dict, so lets add and cancel this function
+            self.last_time[message.from_user.id] = message.date
+            return
+        if message.date - self.last_time[message.from_user.id] < self.limit:
+            # User is flooding
+            await bot.send_message(message.chat.id, 'You are making request too often')
+            return CancelUpdate()
+        self.last_time[message.from_user.id] = message.date
+
+        
+    async def post_process(self, message, data, exception):
+        pass
+
+bot.setup_middleware(SimpleMiddleware(2))
+
+@bot.message_handler(commands=['start'])
+async def start(message):
+    await bot.send_message(message.chat.id, 'Hello!')
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/middleware/i18n.py

@@ -0,0 +1,49 @@
+#!/usr/bin/python
+
+# This example shows how to implement i18n (internationalization) l10n (localization) to create
+# multi-language bots with middleware handler.
+#
+# Also, you could check language code in handler itself too.
+# But this example just to show the work of middlewares.
+
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+from telebot import asyncio_handler_backends
+import logging
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.DEBUG) # Outputs debug messages to console.
+
+TRANSLATIONS = {
+    'hello': {
+        'en': 'hello',
+        'ru': 'привет',
+        'uz': 'salom'
+    }
+}
+
+
+
+bot = AsyncTeleBot('TOKEN')
+
+
+class LanguageMiddleware(asyncio_handler_backends.BaseMiddleware):
+    def __init__(self):
+        self.update_types = ['message'] # Update types that will be handled by this middleware.
+    async def pre_process(self, message, data):
+        data['response'] = TRANSLATIONS['hello'][message.from_user.language_code]
+    async def post_process(self, message, data, exception):
+        if exception: # You can get exception occured in handler.
+            logger.exception(str(exception))
+
+bot.setup_middleware(LanguageMiddleware()) # do not forget to setup
+
+@bot.message_handler(commands=['start'])
+async def start(message, data: dict):
+    # you can get the data in handler too.
+    # Not necessary to create data parameter in handler function.
+    await bot.send_message(message.chat.id, data['response'])
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/register_handler.py

@@ -0,0 +1,20 @@
+from telebot.async_telebot import AsyncTeleBot
+bot = AsyncTeleBot('TOKEN')
+
+async def start_executor(message):
+    await bot.send_message(message.chat.id, 'Hello!')
+
+bot.register_message_handler(start_executor, commands=['start']) # Start command executor
+
+# See also
+# bot.register_callback_query_handler(*args, **kwargs)
+# bot.register_channel_post_handler(*args, **kwargs)
+# bot.register_chat_member_handler(*args, **kwargs)
+# bot.register_inline_handler(*args, **kwargs)
+# bot.register_my_chat_member_handler(*args, **kwargs)
+# bot.register_edited_message_handler(*args, **kwargs)
+# And other functions..
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/send_file_example.py

@@ -0,0 +1,29 @@
+
+import telebot
+from telebot.async_telebot import AsyncTeleBot
+
+
+
+bot = AsyncTeleBot('TOKEN')
+
+
+@bot.message_handler(commands=['photo'])
+async def photo_send(message: telebot.types.Message):
+    with open('test.png', 'rb') as new_file:
+        await bot.send_photo(message.chat.id, new_file)
+
+@bot.message_handler(commands=['document'])
+async def document_send(message: telebot.types.Message):
+    with open('test.docx', 'rb') as new_file:
+        await bot.send_document(message.chat.id, new_file)
+
+@bot.message_handler(commands=['photos'])
+async def photos_send(message: telebot.types.Message):
+    with open('test.png', 'rb') as new_file, open('test2.png', 'rb') as new_file2:
+        await bot.send_media_group(message.chat.id, [telebot.types.InputMediaPhoto(new_file), telebot.types.InputMediaPhoto(new_file2)])
+    
+
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/asynchronous_telebot/skip_updates_example.py

@@ -0,0 +1,15 @@
+from telebot.async_telebot import AsyncTeleBot
+
+bot = AsyncTeleBot('TOKEN')
+
+@bot.message_handler(commands=['start', 'help'])
+async def send_welcome(message):
+	await bot.reply_to(message, "Howdy, how are you doing?")
+
+@bot.message_handler(func=lambda message: True)
+async def echo_all(message):
+	await bot.reply_to(message, message.text)
+
+
+import asyncio
+asyncio.run(bot.polling(skip_pending=True)) # to skip updates

examples/asynchronous_telebot/update_listener.py

@@ -0,0 +1,16 @@
+from telebot.async_telebot import AsyncTeleBot
+
+# Update listeners are functions that are called when any update is received.
+
+bot = AsyncTeleBot(token='TOKEN')
+
+async def update_listener(messages):
+    for message in messages:
+        if message.text == '/start':
+            await bot.send_message(message.chat.id, 'Hello!')
+
+bot.set_update_listener(update_listener)
+
+
+import asyncio
+asyncio.run(bot.polling())

examples/chat_join_request.py

@@ -0,0 +1,11 @@
+import telebot
+
+
+bot = telebot.TeleBot('TOKEN')
+
+@bot.chat_join_request_handler()
+def make_some(message: telebot.types.ChatJoinRequest):
+    bot.send_message(message.chat.id, 'I accepted a new user!')
+    bot.approve_chat_join_request(message.chat.id, message.from_user.id)
+
+bot.infinity_polling(allowed_updates=telebot.util.update_types)

examples/chat_member_example.py

@@ -0,0 +1,33 @@
+import telebot
+from telebot import types,util
+
+bot = telebot.TeleBot("token")
+
+#chat_member_handler. When status changes, telegram gives update. check status from old_chat_member and new_chat_member.
+@bot.chat_member_handler()
+def chat_m(message: types.ChatMemberUpdated):
+    old = message.old_chat_member
+    new = message.new_chat_member
+    if new.status == "member":
+        bot.send_message(message.chat.id,"Hello {name}!".format(name=new.user.first_name)) # Welcome message
+
+#if bot is added to group, this handler will work
+@bot.my_chat_member_handler()
+def my_chat_m(message: types.ChatMemberUpdated):
+    old = message.old_chat_member
+    new = message.new_chat_member
+    if new.status == "member":
+        bot.send_message(message.chat.id,"Somebody added me to group") # Welcome message, if bot was added to group
+        bot.leave_chat(message.chat.id)
+
+#content_Type_service is:
+#'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
+#'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
+#'proximity_alert_triggered', 'voice_chat_scheduled', 'voice_chat_started', 'voice_chat_ended', 
+#'voice_chat_participants_invited', 'message_auto_delete_timer_changed'
+# this handler deletes service messages
+
+@bot.message_handler(content_types=util.content_type_service)
+def delall(message: types.Message):
+    bot.delete_message(message.chat.id,message.message_id)
+bot.infinity_polling(allowed_updates=util.update_types)

examples/custom_filters/admin_filter_example.py

@@ -0,0 +1,12 @@
+import telebot
+from telebot import custom_filters
+bot = telebot.TeleBot('TOKEN')
+
+# Handler
+@bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
+def answer_for_admin(message):
+    bot.send_message(message.chat.id,"hello my admin")
+
+# Register filter
+bot.add_custom_filter(custom_filters.IsAdminFilter(bot))
+bot.infinity_polling()

examples/custom_filters/general_custom_filters.py

@@ -0,0 +1,42 @@
+import telebot
+
+bot = telebot.TeleBot('TOKEN')
+
+
+# AdvancedCustomFilter is for list, string filter values
+class MainFilter(telebot.custom_filters.AdvancedCustomFilter):
+    key='text'
+    @staticmethod
+    def check(message, text):
+        return message.text in text
+
+# SimpleCustomFilter is for boolean values, such as is_admin=True
+class IsAdmin(telebot.custom_filters.SimpleCustomFilter):
+    key='is_admin'
+    @staticmethod
+    def check(message: telebot.types.Message):
+        return bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator']
+
+
+@bot.message_handler(is_admin=True, commands=['admin']) # Check if user is admin
+def admin_rep(message):
+    bot.send_message(message.chat.id, "Hi admin")
+
+@bot.message_handler(is_admin=False, commands=['admin']) # If user is not admin
+def not_admin(message):
+    bot.send_message(message.chat.id, "You are not admin")
+
+@bot.message_handler(text=['hi']) # Response to hi message
+def welcome_hi(message):
+    bot.send_message(message.chat.id, 'You said hi')
+
+@bot.message_handler(text=['bye']) # Response to bye message
+def bye_user(message):
+    bot.send_message(message.chat.id, 'You said bye')
+
+
+# Do not forget to register filters
+bot.add_custom_filter(MainFilter())
+bot.add_custom_filter(IsAdmin())
+
+bot.infinity_polling(skip_pending=True) # Skip old updates

examples/custom_filters/id_filter_example.py

@@ -0,0 +1,19 @@
+import telebot
+from telebot import custom_filters
+
+bot = telebot.TeleBot('token')
+
+
+# Chat id can be private or supergroups.
+@bot.message_handler(chat_id=[12345678], commands=['admin']) # chat_id checks id corresponds to your list or not.
+def admin_rep(message):
+    bot.send_message(message.chat.id, "You are allowed to use this command.")
+
+@bot.message_handler(commands=['admin'])
+def not_admin(message):
+    bot.send_message(message.chat.id, "You are not allowed to use this command")
+
+# Do not forget to register
+bot.add_custom_filter(custom_filters.ChatFilter())
+
+bot.infinity_polling()

examples/custom_filters/is_filter_example.py

@@ -0,0 +1,21 @@
+import telebot
+from telebot import custom_filters
+
+bot = telebot.TeleBot('TOKEN')
+
+
+# Check if message is a reply
+@bot.message_handler(is_reply=True)
+def start_filter(message):
+    bot.send_message(message.chat.id, "Looks like you replied to my message.")
+
+# Check if message was forwarded
+@bot.message_handler(is_forwarded=True)
+def text_filter(message):
+    bot.send_message(message.chat.id, "I do not accept forwarded messages!")
+
+# Do not forget to register filters
+bot.add_custom_filter(custom_filters.IsReplyFilter())
+bot.add_custom_filter(custom_filters.ForwardFilter())
+
+bot.infinity_polling()

examples/custom_filters/text_filter_example.py

@@ -0,0 +1,21 @@
+import telebot
+from telebot import custom_filters
+
+bot = telebot.TeleBot('TOKEN')
+
+
+# Check if message starts with @admin tag
+@bot.message_handler(text_startswith="@admin")
+def start_filter(message):
+    bot.send_message(message.chat.id, "Looks like you are calling admin, wait...")
+
+# Check if text is hi or hello
+@bot.message_handler(text=['hi','hello'])
+def text_filter(message):
+    bot.send_message(message.chat.id, "Hi, {name}!".format(name=message.from_user.first_name))
+
+# Do not forget to register filters
+bot.add_custom_filter(custom_filters.TextMatchFilter())
+bot.add_custom_filter(custom_filters.TextStartsFilter())
+
+bot.infinity_polling()

examples/custom_states.py

@@ -0,0 +1,74 @@
+import telebot
+
+from telebot import custom_filters
+
+bot = telebot.TeleBot("")
+
+
+class MyStates:
+    name = 1
+    surname = 2
+    age = 3
+
+
+
+@bot.message_handler(commands=['start'])
+def start_ex(message):
+    """
+    Start command. Here we are starting state
+    """
+    bot.set_state(message.from_user.id, MyStates.name)
+    bot.send_message(message.chat.id, 'Hi, write me a name')
+ 
+
+ 
+@bot.message_handler(state="*", commands='cancel')
+def any_state(message):
+    """
+    Cancel state
+    """
+    bot.send_message(message.chat.id, "Your state was cancelled.")
+    bot.delete_state(message.from_user.id)
+
+@bot.message_handler(state=MyStates.name)
+def name_get(message):
+    """
+    State 1. Will process when user's state is 1.
+    """
+    bot.send_message(message.chat.id, f'Now write me a surname')
+    bot.set_state(message.from_user.id, MyStates.surname)
+    with bot.retrieve_data(message.from_user.id) as data:
+        data['name'] = message.text
+ 
+ 
+@bot.message_handler(state=MyStates.surname)
+def ask_age(message):
+    """
+    State 2. Will process when user's state is 2.
+    """
+    bot.send_message(message.chat.id, "What is your age?")
+    bot.set_state(message.from_user.id, MyStates.age)
+    with bot.retrieve_data(message.from_user.id) as data:
+        data['surname'] = message.text
+ 
+# result
+@bot.message_handler(state=MyStates.age, is_digit=True)
+def ready_for_answer(message):
+    with bot.retrieve_data(message.from_user.id) as data:
+        bot.send_message(message.chat.id, "Ready, take a look:\n<b>Name: {name}\nSurname: {surname}\nAge: {age}</b>".format(name=data['name'], surname=data['surname'], age=message.text), parse_mode="html")
+    bot.delete_state(message.from_user.id)
+
+#incorrect number
+@bot.message_handler(state=MyStates.age, is_digit=False)
+def age_incorrect(message):
+    bot.send_message(message.chat.id, 'Looks like you are submitting a string in the field age. Please enter a number')
+
+# register filters
+
+bot.add_custom_filter(custom_filters.StateFilter(bot))
+bot.add_custom_filter(custom_filters.IsDigitFilter())
+
+# set saving states into file.
+bot.enable_saving_states() # you can delete this if you do not need to save states
+
+bot.infinity_polling(skip_pending=True)

examples/deep_linking.py

@@ -1,3 +1,5 @@
+#!/usr/bin/python
+
 # This example shows how to implement deep linking (https://core.telegram.org/bots#deep-linking)
 # with the pyTelegramBotAPI.
 # Note: This is not a working, production-ready sample.
@@ -31,34 +33,38 @@
 # steps are not shown here. Only steps 5 to 7 are illustrated, some in pseudo-code, with this example.
 
 import telebot
-import time
 
 bot = telebot.TeleBot('TOKEN')
 
+
 def extract_unique_code(text):
     # Extracts the unique_code from the sent /start command.
     return text.split()[1] if len(text.split()) > 1 else None
 
+
 def in_storage(unique_code):
     # (pseudo-code) Should check if a unique code exists in storage
     return True
 
+
 def get_username_from_storage(unique_code):
     # (pseudo-code) Does a query to the storage, retrieving the associated username
     # Should be replaced by a real database-lookup.
     return "ABC" if in_storage(unique_code) else None
 
+
 def save_chat_id(chat_id, username):
     # (pseudo-code) Save the chat_id->username to storage
     # Should be replaced by a real database query.
     pass
 
+
 @bot.message_handler(commands=['start'])
 def send_welcome(message):
     unique_code = extract_unique_code(message.text)
-    if unique_code: # if the '/start' command contains a unique_code
+    if unique_code:  # if the '/start' command contains a unique_code
         username = get_username_from_storage(unique_code)
-        if username: # if the username exists in our database
+        if username:  # if the username exists in our database
             save_chat_id(message.chat.id, username)
             reply = "Hello {0}, how are you?".format(username)
         else:
@@ -67,4 +73,5 @@ def send_welcome(message):
         reply = "Please visit me via a provided URL from the website."
     bot.reply_to(message, reply)
 
-bot.polling()
+
+bot.infinity_polling()

examples/detailed_example/detailed_example.py

@@ -2,9 +2,10 @@
 This is a detailed example using almost every command of the API
 """
 
+import time
+
 import telebot
 from telebot import types
-import time
 
 TOKEN = '<token_string>'
 
@@ -12,16 +13,16 @@ knownUsers = []  # todo: save these in a file,
 userStep = {}  # so they won't reset every time the bot restarts
 
 commands = {  # command description used in the "help" command
-              'start': 'Get used to the bot',
-              'help': 'Gives you information about the available commands',
-              'sendLongText': 'A test using the \'send_chat_action\' command',
-              'getImage': 'A test using multi-stage messages, custom keyboard, and media sending'
+    'start'       : 'Get used to the bot',
+    'help'        : 'Gives you information about the available commands',
+    'sendLongText': 'A test using the \'send_chat_action\' command',
+    'getImage'    : 'A test using multi-stage messages, custom keyboard, and media sending'
 }
 
 imageSelect = types.ReplyKeyboardMarkup(one_time_keyboard=True)  # create the image selection keyboard
-imageSelect.add('cock', 'pussy')
+imageSelect.add('Mickey', 'Minnie')
 
-hideBoard = types.ReplyKeyboardHide()  # if sent as reply_markup, will hide the keyboard
+hideBoard = types.ReplyKeyboardRemove()  # if sent as reply_markup, will hide the keyboard
 
 
 # error handling if user isn't known yet
@@ -33,7 +34,7 @@ def get_user_step(uid):
     else:
         knownUsers.append(uid)
         userStep[uid] = 0
-        print "New user detected, who hasn't used \"/start\" yet"
+        print("New user detected, who hasn't used \"/start\" yet")
         return 0
 
 
@@ -45,7 +46,7 @@ def listener(messages):
     for m in messages:
         if m.content_type == 'text':
             # print the sent message to the console
-            print str(m.chat.first_name) + " [" + str(m.chat.id) + "]: " + m.text
+            print(str(m.chat.first_name) + " [" + str(m.chat.id) + "]: " + m.text)
 
 
 bot = telebot.TeleBot(TOKEN)
@@ -104,15 +105,15 @@ def msg_image_select(m):
     # for some reason the 'upload_photo' status isn't quite working (doesn't show at all)
     bot.send_chat_action(cid, 'typing')
 
-    if text == "cock":  # send the appropriate image based on the reply to the "/getImage" command
+    if text == 'Mickey':  # send the appropriate image based on the reply to the "/getImage" command
         bot.send_photo(cid, open('rooster.jpg', 'rb'),
                        reply_markup=hideBoard)  # send file and hide keyboard, after image is sent
         userStep[cid] = 0  # reset the users step back to 0
-    elif text == "pussy":
+    elif text == 'Minnie':
         bot.send_photo(cid, open('kitten.jpg', 'rb'), reply_markup=hideBoard)
         userStep[cid] = 0
     else:
-        bot.send_message(cid, "Don't type bullsh*t, if I give you a predefined keyboard!")
+        bot.send_message(cid, "Please, use the predefined keyboard!")
         bot.send_message(cid, "Please try again")
 
 
@@ -128,4 +129,5 @@ def command_default(m):
     # this is the standard reply to a normal message
     bot.send_message(m.chat.id, "I don't understand \"" + m.text + "\"\nMaybe try the help page at /help")
 
-bot.polling()
+
+bot.infinity_polling()

examples/download_file_example.py

@@ -5,7 +5,7 @@ CHAT_ID = 'YOUR CHAT ID'
 
 bot = telebot.TeleBot(TOKEN)
 
-ret_msg = bot.send_voice(CHAT_ID, open('tests/test_data/record.ogg'))
+ret_msg = bot.send_voice(CHAT_ID, open('tests/test_data/record.ogg', 'rb'))
 
 file_info = bot.get_file(ret_msg.voice.file_id)
 

examples/echo_bot.py

@@ -1,3 +1,5 @@
+#!/usr/bin/python
+
 # This is a simple echo bot using the decorator mechanism.
 # It echoes any incoming text messages.
 
@@ -7,6 +9,7 @@ API_TOKEN = '<api_token>'
 
 bot = telebot.TeleBot(API_TOKEN)
 
+
 # Handle '/start' and '/help'
 @bot.message_handler(commands=['help', 'start'])
 def send_welcome(message):
@@ -21,4 +24,5 @@ I am here to echo your kind words back to you. Just say anything nice and I'll s
 def echo_message(message):
     bot.reply_to(message, message.text)
 
-bot.polling()
+
+bot.infinity_polling()

examples/inline_example.py

@@ -1,8 +1,9 @@
-# This example show how to write an inline mode telegramt bot use pyTelegramBotAPI.
-import telebot
-import time
-import sys
+# This example show how to write an inline mode telegram bot use pyTelegramBotAPI.
 import logging
+import sys
+import time
+
+import telebot
 from telebot import types
 
 API_TOKEN = '<TOKEN>'
@@ -50,7 +51,7 @@ def query_video(inline_query):
         print(e)
 
 
-@bot.inline_handler(lambda query: len(query.query) is 0)
+@bot.inline_handler(lambda query: len(query.query) == 0)
 def default_query(inline_query):
     try:
         r = types.InlineQueryResultArticle('1', 'default', types.InputTextMessageContent('default'))
@@ -60,7 +61,7 @@ def default_query(inline_query):
 
 
 def main_loop():
-    bot.polling(True)
+    bot.infinity_polling()
     while 1:
         time.sleep(3)
 
@@ -69,5 +70,5 @@ if __name__ == '__main__':
     try:
         main_loop()
     except KeyboardInterrupt:
-        print >> sys.stderr, '\nExiting by user request.\n'
+        print('\nExiting by user request.\n')
         sys.exit(0)

examples/inline_keyboard_example.py

@@ -0,0 +1,27 @@
+# This example show how to use inline keyboards and process button presses
+import telebot
+from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+TELEGRAM_TOKEN = '<TOKEN>'
+
+bot = telebot.TeleBot(TELEGRAM_TOKEN)
+
+def gen_markup():
+    markup = InlineKeyboardMarkup()
+    markup.row_width = 2
+    markup.add(InlineKeyboardButton("Yes", callback_data="cb_yes"),
+                               InlineKeyboardButton("No", callback_data="cb_no"))
+    return markup
+
+@bot.callback_query_handler(func=lambda call: True)
+def callback_query(call):
+    if call.data == "cb_yes":
+        bot.answer_callback_query(call.id, "Answer is Yes")
+    elif call.data == "cb_no":
+        bot.answer_callback_query(call.id, "Answer is No")
+
+@bot.message_handler(func=lambda message: True)
+def message_handler(message):
+    bot.send_message(message.chat.id, "Yes/no?", reply_markup=gen_markup())
+
+bot.infinity_polling()

examples/middleware/i18n.py

@@ -0,0 +1,53 @@
+#!/usr/bin/python
+
+# This example shows how to implement i18n (internationalization) l10n (localization) to create
+# multi-language bots with middleware handler.
+#
+# Note: For the sake of simplicity of this example no extra library is used. However, it is recommended to use
+# better i18n systems (gettext and etc) for handling multilingual translations.
+# This is not a working, production-ready sample and it is highly recommended not to use it in production.
+#
+# In this example let's imagine we want to introduce localization or internationalization into our project and
+# we need some global function to activate the language once and to use that language in all other message
+# handler functions for not repeatedly activating it.
+# The middleware (i18n and l10n) is explained:
+
+import telebot
+from telebot import apihelper
+
+apihelper.ENABLE_MIDDLEWARE = True
+
+TRANSLATIONS = {
+    'hello': {
+        'en': 'hello',
+        'ru': 'привет',
+        'uz': 'salom'
+    }
+}
+
+_lang = 'en'
+
+
+def activate(lang):
+    global _lang
+    _lang = lang
+
+
+def _(string):
+    return TRANSLATIONS[string][_lang]
+
+
+bot = telebot.TeleBot('TOKEN')
+
+
+@bot.middleware_handler(update_types=['message'])
+def activate_language(bot_instance, message):
+    activate(message.from_user.language_code)
+
+
+@bot.message_handler(commands=['start'])
+def start(message):
+    bot.send_message(message.chat.id, _('hello'))
+
+
+bot.infinity_polling()

examples/middleware/session.py

@@ -0,0 +1,61 @@
+#!/usr/bin/python
+
+# This example shows how to implement session creation and retrieval based on user id with middleware handler.
+#
+# Note: For the sake of simplicity of this example no extra library is used. However, it is recommended to use
+# in-memory or on-disk storage implementations (redis, mysql, postgres and etc) for storing and retrieving structures.
+# This is not a working, production-ready sample and it is highly recommended not to use it in production.
+#
+# In this example let's imagine we want to create a session for each user who communicates with the bot to store
+# different kind of temporary data while session is active. As an example we want to track the state of the user
+# with the help of this session. So, we need a way to store this session data somewhere globally to enable other
+# message handler functions to be able to use it.
+# The middleware session is explained:
+
+import telebot
+from telebot import apihelper
+
+apihelper.ENABLE_MIDDLEWARE = True
+
+INFO_STATE = 'ON_INFO_MENU'
+MAIN_STATE = 'ON_MAIN_MENU'
+
+SESSIONS = {
+    -10000: {
+        'state': INFO_STATE
+    },
+    -11111: {
+        'state': MAIN_STATE
+    }
+}
+
+
+def get_or_create_session(user_id):
+    try:
+        return SESSIONS[user_id]
+    except KeyError:
+        SESSIONS[user_id] = {'state': MAIN_STATE}
+        return SESSIONS[user_id]
+
+
+bot = telebot.TeleBot('TOKEN')
+
+
+@bot.middleware_handler(update_types=['message'])
+def set_session(bot_instance, message):
+    bot_instance.session = get_or_create_session(message.from_user.id)
+
+
+@bot.message_handler(commands=['start'])
+def start(message):
+    bot.session['state'] = MAIN_STATE
+    bot.send_message(message.chat.id, bot.session['state'])
+
+
+@bot.message_handler(commands=['info'])
+def start(message):
+    bot.session['state'] = INFO_STATE
+    bot.send_message(message.chat.id, bot.session['state'])
+
+
+bot.infinity_polling()

examples/payments_example.py

@@ -0,0 +1,81 @@
+import telebot
+from telebot.types import LabeledPrice, ShippingOption
+
+token = '1234567890:AAAABBBBCCCCDDDDeeeeFFFFgggGHHHH'
+provider_token = '1234567890:TEST:AAAABBBBCCCCDDDD'  # @BotFather -> Bot Settings -> Payments
+bot = telebot.TeleBot(token)
+
+# More about Payments: https://core.telegram.org/bots/payments
+
+prices = [LabeledPrice(label='Working Time Machine', amount=5750), LabeledPrice('Gift wrapping', 500)]
+
+shipping_options = [
+    ShippingOption(id='instant', title='WorldWide Teleporter').add_price(LabeledPrice('Teleporter', 1000)),
+    ShippingOption(id='pickup', title='Local pickup').add_price(LabeledPrice('Pickup', 300))]
+
+
+@bot.message_handler(commands=['start'])
+def command_start(message):
+    bot.send_message(message.chat.id,
+                     "Hello, I'm the demo merchant bot."
+                     " I can sell you a Time Machine."
+                     " Use /buy to order one, /terms for Terms and Conditions")
+
+
+@bot.message_handler(commands=['terms'])
+def command_terms(message):
+    bot.send_message(message.chat.id,
+                     'Thank you for shopping with our demo bot. We hope you like your new time machine!\n'
+                     '1. If your time machine was not delivered on time, please rethink your concept of time and try again.\n'
+                     '2. If you find that your time machine is not working, kindly contact our future service workshops on Trappist-1e.'
+                     ' They will be accessible anywhere between May 2075 and November 4000 C.E.\n'
+                     '3. If you would like a refund, kindly apply for one yesterday and we will have sent it to you immediately.')
+
+
+@bot.message_handler(commands=['buy'])
+def command_pay(message):
+    bot.send_message(message.chat.id,
+                     "Real cards won't work with me, no money will be debited from your account."
+                     " Use this test card number to pay for your Time Machine: `4242 4242 4242 4242`"
+                     "\n\nThis is your demo invoice:", parse_mode='Markdown')
+    bot.send_invoice(message.chat.id, title='Working Time Machine',
+                     description='Want to visit your great-great-great-grandparents?'
+                                 ' Make a fortune at the races?'
+                                 ' Shake hands with Hammurabi and take a stroll in the Hanging Gardens?'
+                                 ' Order our Working Time Machine today!',
+                     provider_token=provider_token,
+                     currency='usd',
+                     photo_url='http://erkelzaar.tsudao.com/models/perrotta/TIME_MACHINE.jpg',
+                     photo_height=512,  # !=0/None or picture won't be shown
+                     photo_width=512,
+                     photo_size=512,
+                     is_flexible=False,  # True If you need to set up Shipping Fee
+                     prices=prices,
+                     start_parameter='time-machine-example',
+                     invoice_payload='HAPPY FRIDAYS COUPON')
+
+
+@bot.shipping_query_handler(func=lambda query: True)
+def shipping(shipping_query):
+    print(shipping_query)
+    bot.answer_shipping_query(shipping_query.id, ok=True, shipping_options=shipping_options,
+                              error_message='Oh, seems like our Dog couriers are having a lunch right now. Try again later!')
+
+
+@bot.pre_checkout_query_handler(func=lambda query: True)
+def checkout(pre_checkout_query):
+    bot.answer_pre_checkout_query(pre_checkout_query.id, ok=True,
+                                  error_message="Aliens tried to steal your card's CVV, but we successfully protected your credentials,"
+                                                " try to pay again in a few minutes, we need a small rest.")
+
+
+@bot.message_handler(content_types=['successful_payment'])
+def got_payment(message):
+    bot.send_message(message.chat.id,
+                     'Hoooooray! Thanks for payment! We will proceed your order for `{} {}` as fast as possible! '
+                     'Stay in touch.\n\nUse /buy again to get a Time Machine for your friend!'.format(
+                         message.successful_payment.total_amount / 100, message.successful_payment.currency),
+                     parse_mode='Markdown')
+
+
+bot.infinity_polling(skip_pending = True)

examples/register_handler.py

@@ -0,0 +1,21 @@
+import telebot
+
+api_token = 'token'
+
+bot = telebot.TeleBot(api_token)
+
+def start_executor(message):
+    bot.send_message(message.chat.id, 'Hello!')
+
+bot.register_message_handler(start_executor, commands=['start']) # Start command executor
+
+# See also
+# bot.register_callback_query_handler(*args, **kwargs)
+# bot.register_channel_post_handler(*args, **kwargs)
+# bot.register_chat_member_handler(*args, **kwargs)
+# bot.register_inline_handler(*args, **kwargs)
+# bot.register_my_chat_member_handler(*args, **kwargs)
+# bot.register_edited_message_handler(*args, **kwargs)
+# And other functions..
+
+bot.infinity_polling()

examples/reply_keyboard_markup_example.py

@@ -0,0 +1,63 @@
+# This example shows you how to create a custom QWERTY keyboard using reply keyboard markup
+import telebot
+from telebot.types import ReplyKeyboardMarkup, KeyboardButton
+
+TOKEN = "<your_token>"
+bot = telebot.TeleBot(TOKEN)
+
+keys = ["1","2","3","4","5","6","7","8","9","0","q","w","e","r","t","y","u","i","o","p","a","s","d","f","g","h","j","k","l","z","x","c","v","b","n","m"]
+symbols = ["1","2","3","4","5","6","7","8","9","0","!","@","#","$","%","^","&","*","(",")","\'","\"","/","\\",",",".",";",":"]
+
+def keyboard(key_type="Normal"):
+    markup = ReplyKeyboardMarkup(row_width=10)
+    if key_type == "Normal":
+        row = [KeyboardButton(x) for x in keys[:10]]
+        markup.add(*row)
+        row = [KeyboardButton(x) for x in keys[10:20]]
+        markup.add(*row)
+        row = [KeyboardButton(x) for x in keys[20:29]]
+        markup.add(*row)
+        row = [KeyboardButton(x) for x in keys[29:]]
+        markup.add(*row)
+        markup.add(KeyboardButton("Caps Lock"),KeyboardButton("Symbols"),KeyboardButton("🔙Delete"),KeyboardButton("✅Done"))
+    elif key_type == "Symbols":
+        row = [KeyboardButton(x) for x in symbols[:10]]
+        markup.add(*row)
+        row = [KeyboardButton(x) for x in symbols[10:20]]
+        markup.add(*row)
+        row = [KeyboardButton(x) for x in symbols[20:]]
+        markup.add(*row)
+        markup.add(KeyboardButton("Caps Lock"),KeyboardButton("Normal"),KeyboardButton("🔙Delete"),KeyboardButton("✅Done"))
+    else:
+        row = [KeyboardButton(x.upper()) for x in keys[:10]]
+        markup.add(*row)
+        row = [KeyboardButton(x.upper()) for x in keys[10:20]]
+        markup.add(*row)
+        row = [KeyboardButton(x.upper()) for x in keys[20:29]]
+        markup.add(*row)
+        row = [KeyboardButton(x.upper()) for x in keys[29:]]
+        markup.add(*row)
+        markup.add(KeyboardButton("Normal"),KeyboardButton("Symbols"),KeyboardButton("🔙Delete"),KeyboardButton("✅Done"))
+    return markup
+
+@bot.message_handler(commands=["start"])
+def start_message(message):
+    bot.send_message(message.chat.id,"You can use the keyboard",reply_markup=keyboard())
+
+@bot.message_handler(func=lambda message:True)
+def all_messages(message):
+    if message.text == "✅Done":
+        markup = telebot.types.ReplyKeyboardRemove()
+        bot.send_message(message.from_user.id,"Done with Keyboard",reply_markup=markup)
+    elif message.text == "Symbols":
+        bot.send_message(message.from_user.id,"Special characters",reply_markup=keyboard("Symbols"))
+    elif message.text == "Normal":
+        bot.send_message(message.from_user.id,"Normal Keyboard",reply_markup=keyboard("Normal"))
+    elif message.text == "Caps Lock":
+        bot.send_message(message.from_user.id,"Caps Lock",reply_markup=keyboard("Caps"))
+    elif message.text == "🔙Delete":
+        bot.delete_message(message.from_user.id,message.message_id)
+    else:
+        bot.send_message(message.chat.id,message.text)
+
+bot.infinity_polling()

examples/serverless/azure_functions

@@ -0,0 +1,69 @@
+# Using Azure Functions for serverless bots.
+# (Thanks to twitter.com/masyan for the idea)
+
+# By default the Azure Functions url is https://.../api/HttpTrigger for HttpTrigger type.
+# In this example we will use clear webhook url without /api/ -> https://.../HttpTrigger.
+# Also we set "authLevel": "anonymous".
+
+# For HttpTrigger type set "route" and "authLevel" in functions.json
+# {
+#   "bindings": [
+#   ...
+#   "authLevel": "anonymous"
+#   "route": "HttpTrigger"
+#   ]
+# }
+
+# To avoid using /api/ in url set "routePrefix":"" in host.json
+# {
+#   ...
+#   "extensions": {
+#     "http": {
+#       "routePrefix": ""
+#     }
+#   }
+# }
+
+import logging
+
+import azure.functions as func
+import telebot
+from telebot import apihelper, types
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.DEBUG)
+
+# Set bot token
+TOKEN = ''
+
+# Uncomment this for using proxy for request
+# PROXY = ''
+# apihelper.proxy = {'https': PROXY}
+
+# Set WEBHOOK as your Azure Functions url (https://...azurewebsites.net/HttpTrigger)
+WEBHOOK = ''
+
+bot = telebot.TeleBot(TOKEN)
+
+@bot.message_handler(commands=['start'])
+def start(message):
+    bot.reply_to(message, 'Hello, ' + message.from_user.first_name)
+
+@bot.message_handler(func=lambda message: True, content_types=['text'])
+def echo_message(message):
+    bot.reply_to(message, message.text)
+
+# To avoid "error 429 too many request" set webhook only once. Or use time.sleep(1).
+def main(req: func.HttpRequest) -> func.HttpResponse:
+    bot.set_webhook(url=WEBHOOK)
+    request_body_dict = req.get_json()
+    update = telebot.types.Update.de_json(request_body_dict)
+    bot.process_new_messages([update.message])
+    return func.HttpResponse(body='', status_code=200)
+    
+# Sometimes "requests" version is important. 
+# azure-functions==1.0.4
+# PySocks==1.7.1
+# pyTelegramBotAPI==3.6.6
+# requests==2.10.0
+

examples/skip_updates_example.py

@@ -0,0 +1,13 @@
+import telebot
+
+bot = telebot.TeleBot("TOKEN")
+
+@bot.message_handler(commands=['start', 'help'])
+def send_welcome(message):
+	bot.reply_to(message, "Howdy, how are you doing?")
+
+@bot.message_handler(func=lambda message: True)
+def echo_all(message):
+	bot.reply_to(message, message.text)
+
+bot.infinity_polling(skip_pending=True)# Skip pending skips old updates

examples/step_example.py

@@ -2,7 +2,6 @@
 """
 This Example will show you how to use register_next_step handler.
 """
-import time
 
 import telebot
 from telebot import types
@@ -69,10 +68,19 @@ def process_sex_step(message):
         if (sex == u'Male') or (sex == u'Female'):
             user.sex = sex
         else:
-            raise Exception()
+            raise Exception("Unknown sex")
         bot.send_message(chat_id, 'Nice to meet you ' + user.name + '\n Age:' + str(user.age) + '\n Sex:' + user.sex)
     except Exception as e:
         bot.reply_to(message, 'oooops')
 
 
-bot.polling()
+# Enable saving next step handlers to file "./.handlers-saves/step.save".
+# Delay=2 means that after any change in next step handlers (e.g. calling register_next_step_handler())
+# saving will hapen after delay 2 seconds.
+bot.enable_save_next_step_handlers(delay=2)
+
+# Load next_step_handlers from save file (default "./.handlers-saves/step.save")
+# WARNING It will work only if enable_save_next_step_handlers was called!
+bot.load_next_step_handlers()
+
+bot.infinity_polling()

examples/telebot_bot/telebot_bot.py

@@ -3,9 +3,10 @@
 # and goes by the name 'TeleBot (@pyTeleBot)'. Join our group to talk to him!
 # WARNING: Tested with Python 2.7
 
-import telebot
 import os
 
+import telebot
+
 text_messages = {
     'welcome':
         u'Please welcome {name}!\n\n'
@@ -33,8 +34,10 @@ if "TELEBOT_BOT_TOKEN" not in os.environ or "GROUP_CHAT_ID" not in os.environ:
 bot = telebot.AsyncTeleBot(os.environ["TELEBOT_BOT_TOKEN"])
 GROUP_CHAT_ID = int(os.environ["GROUP_CHAT_ID"])
 
+
 def is_api_group(chat_id):
-    return chat_id== GROUP_CHAT_ID
+    return chat_id == GROUP_CHAT_ID
+
 
 @bot.message_handler(func=lambda m: True, content_types=['new_chat_participant'])
 def on_user_joins(message):
@@ -50,6 +53,7 @@ def on_user_joins(message):
 
     bot.reply_to(message, text_messages['welcome'].format(name=name))
 
+
 @bot.message_handler(commands=['info', 'help'])
 def on_info(message):
     if not is_api_group(message.chat.id):
@@ -58,21 +62,23 @@ def on_info(message):
 
     bot.reply_to(message, text_messages['info'])
 
+
 @bot.message_handler(commands=["ping"])
 def on_ping(message):
     bot.reply_to(message, "Still alive and kicking!")
 
+
 @bot.message_handler(commands=['start'])
 def on_start(message):
     if not is_api_group(message.chat.id):
         bot.reply_to(message, text_messages['wrong_chat'])
         return
 
+
 def listener(messages):
     for m in messages:
-        print str(m)
+        print(str(m))
+
 
 bot.set_update_listener(listener)
-bot.polling()
-
-
+bot.infinity_polling()

examples/webhook_examples/README.md

@@ -1,6 +1,6 @@
 # Webhook examples using pyTelegramBotAPI
 
-There are 3 examples in this directory using different libraries:
+There are 5 examples in this directory using different libraries:
 
 * **Python (CPython):** *webhook_cpython_echo_bot.py*
   * **Pros:**
@@ -32,5 +32,30 @@ There are 3 examples in this directory using different libraries:
     * The project seems not to be very active, latest version dates 2013.
     * They don't recommend to use it with Python 3, but may work.
     * May be a oversized for just handling webhook petitions.
+    
+* **aiohttp (1.2.0):** *webhook_aiohttp_echo_bot.py*
+  * **Pros:**
+    * It's a web application framework
+    * Python 3 compatible
+    * Asynchronous, excellent performance
+    * Utilizes new async/await syntax
+  * **Cons:**
+    * Requires Python 3.4.2+, don't work with Python 2
 
-*Latest update of this document: 2015-10-06*
+* **Twisted (20.3.0):** *webhook_twisted_echo_bot.py*
+  * **Pros:**
+    * Asynchronous event-driven networking engine
+    * Very high performance
+    * Built-in support for many internet protocols
+  * **Cons:**
+    * Twisted is low-level, which may be good or bad depending on use case
+    * Considerable learning curve - reading docs is a must.
+* **FastAPI(0.70.1):** *webhook_fastapi_echo_bot.py*
+  * **Pros:**
+    * Can be written for both sync and async
+    * Good documentation
+  * **Cons:**
+    * Requires python 3.6+
+    
+
+*Latest update of this document: 01-03-2022

examples/webhook_examples/webhook_aiohttp_echo_bot.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# This is a simple echo bot using decorators and webhook with aiohttp
+# It echoes any incoming text messages and does not use the polling method.
+
+import logging
+import ssl
+
+from aiohttp import web
+
+import telebot
+
+API_TOKEN = '<api_token>'
+
+WEBHOOK_HOST = '<ip/host where the bot is running>'
+WEBHOOK_PORT = 8443  # 443, 80, 88 or 8443 (port need to be 'open')
+WEBHOOK_LISTEN = '0.0.0.0'  # In some VPS you may need to put here the IP addr
+
+WEBHOOK_SSL_CERT = './webhook_cert.pem'  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out webhook_pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key webhook_pkey.pem -out webhook_cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+WEBHOOK_URL_BASE = "https://{}:{}".format(WEBHOOK_HOST, WEBHOOK_PORT)
+WEBHOOK_URL_PATH = "/{}/".format(API_TOKEN)
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.INFO)
+
+bot = telebot.TeleBot(API_TOKEN)
+
+app = web.Application()
+
+
+# Process webhook calls
+async def handle(request):
+    if request.match_info.get('token') == bot.token:
+        request_body_dict = await request.json()
+        update = telebot.types.Update.de_json(request_body_dict)
+        bot.process_new_updates([update])
+        return web.Response()
+    else:
+        return web.Response(status=403)
+
+
+app.router.add_post('/{token}/', handle)
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+def send_welcome(message):
+    bot.reply_to(message,
+                 ("Hi there, I am EchoBot.\n"
+                  "I am here to echo your kind words back to you."))
+
+
+# Handle all other messages
+@bot.message_handler(func=lambda message: True, content_types=['text'])
+def echo_message(message):
+    bot.reply_to(message, message.text)
+
+
+# Remove webhook, it fails sometimes the set if there is a previous webhook
+bot.remove_webhook()
+
+# Set webhook
+bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
+                certificate=open(WEBHOOK_SSL_CERT, 'r'))
+
+# Build ssl context
+context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
+context.load_cert_chain(WEBHOOK_SSL_CERT, WEBHOOK_SSL_PRIV)
+
+# Start aiohttp server
+web.run_app(
+    app,
+    host=WEBHOOK_LISTEN,
+    port=WEBHOOK_PORT,
+    ssl_context=context,
+)

examples/webhook_examples/webhook_cherrypy_echo_bot.py

@@ -4,10 +4,11 @@
 # This is a simple echo bot using decorators and webhook with CherryPy
 # It echoes any incoming text messages and does not use the polling method.
 
-import cherrypy
-import telebot
 import logging
 
+import cherrypy
+
+import telebot
 
 API_TOKEN = '<api_token>'
 
@@ -29,7 +30,6 @@ WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
 WEBHOOK_URL_BASE = "https://%s:%s" % (WEBHOOK_HOST, WEBHOOK_PORT)
 WEBHOOK_URL_PATH = "/%s/" % (API_TOKEN)
 
-
 logger = telebot.logger
 telebot.logger.setLevel(logging.INFO)
 
@@ -70,14 +70,19 @@ def echo_message(message):
 bot.remove_webhook()
 
 # Set webhook
-bot.set_webhook(url=WEBHOOK_URL_BASE+WEBHOOK_URL_PATH,
+bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
                 certificate=open(WEBHOOK_SSL_CERT, 'r'))
 
+# Disable CherryPy requests log
+access_log = cherrypy.log.access_log
+for handler in tuple(access_log.handlers):
+    access_log.removeHandler(handler)
+
 # Start cherrypy server
 cherrypy.config.update({
-    'server.socket_host': WEBHOOK_LISTEN,
-    'server.socket_port': WEBHOOK_PORT,
-    'server.ssl_module': 'builtin',
+    'server.socket_host'    : WEBHOOK_LISTEN,
+    'server.socket_port'    : WEBHOOK_PORT,
+    'server.ssl_module'     : 'builtin',
     'server.ssl_certificate': WEBHOOK_SSL_CERT,
     'server.ssl_private_key': WEBHOOK_SSL_PRIV
 })

examples/webhook_examples/webhook_cpython_echo_bot.py

@@ -4,11 +4,17 @@
 # This is a simple echo bot using decorators and webhook with BaseHTTPServer
 # It echoes any incoming text messages and does not use the polling method.
 
-import BaseHTTPServer
-import ssl
-import telebot
-import logging
+try:
+    # Python 2
+    from BaseHTTPServer import BaseHTTPRequestHandler, HTTPServer
+except ImportError:
+    # Python 3
+    from http.server import BaseHTTPRequestHandler, HTTPServer
 
+import logging
+import ssl
+
+import telebot
 
 API_TOKEN = '<api_token>'
 
@@ -30,7 +36,6 @@ WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
 WEBHOOK_URL_BASE = "https://%s:%s" % (WEBHOOK_HOST, WEBHOOK_PORT)
 WEBHOOK_URL_PATH = "/%s/" % (API_TOKEN)
 
-
 logger = telebot.logger
 telebot.logger.setLevel(logging.INFO)
 
@@ -38,7 +43,7 @@ bot = telebot.TeleBot(API_TOKEN)
 
 
 # WebhookHandler, process webhook calls
-class WebhookHandler(BaseHTTPServer.BaseHTTPRequestHandler):
+class WebhookHandler(BaseHTTPRequestHandler):
     server_version = "WebhookHandler/1.0"
 
     def do_HEAD(self):
@@ -81,15 +86,17 @@ def echo_message(message):
 
 
 # Remove webhook, it fails sometimes the set if there is a previous webhook
-bot.remove_webhook()
+#bot.remove_webhook()
 
 # Set webhook
-bot.set_webhook(url=WEBHOOK_URL_BASE+WEBHOOK_URL_PATH,
-                certificate=open(WEBHOOK_SSL_CERT, 'r'))
+# Beacuse telegram bot api server will check webhook server is alive.
+# Here we need set webhook after server started manually.
+#bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
+#                certificate=open(WEBHOOK_SSL_CERT, 'r'))
 
 # Start server
-httpd = BaseHTTPServer.HTTPServer((WEBHOOK_LISTEN, WEBHOOK_PORT),
-                                  WebhookHandler)
+httpd = HTTPServer((WEBHOOK_LISTEN, WEBHOOK_PORT),
+                   WebhookHandler)
 
 httpd.socket = ssl.wrap_socket(httpd.socket,
                                certfile=WEBHOOK_SSL_CERT,

examples/webhook_examples/webhook_fastapi_echo_bot.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# This is a simple echo bot using decorators and webhook with fastapi
+# It echoes any incoming text messages and does not use the polling method.
+
+import logging
+import fastapi
+import telebot
+
+API_TOKEN = 'TOKEN'
+
+WEBHOOK_HOST = '<ip/domain>'
+WEBHOOK_PORT = 8443  # 443, 80, 88 or 8443 (port need to be 'open')
+WEBHOOK_LISTEN = '0.0.0.0'  # In some VPS you may need to put here the IP addr
+
+WEBHOOK_SSL_CERT = './webhook_cert.pem'  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out webhook_pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key webhook_pkey.pem -out webhook_cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+WEBHOOK_URL_BASE = "https://{}:{}".format(WEBHOOK_HOST, WEBHOOK_PORT)
+WEBHOOK_URL_PATH = "/{}/".format(API_TOKEN)
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.INFO)
+
+bot = telebot.TeleBot(API_TOKEN)
+
+app = fastapi.FastAPI()
+
+
+# Process webhook calls
+@app.post(f'/{API_TOKEN}/')
+def process_webhook(update: dict):
+    if update:
+        update = telebot.types.Update.de_json(update)
+        bot.process_new_updates([update])
+    else:
+        return
+
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+def send_welcome(message):
+    bot.reply_to(message,
+                 ("Hi there, I am EchoBot.\n"
+                  "I am here to echo your kind words back to you."))
+
+
+# Handle all other messages
+@bot.message_handler(func=lambda message: True, content_types=['text'])
+def echo_message(message):
+    bot.reply_to(message, message.text)
+
+
+# Remove webhook, it fails sometimes the set if there is a previous webhook
+bot.remove_webhook()
+
+# Set webhook
+bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
+                certificate=open(WEBHOOK_SSL_CERT, 'r'))
+
+
+import uvicorn
+uvicorn.run(
+    app,
+    host=WEBHOOK_LISTEN,
+    port=WEBHOOK_PORT,
+    ssl_certfile=WEBHOOK_SSL_CERT,
+    ssl_keyfile=WEBHOOK_SSL_PRIV
+)

examples/webhook_examples/webhook_flask_echo_bot.py

@@ -4,10 +4,12 @@
 # This is a simple echo bot using decorators and webhook with flask
 # It echoes any incoming text messages and does not use the polling method.
 
-import flask
-import telebot
 import logging
+import time
 
+import flask
+
+import telebot
 
 API_TOKEN = '<api_token>'
 
@@ -29,7 +31,6 @@ WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
 WEBHOOK_URL_BASE = "https://%s:%s" % (WEBHOOK_HOST, WEBHOOK_PORT)
 WEBHOOK_URL_PATH = "/%s/" % (API_TOKEN)
 
-
 logger = telebot.logger
 telebot.logger.setLevel(logging.INFO)
 
@@ -48,9 +49,9 @@ def index():
 @app.route(WEBHOOK_URL_PATH, methods=['POST'])
 def webhook():
     if flask.request.headers.get('content-type') == 'application/json':
-        json_string = flask.request.get_data().encode('utf-8')
+        json_string = flask.request.get_data().decode('utf-8')
         update = telebot.types.Update.de_json(json_string)
-        bot.process_new_messages([update.message])
+        bot.process_new_updates([update])
         return ''
     else:
         flask.abort(403)
@@ -73,8 +74,10 @@ def echo_message(message):
 # Remove webhook, it fails sometimes the set if there is a previous webhook
 bot.remove_webhook()
 
+time.sleep(0.1)
+
 # Set webhook
-bot.set_webhook(url=WEBHOOK_URL_BASE+WEBHOOK_URL_PATH,
+bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
                 certificate=open(WEBHOOK_SSL_CERT, 'r'))
 
 # Start flask server

examples/webhook_examples/webhook_flask_heroku_echo.py

@@ -1,29 +1,38 @@
-import telebot
 import os
+
 from flask import Flask, request
 
-bot = telebot.TeleBot('<api_token>')
+import telebot
 
+TOKEN = '<api_token>'
+bot = telebot.TeleBot(TOKEN)
 server = Flask(__name__)
 
+
 @bot.message_handler(commands=['start'])
 def start(message):
     bot.reply_to(message, 'Hello, ' + message.from_user.first_name)
 
+
 @bot.message_handler(func=lambda message: True, content_types=['text'])
 def echo_message(message):
     bot.reply_to(message, message.text)
 
-@server.route("/bot", methods=['POST'])
+
+@server.route('/' + TOKEN, methods=['POST'])
 def getMessage():
-    bot.process_new_updates([telebot.types.Update.de_json(request.stream.read().decode("utf-8"))])
+    json_string = request.get_data().decode('utf-8')
+    update = telebot.types.Update.de_json(json_string)
+    bot.process_new_updates([update])
     return "!", 200
 
+
 @server.route("/")
 def webhook():
     bot.remove_webhook()
-    bot.set_webhook(url="https://herokuProject_url/bot")
+    bot.set_webhook(url='https://your_heroku_project.com/' + TOKEN)
     return "!", 200
 
-server.run(host="0.0.0.0", port=os.environ.get('PORT', 5000))
-server = Flask(__name__)
+
+if __name__ == "__main__":
+    server.run(host="0.0.0.0", port=int(os.environ.get('PORT', 5000)))

examples/webhook_examples/webhook_tornado_echo_bot.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# This example shows webhook echo bot with Tornado web framework
+# Documenation to Tornado: http://tornadoweb.org
+
+import signal
+
+import tornado.httpserver
+import tornado.ioloop
+import tornado.options
+import tornado.web
+
+import telebot
+
+API_TOKEN = '<api_token>'
+WEBHOOK_CERT = "./cert.pem"
+WEBHOOK_PKEY = "./pkey.pem"
+WEBHOOK_HOST = "<domain_or_ip>"
+WEBHOOK_SECRET = "<secret_uri_for_updates"
+WEBHOOK_PORT = 88
+WEBHOOK_URL_BASE = "https://{0}:{1}/{2}".format(WEBHOOK_HOST, str(WEBHOOK_PORT), WEBHOOK_SECRET)
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key pkey.pem -out cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+bot = telebot.TeleBot(API_TOKEN)
+
+
+class Root(tornado.web.RequestHandler):
+    def get(self):
+        self.write("Hi! This is webhook example!")
+        self.finish()
+
+
+class webhook_serv(tornado.web.RequestHandler):
+    def get(self):
+        self.write("What are you doing here?")
+        self.finish()
+
+    def post(self):
+        if "Content-Length" in self.request.headers and \
+            "Content-Type" in self.request.headers and \
+            self.request.headers['Content-Type'] == "application/json":
+
+            # length = int(self.request.headers['Content-Length'])
+            json_data = self.request.body.decode("utf-8")
+            update = telebot.types.Update.de_json(json_data)
+            bot.process_new_updates([update])
+            self.write("")
+            self.finish()
+        else:
+            self.write("What are you doing here?")
+            self.finish()
+
+
+tornado.options.define("port", default=WEBHOOK_PORT, help="run on the given port", type=int)
+is_closing = False
+
+
+def signal_handler(signum, frame):
+    global is_closing
+    print("Exiting...")
+    is_closing = True
+
+
+def try_exit():
+    global is_closing
+    if is_closing:
+        # clean up here
+        tornado.ioloop.IOLoop.instance().stop()
+        print("Exit success!")
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+def send_welcome(message):
+    bot.reply_to(message,
+                 ("Hi there, I am EchoBot.\n"
+                  "I am here to echo your kind words back to you."))
+
+
+bot.remove_webhook()
+bot.set_webhook(url=WEBHOOK_URL_BASE,
+                certificate=open(WEBHOOK_CERT, 'r'))
+tornado.options.options.logging = None
+tornado.options.parse_command_line()
+signal.signal(signal.SIGINT, signal_handler)
+application = tornado.web.Application([
+    (r"/", Root),
+    (r"/" + WEBHOOK_SECRET, webhook_serv)
+])
+
+http_server = tornado.httpserver.HTTPServer(application, ssl_options={
+    "certfile": WEBHOOK_CERT,
+    "keyfile" : WEBHOOK_PKEY,
+})
+http_server.listen(tornado.options.options.port)
+tornado.ioloop.PeriodicCallback(try_exit, 100).start()
+tornado.ioloop.IOLoop.instance().start()

examples/webhook_examples/webhook_twisted_echo_bot.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# This is an example echo bot using webhook with Twisted network framework.
+# Updates are received with Twisted web server and processed in reactor thread pool.
+# Relevant docs:
+# https://twistedmatrix.com/documents/current/core/howto/reactor-basics.html
+# https://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html
+
+import logging
+import telebot
+import json
+from twisted.internet import ssl, reactor
+from twisted.web.resource import Resource, ErrorPage
+from twisted.web.server import Site, Request
+
+API_TOKEN = '<api_token>'
+
+WEBHOOK_HOST = '<ip or hostname>'
+WEBHOOK_PORT = 8443  # 443, 80, 88 or 8443 (port need to be 'open')
+WEBHOOK_LISTEN = '0.0.0.0'  # In some VPS you may need to put here the IP addr
+
+WEBHOOK_SSL_CERT = './webhook_cert.pem'  # Path to the ssl certificate
+WEBHOOK_SSL_PRIV = './webhook_pkey.pem'  # Path to the ssl private key
+
+# Quick'n'dirty SSL certificate generation:
+#
+# openssl genrsa -out webhook_pkey.pem 2048
+# openssl req -new -x509 -days 3650 -key webhook_pkey.pem -out webhook_cert.pem
+#
+# When asked for "Common Name (e.g. server FQDN or YOUR name)" you should reply
+# with the same value in you put in WEBHOOK_HOST
+
+WEBHOOK_URL_BASE = "https://{}:{}".format(WEBHOOK_HOST, WEBHOOK_PORT)
+WEBHOOK_URL_PATH = "/{}/".format(API_TOKEN)
+
+logger = telebot.logger
+telebot.logger.setLevel(logging.INFO)
+bot = telebot.TeleBot(API_TOKEN)
+
+
+# Handle '/start' and '/help'
+@bot.message_handler(commands=['help', 'start'])
+def send_welcome(message):
+    bot.reply_to(message,
+                 ("Hi there, I am EchoBot.\n"
+                  "I am here to echo your kind words back to you."))
+
+
+# Handle all other messages
+@bot.message_handler(func=lambda message: True, content_types=['text'])
+def echo_message(message):
+    bot.reply_to(message, message.text)
+
+
+# Remove webhook, it fails sometimes the set if there is a previous webhook
+bot.remove_webhook()
+
+# Set webhook
+bot.set_webhook(url=WEBHOOK_URL_BASE + WEBHOOK_URL_PATH,
+                certificate=open(WEBHOOK_SSL_CERT, 'r'))
+
+
+# Process webhook calls
+class WebhookHandler(Resource):
+    isLeaf = True
+    def render_POST(self, request: Request):
+        request_body_dict = json.load(request.content)
+        update = telebot.types.Update.de_json(request_body_dict)
+        reactor.callInThread(lambda: bot.process_new_updates([update]))
+        return b''
+
+
+root = ErrorPage(403, 'Forbidden', '')
+root.putChild(API_TOKEN.encode(), WebhookHandler())
+site = Site(root)
+sslcontext = ssl.DefaultOpenSSLContextFactory(WEBHOOK_SSL_PRIV, WEBHOOK_SSL_CERT)
+reactor.listenSSL(8443, site, sslcontext)
+reactor.run()

requirements.txt

@@ -1,5 +1,4 @@
-py==1.4.29
 pytest==3.0.2
-requests==2.7.0
-six==1.9.0
+requests==2.20.0
 wheel==0.24.0
+aiohttp>=3.8.0,<3.9.0

setup.py

@@ -1,30 +1,35 @@
 #!/usr/bin/env python
 from setuptools import setup
 from io import open
+import re
 
-def readme():
-    with open('README.rst', encoding='utf-8') as f:
-        return f.read()
+def read(filename):
+    with open(filename, encoding='utf-8') as file:
+        return file.read()
+
+with open('telebot/version.py', 'r', encoding='utf-8') as f:  # Credits: LonamiWebs
+    version = re.search(r"^__version__\s*=\s*'(.*)'.*$",
+                        f.read(), flags=re.MULTILINE).group(1)
 
 setup(name='pyTelegramBotAPI',
-      version='2.2.3',
+      version=version,
       description='Python Telegram bot api. ',
-      long_description=readme(),
+      long_description=read('README.md'),
+      long_description_content_type="text/markdown",
       author='eternnoir',
       author_email='eternnoir@gmail.com',
       url='https://github.com/eternnoir/pyTelegramBotAPI',
       packages=['telebot'],
       license='GPL2',
       keywords='telegram bot api tools',
-      install_requires=['requests', 'six'],
+      install_requires=['requests'],
       extras_require={
           'json': 'ujson',
+          'PIL': 'Pillow',
+          'redis': 'redis>=3.4.1'
       },
       classifiers=[
           'Development Status :: 5 - Production/Stable',
-          'Programming Language :: Python :: 2',
-          'Programming Language :: Python :: 2.6',
-          'Programming Language :: Python :: 2.7',
           'Programming Language :: Python :: 3',
           'Environment :: Console',
           'License :: OSI Approved :: GNU General Public License v2 (GPLv2)',

telebot/asyncio_filters.py

@@ -0,0 +1,178 @@
+from abc import ABC
+
+class SimpleCustomFilter(ABC):
+    """
+    Simple Custom Filter base class.
+    Create child class with check() method.
+    Accepts only message, returns bool value, that is compared with given in handler.
+    """
+
+    async def check(self, message):
+        """
+        Perform a check.
+        """
+        pass
+
+
+class AdvancedCustomFilter(ABC):
+    """
+    Simple Custom Filter base class.
+    Create child class with check() method.
+    Accepts two parameters, returns bool: True - filter passed, False - filter failed.
+    message: Message class
+    text: Filter value given in handler
+    """
+
+    async def check(self, message, text):
+        """
+        Perform a check.
+        """
+        pass
+
+
+class TextMatchFilter(AdvancedCustomFilter):
+    """
+    Filter to check Text message.
+    key: text
+
+    Example:
+    @bot.message_handler(text=['account'])
+    """
+
+    key = 'text'
+
+    async def check(self, message, text):
+        if type(text) is list:return message.text in text
+        else: return text == message.text
+
+class TextContainsFilter(AdvancedCustomFilter):
+    """
+    Filter to check Text message.
+    key: text
+
+    Example:
+    # Will respond if any message.text contains word 'account'
+    @bot.message_handler(text_contains=['account'])
+    """
+
+    key = 'text_contains'
+
+    async def check(self, message, text):
+        return text in message.text
+
+class TextStartsFilter(AdvancedCustomFilter):
+    """
+    Filter to check whether message starts with some text.
+
+    Example:
+    # Will work if message.text starts with 'Sir'.
+    @bot.message_handler(text_startswith='Sir')
+    """
+
+    key = 'text_startswith'
+    async def check(self, message, text):
+        return message.text.startswith(text) 
+
+class ChatFilter(AdvancedCustomFilter):
+    """
+    Check whether chat_id corresponds to given chat_id.
+
+    Example:
+    @bot.message_handler(chat_id=[99999])
+    """
+
+    key = 'chat_id'
+    async def check(self, message, text):
+        return message.chat.id in text
+
+class ForwardFilter(SimpleCustomFilter):
+    """
+    Check whether message was forwarded from channel or group.
+
+    Example:
+
+    @bot.message_handler(is_forwarded=True)
+    """
+
+    key = 'is_forwarded'
+
+    async def check(self, message):
+        return message.forward_from_chat is not None
+
+class IsReplyFilter(SimpleCustomFilter):
+    """
+    Check whether message is a reply.
+
+    Example:
+
+    @bot.message_handler(is_reply=True)
+    """
+
+    key = 'is_reply'
+
+    async def check(self, message):
+        return message.reply_to_message is not None
+
+
+
+class LanguageFilter(AdvancedCustomFilter):
+    """
+    Check users language_code.
+
+    Example:
+
+    @bot.message_handler(language_code=['ru'])
+    """
+
+    key = 'language_code'
+
+    async def check(self, message, text):
+        if type(text) is list:return message.from_user.language_code in text
+        else: return message.from_user.language_code == text
+
+class IsAdminFilter(SimpleCustomFilter):
+    """
+    Check whether the user is administrator / owner of the chat.
+
+    Example:
+    @bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
+    """
+
+    key = 'is_chat_admin'
+
+    def __init__(self, bot):
+        self._bot = bot
+
+    async def check(self, message):
+        result = await self._bot.get_chat_member(message.chat.id, message.from_user.id)
+        return result.status in ['creator', 'administrator']
+
+class StateFilter(AdvancedCustomFilter):
+    """
+    Filter to check state.
+
+    Example:
+    @bot.message_handler(state=1)
+    """
+    def __init__(self, bot):
+        self.bot = bot
+    key = 'state'
+
+    async def check(self, message, text):
+        result = await self.bot.current_states.current_state(message.from_user.id)
+        if result is False: return False
+        elif text == '*': return True
+        elif type(text) is list: return result in text
+        return result == text
+
+class IsDigitFilter(SimpleCustomFilter):
+    """
+    Filter to check whether the string is made up of only digits.
+
+    Example:
+    @bot.message_handler(is_digit=True)
+    """
+    key = 'is_digit'
+
+    async def check(self, message):
+        return message.text.isdigit()

telebot/asyncio_handler_backends.py

@@ -0,0 +1,219 @@
+import os
+import pickle
+
+
+
+class StateMemory:
+    def __init__(self):
+        self._states = {}
+
+    async def add_state(self, chat_id, state):
+        """
+        Add a state.
+        :param chat_id:
+        :param state: new state
+        """
+        if chat_id in self._states:
+            
+            self._states[chat_id]['state'] = state
+        else:
+            self._states[chat_id] = {'state': state,'data': {}}
+
+    async def current_state(self, chat_id):
+        """Current state"""
+        if chat_id in self._states: return self._states[chat_id]['state']
+        else: return False
+
+    async def delete_state(self, chat_id):
+        """Delete a state"""
+        self._states.pop(chat_id)
+
+    def get_data(self, chat_id):
+        return self._states[chat_id]['data']
+
+    async def set(self, chat_id, new_state):
+        """
+        Set a new state for a user.
+        :param chat_id:
+        :param new_state: new_state of a user
+        """
+        await self.add_state(chat_id,new_state)
+
+    async def add_data(self, chat_id, key, value):
+        result = self._states[chat_id]['data'][key] = value
+        return result
+
+    async def finish(self, chat_id):
+        """
+        Finish(delete) state of a user.
+        :param chat_id:
+        """
+        await self.delete_state(chat_id)
+
+    def retrieve_data(self, chat_id):
+        """
+        Save input text.
+
+        Usage:
+        with bot.retrieve_data(message.chat.id) as data:
+            data['name'] = message.text
+
+        Also, at the end of your 'Form' you can get the name:
+        data['name']
+        """
+        return StateContext(self, chat_id)
+
+
+class StateFile:
+    """
+    Class to save states in a file.
+    """
+    def __init__(self, filename):
+        self.file_path = filename
+
+    async def add_state(self, chat_id, state):
+        """
+        Add a state.
+        :param chat_id:
+        :param state: new state
+        """
+        states_data = self.read_data()
+        if chat_id in states_data:
+            states_data[chat_id]['state'] = state
+            return await self.save_data(states_data)
+        else:
+            states_data[chat_id] = {'state': state,'data': {}}
+            return await self.save_data(states_data)
+
+
+    async def current_state(self, chat_id):
+        """Current state."""
+        states_data = self.read_data()
+        if chat_id in states_data: return states_data[chat_id]['state']
+        else: return False
+
+    async def delete_state(self, chat_id):
+        """Delete a state"""
+        states_data = self.read_data()
+        states_data.pop(chat_id)
+        await self.save_data(states_data)
+
+    def read_data(self):
+        """
+        Read the data from file.
+        """
+        file = open(self.file_path, 'rb')
+        states_data = pickle.load(file)
+        file.close()
+        return states_data
+
+    def create_dir(self):
+        """
+        Create directory .save-handlers.
+        """
+        dirs = self.file_path.rsplit('/', maxsplit=1)[0]
+        os.makedirs(dirs, exist_ok=True)
+        if not os.path.isfile(self.file_path):
+            with open(self.file_path,'wb') as file:
+                pickle.dump({}, file)
+        
+    async def save_data(self, new_data):
+        """
+        Save data after editing.
+        :param new_data:
+        """
+        with open(self.file_path, 'wb+') as state_file:
+            pickle.dump(new_data, state_file, protocol=pickle.HIGHEST_PROTOCOL)
+        return True
+
+    def get_data(self, chat_id):
+        return self.read_data()[chat_id]['data']
+
+    async def set(self, chat_id, new_state):
+        """
+        Set a new state for a user.
+        :param chat_id:
+        :param new_state: new_state of a user
+        
+        """
+        await self.add_state(chat_id,new_state)
+
+    async def add_data(self, chat_id, key, value):
+        states_data = self.read_data()
+        result = states_data[chat_id]['data'][key] = value
+        await self.save_data(result)
+
+        return result
+
+    async def finish(self, chat_id):
+        """
+        Finish(delete) state of a user.
+        :param chat_id:
+        """
+        await self.delete_state(chat_id)
+
+    def retrieve_data(self, chat_id):
+        """
+        Save input text.
+
+        Usage:
+        with bot.retrieve_data(message.chat.id) as data:
+            data['name'] = message.text
+
+        Also, at the end of your 'Form' you can get the name:
+        data['name']
+        """
+        return StateFileContext(self, chat_id)
+
+
+class StateContext:
+    """
+    Class for data.
+    """
+    def __init__(self , obj: StateMemory, chat_id) -> None:
+        self.obj = obj
+        self.chat_id = chat_id
+        self.data = obj.get_data(chat_id)
+
+    async def __aenter__(self):
+        return self.data
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        return
+
+class StateFileContext:
+    """
+    Class for data.
+    """
+    def __init__(self , obj: StateFile, chat_id) -> None:
+        self.obj = obj
+        self.chat_id = chat_id
+        self.data = None
+
+    async def __aenter__(self):
+        self.data = self.obj.get_data(self.chat_id)
+        return self.data
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        old_data = self.obj.read_data()
+        for i in self.data:
+            old_data[self.chat_id]['data'][i] = self.data.get(i)
+        await self.obj.save_data(old_data)
+
+        return
+
+
+class BaseMiddleware:
+    """
+    Base class for middleware.
+
+    Your middlewares should be inherited from this class.
+    """
+    def __init__(self):
+        pass
+
+    async def pre_process(self, message, data):
+        raise NotImplementedError
+    async def post_process(self, message, data, exception):
+        raise NotImplementedError
+

telebot/callback_data.py

@@ -0,0 +1,115 @@
+import typing
+
+
+class CallbackDataFilter:
+
+    def __init__(self, factory, config: typing.Dict[str, str]):
+        self.config = config
+        self.factory = factory
+
+    def check(self, query):
+        """
+        Checks if query.data appropriates to specified config
+        :param query: telebot.types.CallbackQuery
+        :return: bool
+        """
+
+        try:
+            data = self.factory.parse(query.data)
+        except ValueError:
+            return False
+
+        for key, value in self.config.items():
+            if isinstance(value, (list, tuple, set, frozenset)):
+                if data.get(key) not in value:
+                    return False
+            elif data.get(key) != value:
+                return False
+        return True
+
+
+class CallbackData:
+    """
+    Callback data factory
+    This class will help you to work with CallbackQuery
+    """
+
+    def __init__(self, *parts, prefix: str, sep=':'):
+        if not isinstance(prefix, str):
+            raise TypeError(f'Prefix must be instance of str not {type(prefix).__name__}')
+        if not prefix:
+            raise ValueError("Prefix can't be empty")
+        if sep in prefix:
+            raise ValueError(f"Separator {sep!r} can't be used in prefix")
+
+        self.prefix = prefix
+        self.sep = sep
+
+        self._part_names = parts
+
+    def new(self, *args, **kwargs) -> str:
+        """
+        Generate callback data
+        :param args: positional parameters of CallbackData instance parts
+        :param kwargs: named parameters
+        :return: str
+        """
+        args = list(args)
+
+        data = [self.prefix]
+
+        for part in self._part_names:
+            value = kwargs.pop(part, None)
+            if value is None:
+                if args:
+                    value = args.pop(0)
+                else:
+                    raise ValueError(f'Value for {part!r} was not passed!')
+
+            if value is not None and not isinstance(value, str):
+                value = str(value)
+
+            if self.sep in value:
+                raise ValueError(f"Symbol {self.sep!r} is defined as the separator and can't be used in parts' values")
+
+            data.append(value)
+
+        if args or kwargs:
+            raise TypeError('Too many arguments were passed!')
+
+        callback_data = self.sep.join(data)
+
+        if len(callback_data.encode()) > 64:
+            raise ValueError('Resulted callback data is too long!')
+
+        return callback_data
+
+    def parse(self, callback_data: str) -> typing.Dict[str, str]:
+        """
+        Parse data from the callback data
+        :param callback_data: string, use to telebot.types.CallbackQuery to parse it from string to a dict
+        :return: dict parsed from callback data
+        """
+
+        prefix, *parts = callback_data.split(self.sep)
+        if prefix != self.prefix:
+            raise ValueError("Passed callback data can't be parsed with that prefix.")
+        elif len(parts) != len(self._part_names):
+            raise ValueError('Invalid parts count!')
+
+        result = {'@': prefix}
+        result.update(zip(self._part_names, parts))
+        return result
+
+    def filter(self, **config) -> CallbackDataFilter:
+        """
+        Generate filter
+
+        :param config: specified named parameters will be checked with CallbackQury.data
+        :return: CallbackDataFilter class
+        """
+
+        for key in config.keys():
+            if key not in self._part_names:
+                raise ValueError(f'Invalid field name {key!r}')
+        return CallbackDataFilter(self, config)

telebot/custom_filters.py

@@ -0,0 +1,176 @@
+from abc import ABC
+
+class SimpleCustomFilter(ABC):
+    """
+    Simple Custom Filter base class.
+    Create child class with check() method.
+    Accepts only message, returns bool value, that is compared with given in handler.
+    """
+
+    def check(self, message):
+        """
+        Perform a check.
+        """
+        pass
+
+
+class AdvancedCustomFilter(ABC):
+    """
+    Simple Custom Filter base class.
+    Create child class with check() method.
+    Accepts two parameters, returns bool: True - filter passed, False - filter failed.
+    message: Message class
+    text: Filter value given in handler
+    """
+
+    def check(self, message, text):
+        """
+        Perform a check.
+        """
+        pass
+
+
+class TextMatchFilter(AdvancedCustomFilter):
+    """
+    Filter to check Text message.
+    key: text
+
+    Example:
+    @bot.message_handler(text=['account'])
+    """
+
+    key = 'text'
+
+    def check(self, message, text):
+        if type(text) is list:return message.text in text
+        else: return text == message.text
+
+class TextContainsFilter(AdvancedCustomFilter):
+    """
+    Filter to check Text message.
+    key: text
+
+    Example:
+    # Will respond if any message.text contains word 'account'
+    @bot.message_handler(text_contains=['account'])
+    """
+
+    key = 'text_contains'
+
+    def check(self, message, text):
+        return text in message.text
+
+class TextStartsFilter(AdvancedCustomFilter):
+    """
+    Filter to check whether message starts with some text.
+
+    Example:
+    # Will work if message.text starts with 'Sir'.
+    @bot.message_handler(text_startswith='Sir')
+    """
+
+    key = 'text_startswith'
+    def check(self, message, text):
+        return message.text.startswith(text) 
+
+class ChatFilter(AdvancedCustomFilter):
+    """
+    Check whether chat_id corresponds to given chat_id.
+
+    Example:
+    @bot.message_handler(chat_id=[99999])
+    """
+
+    key = 'chat_id'
+    def check(self, message, text):
+        return message.chat.id in text
+
+class ForwardFilter(SimpleCustomFilter):
+    """
+    Check whether message was forwarded from channel or group.
+
+    Example:
+
+    @bot.message_handler(is_forwarded=True)
+    """
+
+    key = 'is_forwarded'
+
+    def check(self, message):
+        return message.forward_from_chat is not None
+
+class IsReplyFilter(SimpleCustomFilter):
+    """
+    Check whether message is a reply.
+
+    Example:
+
+    @bot.message_handler(is_reply=True)
+    """
+
+    key = 'is_reply'
+
+    def check(self, message):
+        return message.reply_to_message is not None
+
+
+
+class LanguageFilter(AdvancedCustomFilter):
+    """
+    Check users language_code.
+
+    Example:
+
+    @bot.message_handler(language_code=['ru'])
+    """
+
+    key = 'language_code'
+
+    def check(self, message, text):
+        if type(text) is list:return message.from_user.language_code in text
+        else: return message.from_user.language_code == text
+
+class IsAdminFilter(SimpleCustomFilter):
+    """
+    Check whether the user is administrator / owner of the chat.
+
+    Example:
+    @bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
+    """
+
+    key = 'is_chat_admin'
+
+    def __init__(self, bot):
+        self._bot = bot
+
+    def check(self, message):
+        return self._bot.get_chat_member(message.chat.id, message.from_user.id).status in ['creator', 'administrator']
+
+class StateFilter(AdvancedCustomFilter):
+    """
+    Filter to check state.
+
+    Example:
+    @bot.message_handler(state=1)
+    """
+    def __init__(self, bot):
+        self.bot = bot
+    key = 'state'
+
+    def check(self, message, text):
+        if self.bot.current_states.current_state(message.from_user.id) is False: return False
+        elif text == '*': return True
+        elif type(text) is list: return self.bot.current_states.current_state(message.from_user.id) in text
+        return self.bot.current_states.current_state(message.from_user.id) == text
+
+class IsDigitFilter(SimpleCustomFilter):
+    """
+    Filter to check whether the string is made up of only digits.
+
+    Example:
+    @bot.message_handler(is_digit=True)
+    """
+    key = 'is_digit'
+
+    def check(self, message):
+        return message.text.isdigit()

telebot/handler_backends.py

@@ -0,0 +1,339 @@
+import os
+import pickle
+import threading
+
+from telebot import apihelper
+
+
+class HandlerBackend(object):
+    """
+    Class for saving (next step|reply) handlers
+    """
+    def __init__(self, handlers=None):
+        if handlers is None:
+            handlers = {}
+        self.handlers = handlers
+
+    def register_handler(self, handler_group_id, handler):
+        raise NotImplementedError()
+
+    def clear_handlers(self, handler_group_id):
+        raise NotImplementedError()
+
+    def get_handlers(self, handler_group_id):
+        raise NotImplementedError()
+
+
+class MemoryHandlerBackend(HandlerBackend):
+    def register_handler(self, handler_group_id, handler):
+        if handler_group_id in self.handlers:
+            self.handlers[handler_group_id].append(handler)
+        else:
+            self.handlers[handler_group_id] = [handler]
+
+    def clear_handlers(self, handler_group_id):
+        self.handlers.pop(handler_group_id, None)
+
+    def get_handlers(self, handler_group_id):
+        return self.handlers.pop(handler_group_id, None)
+
+    def load_handlers(self, filename, del_file_after_loading):
+        raise NotImplementedError()
+
+
+class FileHandlerBackend(HandlerBackend):
+    def __init__(self, handlers=None, filename='./.handler-saves/handlers.save', delay=120):
+        super(FileHandlerBackend, self).__init__(handlers)
+        self.filename = filename
+        self.delay = delay
+        self.timer = threading.Timer(delay, self.save_handlers)
+
+    def register_handler(self, handler_group_id, handler):
+        if handler_group_id in self.handlers:
+            self.handlers[handler_group_id].append(handler)
+        else:
+            self.handlers[handler_group_id] = [handler]
+        self.start_save_timer()
+
+    def clear_handlers(self, handler_group_id):
+        self.handlers.pop(handler_group_id, None)
+        self.start_save_timer()
+
+    def get_handlers(self, handler_group_id):
+        handlers = self.handlers.pop(handler_group_id, None)
+        self.start_save_timer()
+        return handlers
+
+    def start_save_timer(self):
+        if not self.timer.is_alive():
+            if self.delay <= 0:
+                self.save_handlers()
+            else:
+                self.timer = threading.Timer(self.delay, self.save_handlers)
+                self.timer.start()
+
+    def save_handlers(self):
+        self.dump_handlers(self.handlers, self.filename)
+
+    def load_handlers(self, filename=None, del_file_after_loading=True):
+        if not filename:
+            filename = self.filename
+        tmp = self.return_load_handlers(filename, del_file_after_loading=del_file_after_loading)
+        if tmp is not None:
+            self.handlers.update(tmp)
+
+    @staticmethod
+    def dump_handlers(handlers, filename, file_mode="wb"):
+        dirs = filename.rsplit('/', maxsplit=1)[0]
+        os.makedirs(dirs, exist_ok=True)
+
+        with open(filename + ".tmp", file_mode) as file:
+            if (apihelper.CUSTOM_SERIALIZER is None):
+                pickle.dump(handlers, file)
+            else:
+                apihelper.CUSTOM_SERIALIZER.dump(handlers, file)
+
+        if os.path.isfile(filename):
+            os.remove(filename)
+
+        os.rename(filename + ".tmp", filename)
+
+    @staticmethod
+    def return_load_handlers(filename, del_file_after_loading=True):
+        if os.path.isfile(filename) and os.path.getsize(filename) > 0:
+            with open(filename, "rb") as file:
+                if (apihelper.CUSTOM_SERIALIZER is None):
+                    handlers = pickle.load(file)
+                else:
+                    handlers = apihelper.CUSTOM_SERIALIZER.load(file)
+
+            if del_file_after_loading:
+                os.remove(filename)
+
+            return handlers
+
+
+class RedisHandlerBackend(HandlerBackend):
+    def __init__(self, handlers=None, host='localhost', port=6379, db=0, prefix='telebot', password=None):
+        super(RedisHandlerBackend, self).__init__(handlers)
+        from redis import Redis
+        self.prefix = prefix
+        self.redis = Redis(host, port, db, password)
+
+    def _key(self, handle_group_id):
+        return ':'.join((self.prefix, str(handle_group_id)))
+
+    def register_handler(self, handler_group_id, handler):
+        handlers = []
+        value = self.redis.get(self._key(handler_group_id))
+        if value:
+            handlers = pickle.loads(value)
+        handlers.append(handler)
+        self.redis.set(self._key(handler_group_id), pickle.dumps(handlers))
+
+    def clear_handlers(self, handler_group_id):
+        self.redis.delete(self._key(handler_group_id))
+
+    def get_handlers(self, handler_group_id):
+        handlers = None
+        value = self.redis.get(self._key(handler_group_id))
+        if value:
+            handlers = pickle.loads(value)
+            self.clear_handlers(handler_group_id)
+        return handlers
+
+
+class StateMemory:
+    def __init__(self):
+        self._states = {}
+
+    def add_state(self, chat_id, state):
+        """
+        Add a state.
+        :param chat_id:
+        :param state: new state
+        """
+        if chat_id in self._states:
+            
+            self._states[chat_id]['state'] = state
+        else:
+            self._states[chat_id] = {'state': state,'data': {}}
+
+    def current_state(self, chat_id):
+        """Current state"""
+        if chat_id in self._states: return self._states[chat_id]['state']
+        else: return False
+
+    def delete_state(self, chat_id):
+        """Delete a state"""
+        self._states.pop(chat_id)
+
+    def get_data(self, chat_id):
+        return self._states[chat_id]['data']
+
+    def set(self, chat_id, new_state):
+        """
+        Set a new state for a user.
+        :param chat_id:
+        :param new_state: new_state of a user
+        """
+        self.add_state(chat_id,new_state)
+
+    def add_data(self, chat_id, key, value):
+        result = self._states[chat_id]['data'][key] = value
+        return result
+
+    def finish(self, chat_id):
+        """
+        Finish(delete) state of a user.
+        :param chat_id:
+        """
+        self.delete_state(chat_id)
+
+    def retrieve_data(self, chat_id):
+        """
+        Save input text.
+
+        Usage:
+        with bot.retrieve_data(message.chat.id) as data:
+            data['name'] = message.text
+
+        Also, at the end of your 'Form' you can get the name:
+        data['name']
+        """
+        return StateContext(self, chat_id)
+
+
+class StateFile:
+    """
+    Class to save states in a file.
+    """
+    def __init__(self, filename):
+        self.file_path = filename
+
+    def add_state(self, chat_id, state):
+        """
+        Add a state.
+        :param chat_id:
+        :param state: new state
+        """
+        states_data = self.read_data()
+        if chat_id in states_data:
+            states_data[chat_id]['state'] = state
+            return self.save_data(states_data)
+        else:
+            states_data[chat_id] = {'state': state,'data': {}}
+            return self.save_data(states_data)
+
+    def current_state(self, chat_id):
+        """Current state."""
+        states_data = self.read_data()
+        if chat_id in states_data: return states_data[chat_id]['state']
+        else: return False
+
+    def delete_state(self, chat_id):
+        """Delete a state"""
+        states_data = self.read_data()
+        states_data.pop(chat_id)
+        self.save_data(states_data)
+
+    def read_data(self):
+        """
+        Read the data from file.
+        """
+        file = open(self.file_path, 'rb')
+        states_data = pickle.load(file)
+        file.close()
+        return states_data
+
+    def create_dir(self):
+        """
+        Create directory .save-handlers.
+        """
+        dirs = self.file_path.rsplit('/', maxsplit=1)[0]
+        os.makedirs(dirs, exist_ok=True)
+        if not os.path.isfile(self.file_path):
+            with open(self.file_path,'wb') as file:
+                pickle.dump({}, file)
+        
+    def save_data(self, new_data):
+        """
+        Save data after editing.
+        :param new_data:
+        """
+        with open(self.file_path, 'wb+') as state_file:
+            pickle.dump(new_data, state_file, protocol=pickle.HIGHEST_PROTOCOL)
+        return True
+
+    def get_data(self, chat_id):
+        return self.read_data()[chat_id]['data']
+
+    def set(self, chat_id, new_state):
+        """
+        Set a new state for a user.
+        :param chat_id:
+        :param new_state: new_state of a user
+        """
+        self.add_state(chat_id,new_state)
+
+    def add_data(self, chat_id, key, value):
+        states_data = self.read_data()
+        result = states_data[chat_id]['data'][key] = value
+        self.save_data(result)
+        return result
+
+    def finish(self, chat_id):
+        """
+        Finish(delete) state of a user.
+        :param chat_id:
+        """
+        self.delete_state(chat_id)
+
+    def retrieve_data(self, chat_id):
+        """
+        Save input text.
+
+        Usage:
+        with bot.retrieve_data(message.chat.id) as data:
+            data['name'] = message.text
+
+        Also, at the end of your 'Form' you can get the name:
+        data['name']
+        """
+        return StateFileContext(self, chat_id)
+
+
+class StateContext:
+    """
+    Class for data.
+    """
+    def __init__(self , obj: StateMemory, chat_id) -> None:
+        self.obj = obj
+        self.chat_id = chat_id
+        self.data = obj.get_data(chat_id)
+
+    def __enter__(self):
+        return self.data
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return
+
+
+class StateFileContext:
+    """
+    Class for data.
+    """
+    def __init__(self , obj: StateFile, chat_id) -> None:
+        self.obj = obj
+        self.chat_id = chat_id
+        self.data = self.obj.get_data(self.chat_id)
+
+    def __enter__(self):
+        return self.data
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        old_data = self.obj.read_data()
+        for i in self.data:
+            old_data[self.chat_id]['data'][i] = self.data.get(i)
+        self.obj.save_data(old_data)
+        return

telebot/util.py

@@ -1,83 +1,116 @@
 # -*- coding: utf-8 -*-
-
-import threading
+import random
 import re
-import sys
-import six
-from six import string_types
+import string
+import threading
+import traceback
+import warnings
+from typing import Any, Callable, List, Dict, Optional, Union
 
-# Python3 queue support.
+# noinspection PyPep8Naming
+import queue as Queue
+import logging
+
+from telebot import types
 
 try:
-    import Queue
+    import ujson as json
 except ImportError:
-    import queue as Queue
+    import json
 
-from telebot import logger
+try:
+    # noinspection PyPackageRequirements
+    from PIL import Image
+    from io import BytesIO
+    pil_imported = True
+except:
+    pil_imported = False
 
+MAX_MESSAGE_LENGTH = 4096
+
+logger = logging.getLogger('TeleBot')
+
+thread_local = threading.local()
+
+content_type_media = [
+    'text', 'audio', 'animation', 'document', 'photo', 'sticker', 'video', 'video_note', 'voice', 'contact', 'dice', 'poll',
+    'venue', 'location'
+]
+
+content_type_service = [
+    'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
+    'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
+    'proximity_alert_triggered', 'voice_chat_scheduled', 'voice_chat_started', 'voice_chat_ended', 
+    'voice_chat_participants_invited', 'message_auto_delete_timer_changed'
+]
+
+update_types = [
+    "update_id", "message", "edited_message", "channel_post", "edited_channel_post", "inline_query", 
+    "chosen_inline_result", "callback_query", "shipping_query", "pre_checkout_query", "poll", "poll_answer", 
+    "my_chat_member", "chat_member", "chat_join_request"
+]
 
 class WorkerThread(threading.Thread):
-        count = 0
+    count = 0
 
-        def __init__(self, exception_callback=None, queue=None, name=None):
-            if not name:
-                name = "WorkerThread{0}".format(self.__class__.count + 1)
-                self.__class__.count += 1
-            if not queue:
-                queue = Queue.Queue()
+    def __init__(self, exception_callback=None, queue=None, name=None):
+        if not name:
+            name = "WorkerThread{0}".format(self.__class__.count + 1)
+            self.__class__.count += 1
+        if not queue:
+            queue = Queue.Queue()
 
-            threading.Thread.__init__(self, name=name)
-            self.queue = queue
-            self.daemon = True
+        threading.Thread.__init__(self, name=name)
+        self.queue = queue
+        self.daemon = True
 
-            self.received_task_event = threading.Event()
-            self.done_event = threading.Event()
-            self.exception_event = threading.Event()
-            self.continue_event = threading.Event()
+        self.received_task_event = threading.Event()
+        self.done_event = threading.Event()
+        self.exception_event = threading.Event()
+        self.continue_event = threading.Event()
 
-            self.exception_callback = exception_callback
-            self.exc_info = None
-            self._running = True
-            self.start()
+        self.exception_callback = exception_callback
+        self.exception_info = None
+        self._running = True
+        self.start()
 
-        def run(self):
-            while self._running:
-                try:
-                    task, args, kwargs = self.queue.get(block=True, timeout=.5)
-                    self.continue_event.clear()
-                    self.received_task_event.clear()
-                    self.done_event.clear()
-                    self.exception_event.clear()
-                    logger.debug("Received task")
-                    self.received_task_event.set()
+    def run(self):
+        while self._running:
+            try:
+                task, args, kwargs = self.queue.get(block=True, timeout=.5)
+                self.continue_event.clear()
+                self.received_task_event.clear()
+                self.done_event.clear()
+                self.exception_event.clear()
+                logger.debug("Received task")
+                self.received_task_event.set()
 
-                    task(*args, **kwargs)
-                    logger.debug("Task complete")
-                    self.done_event.set()
-                except Queue.Empty:
-                    pass
-                except:
-                    logger.debug("Exception occurred")
-                    self.exc_info = sys.exc_info()
-                    self.exception_event.set()
+                task(*args, **kwargs)
+                logger.debug("Task complete")
+                self.done_event.set()
+            except Queue.Empty:
+                pass
+            except Exception as e:
+                logger.debug(type(e).__name__ + " occurred, args=" + str(e.args) + "\n" + traceback.format_exc())
+                self.exception_info = e
+                self.exception_event.set()
+                if self.exception_callback:
+                    self.exception_callback(self, self.exception_info)
+                self.continue_event.wait()
 
-                    if self.exception_callback:
-                        self.exception_callback(self, self.exc_info)
-                    self.continue_event.wait()
+    def put(self, task, *args, **kwargs):
+        self.queue.put((task, args, kwargs))
 
-        def put(self, task, *args, **kwargs):
-            self.queue.put((task, args, kwargs))
+    def raise_exceptions(self):
+        if self.exception_event.is_set():
+            raise self.exception_info
 
-        def raise_exceptions(self):
-            if self.exception_event.is_set():
-                six.reraise(self.exc_info[0], self.exc_info[1], self.exc_info[2])
+    def clear_exceptions(self):
+        self.exception_event.clear()
+        self.continue_event.set()
 
-        def clear_exceptions(self):
-            self.exception_event.clear()
-            self.continue_event.set()
-
-        def stop(self):
-            self._running = False
+    def stop(self):
+        self._running = False
 
 
 class ThreadPool:
@@ -88,19 +121,19 @@ class ThreadPool:
         self.num_threads = num_threads
 
         self.exception_event = threading.Event()
-        self.exc_info = None
+        self.exception_info = None
 
     def put(self, func, *args, **kwargs):
         self.tasks.put((func, args, kwargs))
 
     def on_exception(self, worker_thread, exc_info):
-        self.exc_info = exc_info
+        self.exception_info = exc_info
         self.exception_event.set()
         worker_thread.continue_event.set()
 
     def raise_exceptions(self):
         if self.exception_event.is_set():
-            six.reraise(self.exc_info[0], self.exc_info[1], self.exc_info[2])
+            raise self.exception_info
 
     def clear_exceptions(self):
         self.exception_event.clear()
@@ -125,20 +158,30 @@ class AsyncTask:
     def _run(self):
         try:
             self.result = self.target(*self.args, **self.kwargs)
-        except:
-            self.result = sys.exc_info()
+        except Exception as e:
+            self.result = e
         self.done = True
 
     def wait(self):
         if not self.done:
             self.thread.join()
         if isinstance(self.result, BaseException):
-            six.reraise(self.result[0], self.result[1], self.result[2])
+            raise self.result
         else:
             return self.result
 
 
-def async():
+class CustomRequestResponse():
+    def __init__(self, json_text, status_code = 200, reason = ""):
+        self.status_code = status_code
+        self.text = json_text
+        self.reason = reason
+
+    def json(self):
+        return json.loads(self.text)
+
+
+def async_dec():
     def decorator(fn):
         def wrapper(*args, **kwargs):
             return AsyncTask(fn, *args, **kwargs)
@@ -149,18 +192,43 @@ def async():
 
 
 def is_string(var):
-    return isinstance(var, string_types)
+    return isinstance(var, str)
 
-def is_command(text):
+
+def is_dict(var):
+    return isinstance(var, dict)
+
+
+def is_bytes(var):
+    return isinstance(var, bytes)
+
+
+def is_pil_image(var):
+    return pil_imported and isinstance(var, Image.Image)
+
+
+def pil_image_to_file(image, extension='JPEG', quality='web_low'):
+    if pil_imported:
+        photoBuffer = BytesIO()
+        image.convert('RGB').save(photoBuffer, extension, quality=quality)
+        photoBuffer.seek(0)
+        
+        return photoBuffer
+    else:
+        raise RuntimeError('PIL module is not imported')
+
+
+def is_command(text: str) -> bool:
     """
     Checks if `text` is a command. Telegram chat commands start with the '/' character.
     :param text: Text to check.
     :return: True if `text` is a command, else False.
     """
+    if text is None: return False
     return text.startswith('/')
 
 
-def extract_command(text):
+def extract_command(text: str) -> Union[str, None]:
     """
     Extracts the command from `text` (minus the '/') if `text` is a command (see is_command).
     If `text` is not a command, this function returns None.
@@ -174,10 +242,28 @@ def extract_command(text):
     :param text: String to extract the command from
     :return: the command if `text` is a command (according to is_command), else None.
     """
+    if text is None: return None
     return text.split()[0].split('@')[0][1:] if is_command(text) else None
 
 
-def split_string(text, chars_per_string):
+def extract_arguments(text: str) -> str:
+    """
+    Returns the argument after the command.
+    
+    Examples:
+    extract_arguments("/get name"): 'name'
+    extract_arguments("/get"): ''
+    extract_arguments("/get@botName name"): 'name'
+    
+    :param text: String to extract the arguments from a command
+    :return: the arguments if `text` is a command (according to is_command), else None.
+    """
+    regexp = re.compile(r"/\w*(@\w*)*\s*([\s\S]*)", re.IGNORECASE)
+    result = regexp.match(text)
+    return result.group(2) if is_command(text) else None
+
+
+def split_string(text: str, chars_per_string: int) -> List[str]:
     """
     Splits one string into multiple strings, with a maximum amount of `chars_per_string` characters per string.
     This is very useful for splitting one giant message into multiples.
@@ -188,6 +274,107 @@ def split_string(text, chars_per_string):
     """
     return [text[i:i + chars_per_string] for i in range(0, len(text), chars_per_string)]
 
+
+def smart_split(text: str, chars_per_string: int=MAX_MESSAGE_LENGTH) -> List[str]:
+    """
+    Splits one string into multiple strings, with a maximum amount of `chars_per_string` characters per string.
+    This is very useful for splitting one giant message into multiples.
+    If `chars_per_string` > 4096: `chars_per_string` = 4096.
+    Splits by '\n', '. ' or ' ' in exactly this priority.
+
+    :param text: The text to split
+    :param chars_per_string: The number of maximum characters per part the text is split to.
+    :return: The splitted text as a list of strings.
+    """
+
+    def _text_before_last(substr: str) -> str:
+        return substr.join(part.split(substr)[:-1]) + substr
+
+    if chars_per_string > MAX_MESSAGE_LENGTH: chars_per_string = MAX_MESSAGE_LENGTH
+
+    parts = []
+    while True:
+        if len(text) < chars_per_string:
+            parts.append(text)
+            return parts
+
+        part = text[:chars_per_string]
+
+        if "\n" in part: part = _text_before_last("\n")
+        elif ". " in part: part = _text_before_last(". ")
+        elif " " in part: part = _text_before_last(" ")
+
+        parts.append(part)
+        text = text[len(part):]
+
+
+def escape(text: str) -> str:
+    """
+    Replaces the following chars in `text` ('&' with '&amp;', '<' with '&lt;' and '>' with '&gt;').
+
+    :param text: the text to escape
+    :return: the escaped text
+    """
+    chars = {"&": "&amp;", "<": "&lt;", ">": "&gt"}
+    for old, new in chars.items(): text = text.replace(old, new)
+    return text
+
+
+def user_link(user: types.User, include_id: bool=False) -> str:
+    """
+    Returns an HTML user link. This is useful for reports.
+    Attention: Don't forget to set parse_mode to 'HTML'!
+
+    Example:
+    bot.send_message(your_user_id, user_link(message.from_user) + ' started the bot!', parse_mode='HTML')
+
+    :param user: the user (not the user_id)
+    :param include_id: include the user_id
+    :return: HTML user link
+    """
+    name = escape(user.first_name)
+    return (f"<a href='tg://user?id={user.id}'>{name}</a>" 
+        + (f" (<pre>{user.id}</pre>)" if include_id else ""))
+
+
+def quick_markup(values: Dict[str, Dict[str, Any]], row_width: int=2) -> types.InlineKeyboardMarkup:
+    """
+    Returns a reply markup from a dict in this format: {'text': kwargs}
+    This is useful to avoid always typing 'btn1 = InlineKeyboardButton(...)' 'btn2 = InlineKeyboardButton(...)' 
+    
+    Example:
+    quick_markup({
+        'Twitter': {'url': 'https://twitter.com'},
+        'Facebook': {'url': 'https://facebook.com'},
+        'Back': {'callback_data': 'whatever'}
+    }, row_width=2): 
+        returns an InlineKeyboardMarkup with two buttons in a row, one leading to Twitter, the other to facebook
+        and a back button below
+
+    kwargs can be: 
+    {
+        'url': None, 
+        'callback_data': None, 
+        'switch_inline_query': None,
+        'switch_inline_query_current_chat': None,
+        'callback_game': None,
+        'pay': None,
+        'login_url': None
+    }
+    
+    :param values: a dict containing all buttons to create in this format: {text: kwargs} {str:}
+    :param row_width: int row width
+    :return: InlineKeyboardMarkup
+    """
+    markup = types.InlineKeyboardMarkup(row_width=row_width)
+    buttons = [
+        types.InlineKeyboardButton(text=text, **kwargs)
+        for text, kwargs in values.items()
+    ]
+    markup.add(*buttons)
+    return markup
+
+
 # CREDITS TO http://stackoverflow.com/questions/12317940#answer-12320352
 def or_set(self):
     self._set()
@@ -200,16 +387,20 @@ def or_clear(self):
 
 
 def orify(e, changed_callback):
-    e._set = e.set
-    e._clear = e.clear
+    if not hasattr(e, "_set"):
+        e._set = e.set
+    if not hasattr(e, "_clear"):
+        e._clear = e.clear
     e.changed = changed_callback
     e.set = lambda: or_set(e)
     e.clear = lambda: or_clear(e)
 
+
 def OrEvent(*events):
     or_event = threading.Event()
+
     def changed():
-        bools = [e.is_set() for e in events]
+        bools = [ev.is_set() for ev in events]
         if any(bools):
             or_event.set()
         else:
@@ -226,18 +417,79 @@ def OrEvent(*events):
     changed()
     return or_event
 
-def extract_arguments(text):
+
+def per_thread(key, construct_value, reset=False):
+    if reset or not hasattr(thread_local, key):
+        value = construct_value()
+        setattr(thread_local, key, value)
+
+    return getattr(thread_local, key)
+
+
+def chunks(lst, n):
+    """Yield successive n-sized chunks from lst."""
+    # https://stackoverflow.com/a/312464/9935473
+    for i in range(0, len(lst), n):
+        yield lst[i:i + n]
+
+
+def generate_random_token():
+    return ''.join(random.sample(string.ascii_letters, 16))
+
+
+def deprecated(warn: bool=True, alternative: Optional[Callable]=None):
     """
-    Returns the argument after the command.
-    
-    Examples:
-    extract_arguments("/get name"): 'name'
-    extract_arguments("/get"): ''
-    extract_arguments("/get@botName name"): 'name'
-    
-    :param text: String to extract the arguments from a command
-    :return: the arguments if `text` is a command (according to is_command), else None.
+    Use this decorator to mark functions as deprecated.
+    When the function is used, an info (or warning if `warn` is True) is logged.
+    :param warn: If True a warning is logged else an info
+    :param alternative: The new function to use instead
     """
-    regexp = re.compile("\/\w*(@\w*)*\s*([\s\S]*)",re.IGNORECASE)
-    result = regexp.match(text)
-    return result.group(2) if is_command(text) else None
+    def decorator(function):
+        def wrapper(*args, **kwargs):
+            info = f"`{function.__name__}` is deprecated." + (f" Use `{alternative.__name__}` instead" if alternative else "")
+            if not warn:
+                logger.info(info)
+            else:
+                logger.warning(info)
+            return function(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+# Cloud helpers
+def webhook_google_functions(bot, request):
+    """A webhook endpoint for Google Cloud Functions FaaS."""
+    if request.is_json:
+        try:
+            request_json = request.get_json()
+            update = types.Update.de_json(request_json)
+            bot.process_new_updates([update])
+            return ''
+        except Exception as e:
+            print(e)
+            return 'Bot FAIL', 400
+    else:
+        return 'Bot ON'
+
+def antiflood(function, *args, **kwargs):
+    """
+    Use this function inside loops in order to avoid getting TooManyRequests error.
+    Example:
+
+    from telebot.util import antiflood
+    for chat_id in chat_id_list:
+        msg = antiflood(bot.send_message, chat_id, text)
+        
+    You want get the
+    """
+    from telebot.apihelper import ApiTelegramException
+    from time import sleep
+    msg = None
+    try:
+        msg = function(*args, **kwargs)
+    except ApiTelegramException as ex:
+        if ex.error_code == 429:
+            sleep(ex.result_json['parameters']['retry_after'])
+            msg = function(*args, **kwargs)
+    finally:
+        return msg

telebot/version.py

@@ -0,0 +1,3 @@
+# Versions should comply with PEP440.
+# This line is parsed in setup.py:
+__version__ = '4.3.1'

tests/test_handler_backends.py

@@ -0,0 +1,277 @@
+import sys
+
+sys.path.append('../')
+
+REDIS_TESTS = False
+
+import os
+import time
+
+import pytest
+
+import telebot
+from telebot import types
+from telebot.handler_backends import MemoryHandlerBackend, FileHandlerBackend
+
+if REDIS_TESTS:
+    from telebot.handler_backends import RedisHandlerBackend
+
+
+@pytest.fixture()
+def telegram_bot():
+    return telebot.TeleBot('', threaded=False)
+
+
+@pytest.fixture
+def private_chat():
+    return types.Chat(id=11, type='private')
+
+
+@pytest.fixture
+def user():
+    return types.User(id=10, is_bot=False, first_name='Some User')
+
+
+@pytest.fixture()
+def message(user, private_chat):
+    params = {'text': '/start'}
+    return types.Message(
+        message_id=1, from_user=user, date=None, chat=private_chat, content_type='text', options=params, json_string=""
+    )
+
+
+@pytest.fixture()
+def reply_to_message(user, private_chat, message):
+    params = {'text': '/start'}
+    reply_message = types.Message(
+        message_id=2, from_user=user, date=None, chat=private_chat, content_type='text', options=params, json_string=""
+    )
+    reply_message.reply_to_message = message
+    return reply_message
+
+
+@pytest.fixture()
+def update_type(message):
+    edited_message = None
+    channel_post = None
+    edited_channel_post = None
+    inline_query = None
+    chosen_inline_result = None
+    callback_query = None
+    shipping_query = None
+    pre_checkout_query = None
+    poll = None
+    poll_answer = None
+    my_chat_member = None
+    chat_member = None
+    chat_join_request = None
+    return types.Update(1001234038283, message, edited_message, channel_post, edited_channel_post, inline_query,
+                        chosen_inline_result, callback_query, shipping_query, pre_checkout_query, poll, poll_answer,
+                        my_chat_member, chat_member, chat_join_request)
+
+
+@pytest.fixture()
+def reply_to_message_update_type(reply_to_message):
+    edited_message = None
+    channel_post = None
+    edited_channel_post = None
+    inline_query = None
+    chosen_inline_result = None
+    callback_query = None
+    shipping_query = None
+    pre_checkout_query = None
+    poll = None
+    poll_answer = None
+    my_chat_member = None
+    chat_member = None
+    chat_join_request = None
+    return types.Update(1001234038284, reply_to_message, edited_message, channel_post, edited_channel_post,
+                        inline_query, chosen_inline_result, callback_query, shipping_query, pre_checkout_query, 
+                        poll, poll_answer, my_chat_member, chat_member, chat_join_request)
+
+
+def next_handler(message):
+    message.text = 'entered next_handler'
+
+
+def test_memory_handler_backend_default_backend(telegram_bot):
+    assert telegram_bot.reply_backend.__class__ == MemoryHandlerBackend
+    assert telegram_bot.next_step_backend.__class__ == MemoryHandlerBackend
+
+
+def test_memory_handler_backend_register_next_step_handler(telegram_bot, private_chat, update_type):
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    assert len(telegram_bot.next_step_backend.handlers[private_chat.id]) == 1
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered next_handler'
+
+    assert private_chat.id not in telegram_bot.next_step_backend.handlers
+
+
+def test_memory_handler_backend_clear_next_step_handler(telegram_bot, private_chat, update_type):
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    assert len(telegram_bot.next_step_backend.handlers[private_chat.id]) == 1
+
+    telegram_bot.clear_step_handler_by_chat_id(private_chat.id)
+
+    assert private_chat.id not in telegram_bot.next_step_backend.handlers
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+
+def test_memory_handler_backend_register_reply_handler(telegram_bot, private_chat, update_type,
+                                                       reply_to_message_update_type):
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_for_reply_by_message_id(message.message_id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    assert len(telegram_bot.reply_backend.handlers[update_type.message.message_id]) == 1
+
+    telegram_bot.process_new_updates([reply_to_message_update_type])
+    assert reply_to_message_update_type.message.text == 'entered next_handler'
+
+    assert private_chat.id not in telegram_bot.reply_backend.handlers
+
+
+def test_memory_handler_backend_clear_reply_handler(telegram_bot, private_chat, update_type,
+                                                    reply_to_message_update_type):
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_for_reply_by_message_id(message.message_id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    assert len(telegram_bot.reply_backend.handlers[update_type.message.message_id]) == 1
+
+    telegram_bot.clear_reply_handlers_by_message_id(update_type.message.message_id)
+
+    assert update_type.message.message_id not in telegram_bot.reply_backend.handlers
+
+    telegram_bot.process_new_updates([reply_to_message_update_type])
+    assert reply_to_message_update_type.message.text == 'entered start'
+
+
+def test_file_handler_backend_register_next_step_handler(telegram_bot, private_chat, update_type):
+    telegram_bot.next_step_backend=FileHandlerBackend(filename='./.handler-saves/step1.save', delay=0.1)
+
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    time.sleep(0.2)
+
+    assert os.path.exists(telegram_bot.next_step_backend.filename)
+
+    assert len(telegram_bot.next_step_backend.handlers[private_chat.id]) == 1
+
+    telegram_bot.next_step_backend.handlers = {}
+
+    telegram_bot.next_step_backend.load_handlers()
+
+    assert len(telegram_bot.next_step_backend.handlers[private_chat.id]) == 1
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered next_handler'
+
+    assert private_chat.id not in telegram_bot.next_step_backend.handlers
+
+    time.sleep(0.2)
+    if os.path.exists(telegram_bot.next_step_backend.filename):
+        os.remove(telegram_bot.next_step_backend.filename)
+
+
+def test_file_handler_backend_clear_next_step_handler(telegram_bot, private_chat, update_type):
+    telegram_bot.next_step_backend=FileHandlerBackend(filename='./.handler-saves/step2.save', delay=0.1)
+
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    assert len(telegram_bot.next_step_backend.handlers[private_chat.id]) == 1
+
+    time.sleep(0.2)
+
+    assert os.path.exists(telegram_bot.next_step_backend.filename)
+
+    telegram_bot.clear_step_handler_by_chat_id(private_chat.id)
+
+    time.sleep(0.2)
+
+    telegram_bot.next_step_backend.load_handlers()
+
+    assert private_chat.id not in telegram_bot.next_step_backend.handlers
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    time.sleep(0.2)
+    if os.path.exists(telegram_bot.next_step_backend.filename):
+        os.remove(telegram_bot.next_step_backend.filename)
+
+
+def test_redis_handler_backend_register_next_step_handler(telegram_bot, private_chat, update_type):
+    if not REDIS_TESTS:
+        pytest.skip('please install redis and configure redis server, then enable REDIS_TESTS')
+
+    telegram_bot.next_step_backend = RedisHandlerBackend(prefix='pyTelegramBotApi:step_backend1')
+
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered next_handler'
+
+
+def test_redis_handler_backend_clear_next_step_handler(telegram_bot, private_chat, update_type):
+    if not REDIS_TESTS:
+        pytest.skip('please install redis and configure redis server, then enable REDIS_TESTS')
+
+    telegram_bot.next_step_backend = RedisHandlerBackend(prefix='pyTelegramBotApi:step_backend2')
+
+    @telegram_bot.message_handler(commands=['start'])
+    def start(message):
+        message.text = 'entered start'
+        telegram_bot.register_next_step_handler_by_chat_id(message.chat.id, next_handler)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'
+
+    telegram_bot.clear_step_handler_by_chat_id(private_chat.id)
+
+    telegram_bot.process_new_updates([update_type])
+    assert update_type.message.text == 'entered start'

tests/test_telebot.py

@@ -1,11 +1,13 @@
 # -*- coding: utf-8 -*-
 import sys
+import warnings
 
 sys.path.append('../')
 
 import time
 import pytest
 import os
+from datetime import datetime, timedelta
 
 import telebot
 from telebot import types
@@ -19,6 +21,19 @@ if not should_skip:
     GROUP_ID = os.environ['GROUP_ID']
 
 
+def deprecated1_new_function():
+    print("deprecated1_new_function")
+def deprecated1_old_function():
+    print("deprecated1_old_function")
+    warnings.warn("The 'deprecated1_old_function' is deprecated. Use `deprecated1_new_function` instead", DeprecationWarning, 2)
+    deprecated1_new_function()
+
+def deprecated2_new_function():
+    print("deprecated2_new_function")
+@util.deprecated(alternative=deprecated2_new_function)
+def deprecated2_old_function():
+    print("deprecated2_old_function")
+
 @pytest.mark.skipif(should_skip, reason="No environment variables configured")
 class TestTeleBot:
     def test_message_listener(self):
@@ -48,7 +63,8 @@ class TestTeleBot:
         bot = telebot.TeleBot('')
         msg = self.create_text_message(r'https://web.telegram.org/')
 
-        @bot.message_handler(regexp='((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
+        # noinspection PyUnusedLocal
+        @bot.message_handler(regexp=r'((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
         def command_url(message):
             msg.text = 'got'
 
@@ -60,6 +76,7 @@ class TestTeleBot:
         bot = telebot.TeleBot('')
         msg = self.create_text_message(r'lambda_text')
 
+        # noinspection PyUnusedLocal
         @bot.message_handler(func=lambda message: r'lambda' in message.text)
         def command_url(message):
             msg.text = 'got'
@@ -72,6 +89,7 @@ class TestTeleBot:
         bot = telebot.TeleBot('')
         msg = self.create_text_message(r'text')
 
+        # noinspection PyUnusedLocal
         @bot.message_handler(func=lambda message: r'lambda' in message.text)
         def command_url(message):
             msg.text = 'got'
@@ -84,7 +102,8 @@ class TestTeleBot:
         bot = telebot.TeleBot('')
         msg = self.create_text_message(r'web.telegram.org/')
 
-        @bot.message_handler(regexp='((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
+        # noinspection PyUnusedLocal
+        @bot.message_handler(regexp=r'((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
         def command_url(message):
             msg.text = 'got'
 
@@ -121,6 +140,16 @@ class TestTeleBot:
         ret_msg = tb.send_document(CHAT_ID, ret_msg.document.file_id)
         assert ret_msg.message_id
 
+    def test_send_file_with_filename(self):
+        file_data = open('../examples/detailed_example/kitten.jpg', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+
+        ret_msg = tb.send_document(CHAT_ID, file_data)
+        assert ret_msg.message_id
+
+        ret_msg = tb.send_document(CHAT_ID, file_data, visible_file_name="test.jpg")
+        assert ret_msg.message_id
+        
     def test_send_file_dis_noti(self):
         file_data = open('../examples/detailed_example/kitten.jpg', 'rb')
         tb = telebot.TeleBot(TOKEN)
@@ -193,7 +222,7 @@ class TestTeleBot:
     def test_send_audio(self):
         file_data = open('./test_data/record.mp3', 'rb')
         tb = telebot.TeleBot(TOKEN)
-        ret_msg = tb.send_audio(CHAT_ID, file_data, 1, performer='eternnoir', title='pyTelegram')
+        ret_msg = tb.send_audio(CHAT_ID, file_data, duration = 1, performer='eternnoir', title='pyTelegram')
         assert ret_msg.content_type == 'audio'
         assert ret_msg.audio.performer == 'eternnoir'
         assert ret_msg.audio.title == 'pyTelegram'
@@ -201,7 +230,8 @@ class TestTeleBot:
     def test_send_audio_dis_noti(self):
         file_data = open('./test_data/record.mp3', 'rb')
         tb = telebot.TeleBot(TOKEN)
-        ret_msg = tb.send_audio(CHAT_ID, file_data, 1, performer='eternnoir', title='pyTelegram', disable_notification=True)
+        ret_msg = tb.send_audio(CHAT_ID, file_data, duration = 1, performer='eternnoir', title='pyTelegram',
+                                disable_notification=True)
         assert ret_msg.content_type == 'audio'
         assert ret_msg.audio.performer == 'eternnoir'
         assert ret_msg.audio.title == 'pyTelegram'
@@ -240,6 +270,12 @@ class TestTeleBot:
         ret_msg = tb.send_message(CHAT_ID, text)
         assert ret_msg.message_id
 
+    def test_send_dice(self):
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_dice(CHAT_ID, emoji='🎯')
+        assert ret_msg.message_id
+        assert ret_msg.content_type == 'dice'
+
     def test_send_message_dis_noti(self):
         text = 'CI Test Message'
         tb = telebot.TeleBot(TOKEN)
@@ -282,6 +318,13 @@ class TestTeleBot:
         ret_msg = tb.forward_message(CHAT_ID, CHAT_ID, msg.message_id)
         assert ret_msg.forward_from
 
+    def test_copy_message(self):
+        text = 'CI copy_message Test Message'
+        tb = telebot.TeleBot(TOKEN)
+        msg = tb.send_message(CHAT_ID, text)
+        ret_msg = tb.copy_message(CHAT_ID, CHAT_ID, msg.message_id)
+        assert ret_msg
+
     def test_forward_message_dis_noti(self):
         text = 'CI forward_message Test Message'
         tb = telebot.TeleBot(TOKEN)
@@ -360,6 +403,20 @@ class TestTeleBot:
         new_msg = tb.edit_message_caption(caption='Edit test', chat_id=CHAT_ID, message_id=msg.message_id)
         assert new_msg.caption == 'Edit test'
 
+    def test_edit_message_media(self):
+        file_data = open('../examples/detailed_example/kitten.jpg', 'rb')
+        file_data_2 = open('../examples/detailed_example/rooster.jpg', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        msg = tb.send_photo(CHAT_ID, file_data)
+        new_msg = tb.edit_message_media(chat_id=CHAT_ID, message_id=msg.message_id,
+                                        media=types.InputMediaPhoto(file_data_2, caption='Test editMessageMedia 0'))
+        assert type(new_msg) != bool
+
+        new_msg = tb.edit_message_media(chat_id=CHAT_ID, message_id=msg.message_id,
+                                        media=types.InputMediaPhoto(msg.photo[0].file_id, caption='Test editMessageMedia'))
+        assert type(new_msg) != bool
+        assert new_msg.caption == 'Test editMessageMedia'
+
     def test_get_chat(self):
         tb = telebot.TeleBot(TOKEN)
         ch = tb.get_chat(GROUP_ID)
@@ -375,6 +432,25 @@ class TestTeleBot:
         cn = tb.get_chat_members_count(GROUP_ID)
         assert cn > 1
 
+    def test_export_chat_invite_link(self):
+        tb = telebot.TeleBot(TOKEN)
+        il = tb.export_chat_invite_link(GROUP_ID)
+        assert isinstance(il, str)
+
+    def test_create_revoke_detailed_chat_invite_link(self):
+        tb = telebot.TeleBot(TOKEN)
+        cil = tb.create_chat_invite_link(
+            GROUP_ID,
+            expire_date = datetime.now() + timedelta(minutes=1),
+            member_limit=5)
+        assert isinstance(cil.invite_link, str)
+        assert cil.creator.id == tb.get_me().id
+        assert isinstance(cil.expire_date, (float, int))
+        assert cil.member_limit == 5
+        assert not cil.is_revoked
+        rcil = tb.revoke_chat_invite_link(GROUP_ID, cil.invite_link)
+        assert rcil.is_revoked
+
     def test_edit_markup(self):
         text = 'CI Test Message'
         tb = telebot.TeleBot(TOKEN)
@@ -387,10 +463,41 @@ class TestTeleBot:
         new_msg = tb.edit_message_reply_markup(chat_id=CHAT_ID, message_id=ret_msg.message_id, reply_markup=markup)
         assert new_msg.message_id
 
-    def create_text_message(self, text):
+    def test_antiflood(self):
+        text = "Flooding"
+        tb = telebot.TeleBot(TOKEN)
+        i = -1
+        for i in range(0,100):
+            util.antiflood(tb.send_message, CHAT_ID, text)
+        assert i
+
+    @staticmethod
+    def create_text_message(text):
         params = {'text': text}
-        chat = types.User(11, 'test')
-        return types.Message(1, None, None, chat, 'text', params)
+        chat = types.User(11, False, 'test')
+        return types.Message(1, None, None, chat, 'text', params, "")
+
+    @staticmethod
+    def create_message_update(text):
+        params = {'text': text}
+        chat = types.User(11, False, 'test')
+        message = types.Message(1, None, None, chat, 'text', params, "")
+        edited_message = None
+        channel_post = None
+        edited_channel_post = None
+        inline_query = None
+        chosen_inline_result = None
+        callback_query = None
+        shipping_query = None
+        pre_checkout_query = None
+        poll = None
+        poll_answer = None
+        my_chat_member = None
+        chat_member = None
+        chat_join_request = None
+        return types.Update(-1001234038283, message, edited_message, channel_post, edited_channel_post, inline_query,
+                            chosen_inline_result, callback_query, shipping_query, pre_checkout_query, poll, poll_answer,
+                            my_chat_member, chat_member, chat_join_request)
 
     def test_is_string_unicode(self):
         s1 = u'string'
@@ -403,3 +510,143 @@ class TestTeleBot:
     def test_not_string(self):
         i1 = 10
         assert not util.is_string(i1)
+
+    def test_send_video_note(self):
+        file_data = open('./test_data/test_video.mp4', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_video_note(CHAT_ID, file_data)
+        assert ret_msg.message_id
+
+    def test_send_media_group(self):
+        tb = telebot.TeleBot(TOKEN)
+        img1 = 'https://i.imgur.com/CjXjcnU.png'
+        img2 = 'https://i.imgur.com/CjXjcnU.png'
+        medias = [types.InputMediaPhoto(img1, "View"), types.InputMediaPhoto(img2, "Dog")]
+        result = tb.send_media_group(CHAT_ID, medias)
+        assert len(result) == 2
+        assert result[0].media_group_id is not None
+        assert result[0].media_group_id == result[1].media_group_id
+
+    def test_send_media_group_local_files(self):
+        photo = open('../examples/detailed_example/kitten.jpg', 'rb')
+        video = open('./test_data/test_video.mp4', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        medias = [types.InputMediaPhoto(photo, "View"),
+                  types.InputMediaVideo(video)]
+        result = tb.send_media_group(CHAT_ID, medias)
+        assert len(result) == 2
+        assert result[0].media_group_id is not None
+        assert result[1].media_group_id is not None
+
+    def test_send_photo_formating_caption(self):
+        file_data = open('../examples/detailed_example/kitten.jpg', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_photo(CHAT_ID, file_data, caption='_italic_', parse_mode='Markdown')
+        assert ret_msg.caption_entities[0].type == 'italic'
+
+    def test_send_video_formatting_caption(self):
+        file_data = open('./test_data/test_video.mp4', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_video(CHAT_ID, file_data, caption='_italic_', parse_mode='Markdown')
+        assert ret_msg.caption_entities[0].type == 'italic'
+
+    def test_send_audio_formatting_caption(self):
+        file_data = open('./test_data/record.mp3', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_audio(CHAT_ID, file_data, caption='<b>bold</b>', parse_mode='HTML')
+        assert ret_msg.caption_entities[0].type == 'bold'
+
+    def test_send_voice_formatting_caprion(self):
+        file_data = open('./test_data/record.ogg', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_voice(CHAT_ID, file_data, caption='<b>bold</b>', parse_mode='HTML')
+        assert ret_msg.caption_entities[0].type == 'bold'
+        assert ret_msg.voice.mime_type == 'audio/ogg'
+
+    def test_send_media_group_formatting_caption(self):
+        tb = telebot.TeleBot(TOKEN)
+        img1 = 'https://i.imgur.com/CjXjcnU.png'
+        img2 = 'https://i.imgur.com/CjXjcnU.png'
+        medias = [types.InputMediaPhoto(img1, "*View*", parse_mode='Markdown'),
+                  types.InputMediaPhoto(img2, "_Dog_", parse_mode='Markdown')]
+        result = tb.send_media_group(CHAT_ID, medias)
+        assert len(result) == 2
+        assert result[0].media_group_id is not None
+        assert result[0].caption_entities[0].type == 'bold'
+        assert result[1].caption_entities[0].type == 'italic'
+
+    def test_send_document_formating_caption(self):
+        file_data = open('../examples/detailed_example/kitten.jpg', 'rb')
+        tb = telebot.TeleBot(TOKEN)
+        ret_msg = tb.send_document(CHAT_ID, file_data, caption='_italic_', parse_mode='Markdown')
+        assert ret_msg.caption_entities[0].type == 'italic'
+
+    def test_chat_commands(self):
+        tb = telebot.TeleBot(TOKEN)
+        command, description, lang = 'command_1', 'description of command 1', 'en'
+        scope = telebot.types.BotCommandScopeChat(CHAT_ID)
+        ret_msg = tb.set_my_commands([telebot.types.BotCommand(command, description)], scope, lang)
+        assert ret_msg is True
+
+        ret_msg = tb.get_my_commands(scope = scope, language_code = lang)
+        assert ret_msg[0].command == command
+        assert ret_msg[0].description == description
+
+        ret_msg = tb.delete_my_commands(scope = scope, language_code = lang)
+        assert ret_msg is True
+
+        ret_msg = tb.get_my_commands(scope = scope, language_code = lang)
+        assert ret_msg == []
+
+
+    def test_typed_middleware_handler(self):
+        from telebot import apihelper
+
+        apihelper.ENABLE_MIDDLEWARE = True
+
+        tb = telebot.TeleBot('')
+        update = self.create_message_update('/help')
+
+        # noinspection PyUnusedLocal
+        @tb.middleware_handler(update_types=['message'])
+        def middleware(tb_instance, message):
+            message.text = 'got'
+
+        @tb.message_handler(func=lambda m: m.text == 'got')
+        def command_handler(message):
+            message.text = message.text + message.text
+
+        tb.process_new_updates([update])
+        time.sleep(1)
+        assert update.message.text == 'got' * 2
+
+    def test_default_middleware_handler(self):
+        from telebot import apihelper
+
+        apihelper.ENABLE_MIDDLEWARE = True
+
+        tb = telebot.TeleBot('')
+        update = self.create_message_update('/help')
+
+        # noinspection PyUnusedLocal
+        @tb.middleware_handler()
+        def middleware(tb_instance, mw_update):
+            mw_update.message.text = 'got'
+
+        @tb.message_handler(func=lambda m: m.text == 'got')
+        def command_handler(message):
+            message.text = message.text + message.text
+
+        tb.process_new_updates([update])
+        time.sleep(1)
+        assert update.message.text == 'got' * 2
+    
+    def test_deprecated_dec(self):
+        deprecated1_old_function()
+        deprecated2_old_function()
+
+    def test_chat_permissions(self):
+        return # CHAT_ID is private chat, no permissions can be set
+        #tb = telebot.TeleBot(TOKEN)
+        #permissions = types.ChatPermissions(can_send_messages=True, can_send_polls=False)
+        #msg = tb.set_chat_permissions(CHAT_ID, permissions)

tests/test_types.py

@@ -6,19 +6,51 @@ from telebot import types
 
 
 def test_json_user():
-    jsonstring = r'{"id":101176298,"first_name":"RDSSBOT","username":"rdss_bot"}'
+    jsonstring = r'{"id":101176298,"first_name":"RDSSBOT","last_name":")))","username":"rdss_bot","is_bot":true}'
     u = types.User.de_json(jsonstring)
     assert u.id == 101176298
+    assert u.full_name == 'RDSSBOT )))'
 
 
 def test_json_message():
-    jsonstring = r'{"message_id":1,"from":{"id":108929734,"first_name":"Frank","last_name":"Wang","username":"eternnoir"},"chat":{"id":1734,"first_name":"F","type":"private","last_name":"Wa","username":"oir"},"date":1435296025,"text":"HIHI"}'
+    jsonstring = r'{"message_id":1,"from":{"id":108929734,"first_name":"Frank","last_name":"Wang","username":"eternnoir","is_bot":true},"chat":{"id":1734,"first_name":"F","type":"private","last_name":"Wa","username":"oir"},"date":1435296025,"text":"HIHI"}'
     msg = types.Message.de_json(jsonstring)
     assert msg.text == 'HIHI'
 
 
+def test_json_message_with_reply_markup():
+    jsonstring = r'{"message_id":48,"from":{"id":153587469,"is_bot":false,"first_name":"Neko","username":"Neko"},"chat":{"id":153587469,"first_name":"Neko","username":"Neko","type":"private"},"date":1598879570,"text":"test","reply_markup":{"inline_keyboard":[[{"text":"Google","url":"http://www.google.com"},{"text":"Yahoo","url":"http://www.yahoo.com"}]]}}'
+    msg = types.Message.de_json(jsonstring)
+    assert msg.content_type == 'text'
+    assert msg.reply_markup.keyboard[0][0].text == 'Google'
+
+
+def test_json_InlineKeyboardMarkup():
+    jsonstring = r'{"inline_keyboard":[[{"text":"Google","url":"http://www.google.com"},{"text":"Yahoo","url":"http://www.yahoo.com"}]]}'
+    markup = types.InlineKeyboardMarkup.de_json(jsonstring)
+    assert markup.keyboard[0][0].text == 'Google'
+    assert markup.keyboard[0][1].url == 'http://www.yahoo.com'
+
+
+def test_json_InlineKeyboardButton():
+    jsonstring = r'{"text":"Google","url":"http://www.google.com"}'
+    button = types.InlineKeyboardButton.de_json(jsonstring)
+    assert button.text == 'Google'
+    assert button.url == 'http://www.google.com'
+
+
+
+def test_json_message_with_dice():
+    jsonstring = r'{"message_id":5560,"from":{"id":879343317,"is_bot":false,"first_name":"George","last_name":"Forse","username":"dr_fxrse","language_code":"ru"},"chat":{"id":879343317,"first_name":"George","last_name":"Forse","username":"dr_fxrse","type":"private"},"date":1586926330,"dice":{"value": 4, "emoji": "\ud83c\udfaf"}}'
+    msg = types.Message.de_json(jsonstring)
+    assert msg.content_type == 'dice'
+    assert isinstance(msg.dice, types.Dice)
+    assert msg.dice.value == 4
+    assert msg.dice.emoji == '🎯'
+
+
 def test_json_message_group():
-    json_string = r'{"message_id":10,"from":{"id":12345,"first_name":"g","last_name":"G","username":"GG"},"chat":{"id":-866,"type":"private","title":"\u4ea4"},"date":1435303157,"text":"HIHI"}'
+    json_string = r'{"message_id":10,"from":{"id":12345,"first_name":"g","last_name":"G","username":"GG","is_bot":true},"chat":{"id":-866,"type":"private","title":"\u4ea4"},"date":1435303157,"text":"HIHI","has_protected_content":true}'
     msg = types.Message.de_json(json_string)
     assert msg.text == 'HIHI'
     assert len(msg.chat.title) != 0
@@ -32,14 +64,14 @@ def test_json_GroupChat():
 
 
 def test_json_Document():
-    json_string = r'{"file_name":"Text File","thumb":{},"file_id":"BQADBQADMwIAAsYifgZ_CEh0u682xwI","file_size":446}'
+    json_string = r'{"file_name":"Text File","thumb":{},"file_id":"BQADBQADMwIAAsYifgZ_CEh0u682xwI","file_unique_id": "AgADJQEAAqfhOEY","file_size":446}'
     doc = types.Document.de_json(json_string)
     assert doc.thumb is None
     assert doc.file_name == 'Text File'
 
 
 def test_json_Message_Audio():
-    json_string = r'{"message_id":131,"from":{"id":12775,"first_name":"dd","username":"dd"},"chat":{"id":10834,"first_name":"dd","type":"private","type":"private","last_name":"dd","username":"dd"},"date":1439978364,"audio":{"duration":1,"mime_type":"audio\/mpeg","title":"pyTelegram","performer":"eternnoir","file_id":"BQADBQADDH1JaB8-1KyWUss2-Ag","file_size":20096}}'
+    json_string = r'{"message_id":131,"from":{"id":12775,"first_name":"dd","username":"dd","is_bot":true },"chat":{"id":10834,"first_name":"dd","type":"private","type":"private","last_name":"dd","username":"dd"},"date":1439978364,"audio":{"duration":1,"mime_type":"audio\/mpeg","title":"pyTelegram","performer":"eternnoir","file_id":"BQADBQADDH1JaB8-1KyWUss2-Ag","file_unique_id": "AgADawEAAn8VSFY","file_size":20096}}'
     msg = types.Message.de_json(json_string)
     assert msg.audio.duration == 1
     assert msg.content_type == 'audio'
@@ -48,7 +80,7 @@ def test_json_Message_Audio():
 
 
 def test_json_Message_Sticker():
-    json_string = r'{"message_id":98,"from":{"id":10734,"first_name":"Fd","last_name":"Wd","username":"dd"},"chat":{"id":10734,"first_name":"Fd","type":"private","last_name":"Wd","username":"dd"},"date":1435479551,"sticker":{"width":550,"height":368,"thumb":{"file_id":"AAQFABPJLB0sAAQq17w-li3bzoIfAAIC","file_size":1822,"width":90,"height":60},"file_id":"BQADBQADNAIAAsYifgYdGJOa6bGAsQI","file_size":30320}}'
+    json_string = r'{"message_id": 21552, "from": {"id": 590740002, "is_bot": false, "first_name": "⚜️ Ƥυrуα ⚜️", "username": "Purya", "language_code": "en"}, "chat": {"id": -1001309982000, "title": "123", "type": "supergroup"}, "date": 1594068909, "sticker": {"width": 368, "height": 368, "emoji": "🤖", "set_name": "ipuryapack", "is_animated": false, "thumb": {"file_id": "AAMCBAADHQJOFL7mAAJUMF8Dj62hpmDhpRAYvkc8CtIqipolAAJ8AAPA-8cF9yxjgjkLS97A0D4iXQARtQAHbQADHy4AAhoE", "file_unique_id": "AQADwNA-Il0AAx8uAAI", "file_size": 7776, "width": 60, "height": 60}, "file_id": "CAACAgQAAx0CThS-5gACVDBfA4-toaZg4aUQGL5HWerSKoqaJQACArADwPvHBfcsY4I5C3feGgQ", "file_unique_id": "AgADfAADsPvHWQ", "file_size": 14602}}'
     msg = types.Message.de_json(json_string)
     assert msg.sticker.height == 368
     assert msg.sticker.thumb.height == 60
@@ -56,29 +88,29 @@ def test_json_Message_Sticker():
 
 
 def test_json_Message_Sticker_without_thumb():
-    json_string = r'{"message_id":98,"from":{"id":10734,"first_name":"Fd","last_name":"Wd","username":"dd"},"chat":{"id":10734,"first_name":"Fd","type":"private","last_name":"Wd","username":"dd"},"date":1435479551,"sticker":{"width":550,"height":368,"file_id":"BQADBQADNAIAAsYifgYdGJOa6bGAsQI","file_size":30320}}'
+    json_string = r'{"message_id": 21552, "from": {"id": 590740002, "is_bot": false, "first_name": "⚜️ Ƥυrуα ⚜️", "username": "Purya", "language_code": "en"}, "chat": {"id": -1001309982000, "title": "123", "type": "supergroup"}, "date": 1594068909, "sticker": {"width": 368, "height": 368, "emoji": "🤖", "set_name": "ipuryapack", "is_animated": false, "file_id": "CAACAgQAAx0CThS-5gACVDBfA4-toaZg4aUQGL5HWerSKoqaJQACArADwPvHBfcsY4I5C3feGgQ", "file_unique_id": "AgADfAADsPvHWQ", "file_size": 14602}}'
     msg = types.Message.de_json(json_string)
     assert msg.sticker.height == 368
-    assert msg.sticker.thumb == None
+    assert msg.sticker.thumb is None
     assert msg.content_type == 'sticker'
 
 
 def test_json_Message_Document():
-    json_string = r'{"message_id":97,"from":{"id":10734,"first_name":"Fd","last_name":"Wd","username":"dd"},"chat":{"id":10,"first_name":"Fd","type":"private","last_name":"Wd","username":"dd"},"date":1435478744,"document":{"file_name":"Text File","thumb":{},"file_id":"BQADBQADMwIAAsYifgZ_CEh0u682xwI","file_size":446}}'
+    json_string = r'{"message_id":97,"from":{"id":10734,"first_name":"Fd","last_name":"Wd","username":"dd","is_bot":true },"chat":{"id":10,"first_name":"Fd","type":"private","last_name":"Wd","username":"dd"},"date":1435478744,"document":{"file_name":"Text File","thumb":{},"file_id":"BQADBQADMwIAAsYifgZ_CEh0u682xwI","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":446}}'
     msg = types.Message.de_json(json_string)
     assert msg.document.file_name == 'Text File'
     assert msg.content_type == 'document'
 
 
 def test_json_Message_Photo():
-    json_string = r'{"message_id":96,"from":{"id":109734,"first_name":"Fd","last_name":"Wd","username":"dd"},"chat":{"id":10734,"first_name":"Fd","type":"private","last_name":"dd","username":"dd"},"date":1435478191,"photo":[{"file_id":"AgADBQADIagxG8YifgYv8yLSj76i-dd","file_size":615,"width":90,"height":67},{"file_id":"AgADBQADIagxG8YifgYv8yLSj76i-dd","file_size":10174,"width":320,"height":240},{"file_id":"dd-A_LsTIABFNx-FUOaEa_3AABAQABAg","file_size":53013,"width":759,"height":570}]}'
+    json_string = r'{"message_id":96,"from":{"id":109734,"first_name":"Fd","last_name":"Wd","username":"dd","is_bot":true },"chat":{"id":10734,"first_name":"Fd","type":"private","last_name":"dd","username":"dd"},"date":1435478191,"photo":[{"file_id":"AgADBQADIagxG8YifgYv8yLSj76i-dd","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":615,"width":90,"height":67},{"file_id":"AgADBQADIagxG8YifgYv8yLSj76i-dd","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":10174,"width":320,"height":240},{"file_id":"dd-A_LsTIABFNx-FUOaEa_3AABAQABAg","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":53013,"width":759,"height":570}]}'
     msg = types.Message.de_json(json_string)
     assert len(msg.photo) == 3
     assert msg.content_type == 'photo'
 
 
 def test_json_Message_Video():
-    json_string = r'{"message_id":101,"from":{"id":109734,"first_name":"dd","last_name":"dd","username":"dd"},"chat":{"id":109734,"first_name":"dd","type":"private","last_name":"dd","username":"dd"},"date":1435481960,"video":{"duration":3,"caption":"","width":360,"height":640,"thumb":{"file_id":"AAQFABPiYnBjkDwMAAIC","file_size":1597,"width":50,"height":90},"file_id":"BAADBQADNifgb_TOPEKErGoQI","file_size":260699}}'
+    json_string = r'{"message_id":101,"from":{"id":109734,"first_name":"dd","last_name":"dd","username":"dd","is_bot":true },"chat":{"id":109734,"first_name":"dd","type":"private","last_name":"dd","username":"dd"},"date":1435481960,"video":{"duration":3,"caption":"","width":360,"height":640,"thumb":{"file_id":"AAQFABPiYnBjkDwMAAIC","file_unique_id": "AQADTeisa3QAAz1nAAI","file_size":1597,"width":50,"height":90},"file_id":"BAADBQADNifgb_TOPEKErGoQI","file_unique_id": "AgADbgEAAn8VSFY","file_size":260699}}'
     msg = types.Message.de_json(json_string)
     assert msg.video
     assert msg.video.duration == 3
@@ -87,39 +119,41 @@ def test_json_Message_Video():
 
 
 def test_json_Message_Location():
-    json_string = r'{"message_id":102,"from":{"id":108734,"first_name":"dd","last_name":"dd","username":"dd"},"chat":{"id":1089734,"first_name":"dd","type":"private","last_name":"dd","username":"dd"},"date":1535482469,"location":{"longitude":127.479471,"latitude":26.090577}}'
+    json_string = r'{"message_id":102,"from":{"id":108734,"first_name":"dd","last_name":"dd","username":"dd","is_bot":true },"chat":{"id":1089734,"first_name":"dd","type":"private","last_name":"dd","username":"dd"},"date":1535482469,"location":{"longitude":127.479471,"latitude":26.090577}}'
     msg = types.Message.de_json(json_string)
     assert msg.location.latitude == 26.090577
     assert msg.content_type == 'location'
 
 
 def test_json_UserProfilePhotos():
-    json_string = r'{"total_count":1,"photos":[[{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAATZH_SpyZjzIwdVAAIC","file_size":6150,"width":160,"height":160},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAATOiTNi_YoJMghVAAIC","file_size":13363,"width":320,"height":320},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAAQW4DyFv0-lhglVAAIC","file_size":28347,"width":640,"height":640},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAAT50RvJCg0GQApVAAIC","file_size":33953,"width":800,"height":800}]]}'
+    json_string = r'{"total_count":1,"photos":[[{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAATZH_SpyZjzIwdVAAIC","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":6150,"width":160,"height":160},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAATOiTNi_YoJMghVAAIC","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":13363,"width":320,"height":320},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAAQW4DyFv0-lhglVAAIC","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":28347,"width":640,"height":640},{"file_id":"AgADAgADqacxG6wpRwABvEB6fpeIcKS4HAIkAAT50RvJCg0GQApVAAIC","file_unique_id": "AQAD_QIfa3QAAyA4BgAB","file_size":33953,"width":800,"height":800}]]}'
     upp = types.UserProfilePhotos.de_json(json_string)
     assert upp.photos[0][0].width == 160
     assert upp.photos[0][-1].height == 800
 
 
 def test_json_contact():
-    json_string = r'{"phone_number":"00011111111","first_name":"dd","last_name":"ddl","user_id":8633}'
+    json_string = r'{"phone_number":"00011111111","first_name":"dd","last_name":"ddl","user_id":8633,"vcard":"SomeContactString"}'
     contact = types.Contact.de_json(json_string)
     assert contact.first_name == 'dd'
     assert contact.last_name == 'ddl'
 
 
 def test_json_voice():
-    json_string = r'{"duration": 0,"mime_type": "audio/ogg","file_id": "AwcccccccDH1JaB7w_gyFjYQxVAg","file_size": 10481}'
+    json_string = r'{"duration": 0,"mime_type": "audio/ogg","file_id": "AwcccccccDH1JaB7w_gyFjYQxVAg","file_unique_id": "AgADbAEAAn8VSFY","file_size": 10481}'
     voice = types.Voice.de_json(json_string)
     assert voice.duration == 0
     assert voice.file_size == 10481
 
+
 def test_json_update():
-    json_string = r'{"update_id":938203,"message":{"message_id":241,"from":{"id":9734,"first_name":"Fk","last_name":"Wg","username":"nir"},"chat":{"id":1111,"first_name":"Fk","type":"private","last_name":"Wg","username":"oir"},"date":1441447009,"text":"HIHI"}}'
+    json_string = r'{"update_id":938203,"message":{"message_id":241,"from":{"is_bot":true,"id":9734,"first_name":"Fk","last_name":"Wg","username":"nir"},"chat":{"id":1111,"first_name":"Fk","type":"private","last_name":"Wg","username":"oir"},"date":1441447009,"text":"HIHI"}}'
     update = types.Update.de_json(json_string)
     assert update.update_id == 938203
     assert update.message.message_id == 241
     assert update.message.from_user.id == 9734
 
+
 def test_json_chat():
     json_string = r'{"id": -111111,"title": "Test Title","type": "group"}'
     chat = types.Chat.de_json(json_string)
@@ -127,6 +161,7 @@ def test_json_chat():
     assert chat.type == 'group'
     assert chat.title == 'Test Title'
 
+
 def test_InlineQueryResultCachedPhoto():
     iq = types.InlineQueryResultCachedPhoto('aaa', 'Fileid')
     json_str = iq.to_json()
@@ -143,6 +178,7 @@ def test_InlineQueryResultCachedPhoto_with_title():
     assert 'Title' in json_str
     assert 'caption' not in json_str
 
+
 def test_InlineQueryResultCachedPhoto_with_markup():
     markup = types.InlineKeyboardMarkup()
     markup.add(types.InlineKeyboardButton("Google", url="http://www.google.com"))
@@ -155,3 +191,57 @@ def test_InlineQueryResultCachedPhoto_with_markup():
     assert 'caption' not in json_str
     assert 'reply_markup' in json_str
 
+
+def test_json_poll_1():
+    jsonstring = r'{"message_id": 395020,"from": {"id": 111,"is_bot": false,"first_name": "FN","last_name": "LN","username": "Badiboy","language_code": "ru"},"chat": {"id": 111,"first_name": "FN","last_name": "LN","username": "Badiboy","type": "private"},"date": 1587841239,"poll": {"id": "5272018969396510722","question": "Test poll 1","options": [{"text": "Answer 1","voter_count": 0},{"text": "Answer 2","voter_count": 0}],"total_voter_count": 0,"is_closed": false,"is_anonymous": true,"type": "regular","allows_multiple_answers": true}}'
+    msg = types.Message.de_json(jsonstring)
+    assert msg.poll is not None
+    assert isinstance(msg.poll, types.Poll)
+    assert msg.poll.id == '5272018969396510722'
+    assert msg.poll.question is not None
+    assert msg.poll.options is not None
+    assert len(msg.poll.options) == 2
+    assert msg.poll.allows_multiple_answers is True
+
+
+def test_json_poll_answer():
+    jsonstring = r'{"poll_id": "5895675970559410186", "user": {"id": 329343347, "is_bot": false, "first_name": "Test", "username": "test_user", "last_name": "User", "language_code": "en"}, "option_ids": [1]}'
+    __import__('pprint').pprint(__import__('json').loads(jsonstring))
+    poll_answer = types.PollAnswer.de_json(jsonstring)
+    assert poll_answer.poll_id == '5895675970559410186'
+    assert isinstance(poll_answer.user, types.User)
+    assert poll_answer.option_ids == [1]
+
+
+def test_KeyboardButtonPollType():
+    markup = types.ReplyKeyboardMarkup()
+    markup.add(types.KeyboardButton('send me a poll', request_poll=types.KeyboardButtonPollType(type='quiz')))
+    json_str = markup.to_json()
+    assert 'request_poll' in json_str
+    assert 'quiz' in json_str
+
+
+def test_json_chat_invite_link():
+    json_string = r'{"invite_link":"https://t.me/joinchat/MeASP-Wi...","creator":{"id":927266710,"is_bot":false,"first_name":">_run","username":"coder2020","language_code":"ru"},"pending_join_request_count":1,"creates_join_request":true,"is_primary":false,"is_revoked":false}'
+    invite_link = types.ChatInviteLink.de_json(json_string)
+    assert invite_link.invite_link == 'https://t.me/joinchat/MeASP-Wi...'
+    assert isinstance(invite_link.creator, types.User)
+    assert not invite_link.is_primary
+    assert not invite_link.is_revoked
+    assert invite_link.expire_date is None
+    assert invite_link.member_limit is None
+    assert invite_link.name is None
+    assert invite_link.creator.id == 927266710
+    assert invite_link.pending_join_request_count == 1
+    assert invite_link.creates_join_request
+
+
+def test_chat_member_updated():
+    json_string = r'{"chat": {"id": -1234567890123, "type": "supergroup", "title": "No Real Group", "username": "NoRealGroup"}, "from": {"id": 133869498, "is_bot": false, "first_name": "Vincent"}, "date": 1624119999, "old_chat_member": {"user": {"id": 77777777, "is_bot": false, "first_name": "Pepe"}, "status": "member"}, "new_chat_member": {"user": {"id": 77777777, "is_bot": false, "first_name": "Pepe"}, "status": "administrator"}}'
+    cm_updated = types.ChatMemberUpdated.de_json(json_string)
+    assert cm_updated.chat.id == -1234567890123
+    assert cm_updated.from_user.id == 133869498
+    assert cm_updated.date == 1624119999
+    assert cm_updated.old_chat_member.status == "member"
+    assert cm_updated.new_chat_member.status == "administrator"
+