telegram.ext.dispatcher module

This module contains the Dispatcher class.

class telegram.ext.dispatcher.Dispatcher(bot, update_queue, workers=4, exception_event=None, job_queue=None)

Bases: object

This class dispatches all kinds of updates to its registered handlers.

  • bot (telegram.Bot) – The bot object that should be passed to the handlers
  • update_queue (Queue) – The synchronized queue that will contain the updates.
  • job_queue (Optional[telegram.ext.JobQueue]) – The JobQueue instance to pass onto handler callbacks
  • workers (Optional[int]) – Number of maximum concurrent worker threads for the @run_async decorator

Registers an error handler in the Dispatcher.

Parameters:handler (function) – A function that takes Bot, Update, TelegramError as arguments.
add_handler(handler, group=0)

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 (telegram.ext.Handler) – A Handler instance
  • group (Optional[int]) – The group identifier. Default is 0
chat_data = None

type – dict[int, dict]

dispatch_error(update, error)

Dispatches an error.

  • update (object) – The update that caused the error
  • error (telegram.TelegramError) – The Telegram error that was raised.
classmethod get_instance()

Get the singleton instance of this class.

groups = None

type – list[int]

handlers = None

type – dict[int, list[Handler]

logger = <logging.Logger object>

Processes a single update.

Parameters:update (object) –

De-registers an error handler.

Parameters:handler (function) –
remove_handler(handler, group=0)

Remove a handler from the specified group

  • handler (telegram.ext.Handler) – A Handler instance
  • group (optional[object]) – The group identifier. Default is 0
run_async(func, *args, **kwargs)

Queue a function (with given args/kwargs) to be run asynchronously.

  • func (function) – The function to run in the thread.
  • args (Optional[tuple]) – Arguments to func.
  • kwargs (Optional[dict]) – Keyword arguments to func.



Thread target of thread ‘dispatcher’. Runs in background and processes the update queue.


Stops the thread

user_data = None

type – dict[int, dict]


Function decorator that will run the function in a new thread.

Using this decorator is only possible when only a single Dispatcher exist in the system.

  • func (function) – The function to run in the thread.
  • async_queue (Queue) – The queue of the functions to be executed asynchronously.

Return type: