Making your bot persistent

In V12.0b1 we added a persistence mechanism to telegram.ext. This wiki page is there to help you understand and set up persistence for your bots.

• What can become persistent?
• Included persistence classes
• 3rd party persistence classes
• What do I need to change?
• Storing Bots

What can become persistent?

• The persistence structure is designed to make bot_data, chat_data, user_data and ConversationHandler's states persistent.
• Job's and the job_queue is not supported because the serialization of callbacks is too unstable to reliably make persistent for broad user-cases. However, the current JobQueue backend APScheduler has it's own persistence logic that you can leverage.
• For a special note about Bot instances, see below

Included persistence classes

Three classes concerning persistence in bots have been added.

• BasePersistence - Is an interface class for persistence classes. If you create your own persistence classes to maintain a database-connection for example, you must inherit from BasePersistence
• PicklePersistence - Uses pickle files to make the bot persistent.
• DictPersistence - Uses in memory dicts and easy conversion to and from JSON to make the bot persistent. Note that this class is mainly intended as starting point for custom persistence classes that need to JSON-serialize the stored data before writing them to file/database and does not actually write any data to file/database.

3rd party persistence classes

Instead of manually handling a database to store data, consider implementing a subclass of BasePersistence. This allows you to simply pass an instance of that subclass to the Updater/Dispatcher and let PTB handle the loading, updating & storing of the data!

If you want to create your own persistence class, please carefully read the docs on BasePersistence. It will tell you what methods you need to overwrite.

If you've written a persistence class that could benefit others (e.g. a general one covering all types of data), it would be great if you linked it here or even better made it available in ptbcontrib.

What do I need to change?

To make your bot persistent you need to do the following.

• Create a persistence object (e.g. my_persistence = PicklePersistence(filename='my_file'))
• Construct Updater with the persistence (Updater('TOKEN', persistence=my_persistence, use_context=True))

Note that the Updater passes the persistence variable to the Dispatcher, so if you aren't using the Updater, you can set the persistence on your Dispatcher object instead.

This is enough to make user_data, bot_data and chat_data persistent. To make a conversation handler persistent (save states between bot restarts) you must name it and set persistent to True. Like ConversationHandler(<no change>, persistent=True, name='my_name'). persistent is False by default. Adding these arguments and adding the conversation handler to a persistence-aware updater/dispatcher will make it persistent.

Storing Bots

As of v13, persistence will automatically try to replace telegram.Bot instances by REPLACED_BOT and insert the bot set with set_bot upon loading of the data. This is to ensure that changes to the bot apply to the saved objects, too. For example, you might change the default values used by the bot. If you change the bots token, this may lead to e.g. Chat not found errors. For the limitations on replacing bots see replace_bot and insert_bot.

This is relevant e.g. if you store Telegram objects like Message in bot/user/chat_data, as some of them have a bot attribute, which holds a reference to the Dispatchers bot.