In V12.0b1 we added a persistence mechanism totelegram.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?
• Refreshing at runtime
• Storing Bots

• The persistence structure is designed to make

  • bot_data
  • chat_data
  • user_data,
  • ConversationHandler's states and
  • ExtBot.callback_data_cache persistent.

• Job's and thejob_queue is not supported.However, the currentJobQueue backendAPScheduler has its own persistence logic that you can leverage.See e.g.ptbcontrib/ptb_jobstores

• For a special note aboutBot instances, seebelow

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 fromBasePersistence and implement all abstract methods
• 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 doesnot actually write any data to file/database.

Instead of manually handling a database to store data, consider implementing a subclass ofBasePersistence. This allows you to simply pass an instance of that subclass to theApplication 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 onBasePersistence. 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 inptbcontrib.

These 3rd party packages contain persistence classes (the list is incomplete):

• python-telegram-bot-django-persistence - Uses Django ORM to store persistence data. It is most useful for projects, that use PTB and Django.
• MongoPersistence - Package to add persistence to your telegram bot and upload data to your mongo database.

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

• Create a persistence object (e.g.my_persistence = PicklePersistence(filepath='my_file'))
• ConstructApplication with the persistence (Application.builder().token('TOKEN').persistence(persistence=my_persistence).build()).

This is enough to makeuser_data,bot_data,chat_data andExtBot.callback_data_cache persistent.To make a conversation handler persistent (save states between bot restarts) youmust name it and setpersistent toTrue.For exampleConversationHandler(..., persistent=True, name='my_name').persistent isFalse by default.Adding these arguments and adding the conversation handler to a persistence-awareApplication will make it persistent.

When starting theApplication withApplication.start() orApplication.run_{polling, webhook}, it will loads the data from the persistence on startup and automatically update the persistence in regular intervals.You can customize the interval via theupdate_interval argument ofBase/Pickle/Dict/…Persistence.

You can also selectively store only some of{bot,chat,user,callback}_data by passing aPersistenceInput to thestore_data argument your persistence class.

If your persistence reads the data from an external database, the entries in this database could change at runtime.This is the case in particular, if the entries in the database are created by a 3rd party service independently of your bot.If you want to make sure that the data incontext.user/chat/bot_data are always up-to-date, your persistence class should implement the methodsrefresh_bot/chat/user_data.Those will be called when in update comes in, before any of your callbacks are called.

These methods can also be useful to implement a lazy-loading strategy.

Instances oftelegram.Bot should not be serialized, because changes to the bot don't apply to the serialized object.

For example, you might change thedefault values used by the bot.Or if you change the bots token, this may lead to e.g.Chat not found errors.This is relevant e.g., if you store Telegram objects likeMessage inbot/user/chat_data, as some of them hold a reference toApplication.bot (which is how the shortcuts likeMessage.reply_text work).

The interface classBasePersistence does not question what kind of data you supply to its methods.Hence, each implementation should take care that it does not try to serializetelegram.Bot instances.For example, it can check if the data equals the attributeBasePersistence.bot (which will be the bot object used by theApplication) and instead store a placeholder.When loading the data, theBasePersistence.bot can be reinserted instead of the placeholder.Indeed, this is basically what the built-inPicklePersistence does.

For more technical details, please refer to the documentation ofBasePersistence,PicklePersistence