Join GitHub today
Transition guide to Version 4.0
All changes can also be reviewed in our official documentation!
For users coming from RC release predating 26th of April, 2016:
- Changes in "filters" syntax (upper/lower case)
- Handler groups are now identified by
intonly, and are processed in order, smallest first.
Dispatcher class has now a cleaner interface and more precise Message filtering. Instead of many methods with long names like
Dispatcher.addTelegramMessageHandler(handler), we now only have two of those methods:
Register a handler.
TL;DR: Order and priority counts. 0 or 1 handlers per group will be used.
A handler must be an instance of a subclass of
telegram.ext.Handler. All handlers are organized in groups with a numeric value. The default group is
0. All groups will be evaluated for handling an update, but only 0 or 1 handler per group will be used.
The priority/order of handlers is determined as follows:
- Priority of the group (lower group number == higher priority)
- The first handler in a group which should handle an update will be used. Other handlers from the group will not be used. The order in which handlers were added to the group defines the priority.
handler (Handler)– A Handler instance
group (optional[int])– The group identifier. Default is
This method remains unchanged, only the name has been changed to snake_case.
add_handler method is accepting an object of a subclass of
telegram.ext.Handler. Let's see how that looks in real life:
from telegram.ext import MessageHandler, Filters def text_callback(bot, update): print("New text message: " + update.message.text) dispatcher.add_handler(MessageHandler([Filters.text], text_callback))
As you can see here, the
MessageHandler class is one of the included
Handler subclasses. All that was possible before is still possible, but now more organized and more explicit. Lets take a quick look at another handler class, the
from telegram.ext import RegexHandler def name_callback(bot, update, groupdict): print("The name of the user is: " + groupdict['name']) name_regex = r'My name is (?P<name>.*)' dispatcher.add_handler(RegexHandler(name_regex, text_callback, pass_groupdict=True))
Here you can see the optional argument
groupdict passed to the handler callback function. Note that it is necessary to specify this explicitly when creating the
- You can easily implement your own handlers. Just subclass
telegram.ext.handlerand take a look at the implementation of the provided handlers.
- Instead of
addTelegramInlineHandlerthere are now
- There is no replacement for
addUnknownTelegramCommandHandler. Instead, it is recommended to use
RegexHandler(r'/.*', ...)and add it as the last handler
contextparameters have been removed
Bot API 2.0
Please read the documentation of the Telegram Bot API to learn about all the new things in version 2 of the bot API. This section covers only those changes that are not backwards compatible and not listed in the Recent Changes list.
Messageclass are now
- The following parameters on
InlineQueryResultobjects are removed in favor of
mime_typehas been removed. JPEG is now required.
ReplyKeyboardMarkupnow takes a list of a list of
KeyboardButtoninstead of strings.
- From v4.0.2 you can use
JobQueue that were previously available for import directly
from telegram are now located in