NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #2283 most downloaded on PyPI
Modern and fully asynchronous framework for Telegram Bot API
Last release 23 days ago
26 Aug 2026
Ships fairly regularly
a new release about every 5 weeks
Nearly every release is documented
notes for 58 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
9 years old
128 releases · first in 2017
Added full support of Bot API 6.4
Chat.promote shortcut arguments (#1082)aioredis to redis.asyncio (#1074)ChatJoinRequest by ChatTypeFilter (#1027)Fixed Message shortucts for non-forum chats, but getting the message_thread_id field
message_thread_id field (#1062)One column per quarter.
Added full support of Bot API 6.3
create_invite_link, edit_invite_link (#1026)Bugfix: Added field can_manage_video_chats to ChatMemberOwner
can_manage_video_chats to ChatMemberOwner (#1003)get_custom_emoji_stickers method (#1002)Fixed LifetimeControllerMiddleware: ` ... venv\lib\site-packages\aiogram\dispatcher\middlewares.py", line 121, in skip_actions f"pre_process_{item}",
LifetimeControllerMiddleware:... venv\lib\site-packages\aiogram\dispatcher\middlewares.py", line 121, in skip_actions
f"pre_process_{item}",
NameError: name 'item' is not defined
Added full support of Bot API 6.2
skip_patterns (#868)RedisStorage2.get_states_list method (#857)BotCommand object (#935)reset_bucket method (#970, #971)Deprecated emoji module until 2.22 version
from_id property to Message (#899)ChatTypeFilter works with inline queries (#915)protect_content to webhook responses (#804)Dispatcher.release_key (#908)Deleted deprecated CHOSEN_INLINE_QUERY
ban_chat_member function doc string (#867)__setitem__ in fields (#806)Small changes in doc-strings and annotations (#820, #818, #809)
:rocket: Support Bot API 5.6 (#801) by @Olegt0rr
disable_web_page_preview parameter (#695) by @samuelfirstFixed unnecessary until_date argument in banChatSenderChat method, in due to Bot API docs has an bug (already fixed by Telegram devs)
until_date argument in banChatSenderChat method, in due to Bot API docs has an bug (already fixed by Telegram devs) (#772):rocket: Added full support of Bot API 5.5
Retry-After (#765)FSMContextProxy.update method (#755)Added full support of Telegram Bot API 5.4
Bot.download_file aliases ability to save files to a directory and automatically create directories (#694)hide_link (#738)send_media_group (#742)send_voice (#722)BREAKING!
If you use bot.session, dispatcher.loop or bot.loop pleas don't to that anymore, you should create you're own client session and or already running event loop from asyncio instead of using internally created session and loop.
Fixed saving files (#665), added separate parameters for saving to directory and file (by #677)
url & get_mention in User (#679)Fixed ChatMember type detection via adding customizable object serialization mechanism (#624, #623)
Fixed unused default locale in I18nMiddleware (#562, #563)
Nothing published for this version
Full support of Bot API 5.3 (#610, #614)
Message.send_copy method for polls (#603)GroupDeactivated exception (#549caption_entities field in InputMedia base class (#583)pre (#597 fixes issues #596 and #481)Message.get_full_command method for messages with caption (#576)MongoStorage: remove documents with empty data from aiogram_data collection to save memory. (#609)Fixed internal call to deprecated 'is_private' method
provider_data argument in sendInvoice method callBot.*_chat_invite_link() methods #548 (#549)allowed_updates argument in Polling mode (#564)Fixed TypeError: Value should be instance of 'User' not 'NoneType'
TypeError: Value should be instance of 'User' not 'NoneType' (#527)Chat.message_auto_delete_time field (#535)MediaGroup filter (#528)Chat.delete_message shortcut (#526)aiogram.types.Document (#431)TelegramObject.__setitem__ when Telegram adds a new field (#532)examples/chat_type_filter.py (#533)Removed deprecation warning from Message.send_copy
FSMContextProxy.setdefault method (#491)Message.answer_location and Message.reply_location unable to send live location (#497)user_id and chat_id getters from the context at Dispatcher check_key, release_key and throttle methods (#520)Chat.update_chat method and all similar situations (#516)MediaGroup attach methods (#514)ContentTypes.DICE (#466)vcard argument to InputContactMessageContent constructor (#473)MessageIdInvalid, CantRestrictChatOwner and UserIsAnAdministratorOfTheChat (#474, #512)answer_chat_action to the Message object (#501)message.send_copy method (#511)Message.send_copysplit_separator argument to safe_split_text (#515)Added missing "supports_streaming" argument to answer_video method #462
Fix MessageEntity serialization for API calls #457
Added alias to Message object Message.copy_to with deprecation of Message.send_copy
close was named in Bot class as close_bot in due to Bot instance already has method with the same name. It will be changed in aiogram 3.0Message.copy_to with deprecation of Message.send_copyChatType.SUPER_GROUP renamed to ChatType.SUPERGROUP (#438):fire: Big thanks to @Olegt0rr for #454
Fixed critical bug with getting asyncio event loop in executor. (#424) AttributeError: 'NoneType' object has no attribute 'run_until_complete'
Fixed critical bug with getting asyncio event loop in executor. (#424)
AttributeError: 'NoneType' object has no attribute 'run_until_complete'
Breaking change: Stop using \_MainThread event loop in bot/dispatcher instances
and many others documentation and examples changes:
rexex -> regex (#386)Fixed Message.get_full_command() #352 Fixed markdown util #353
Fixed Message.get_full_command() #352 Fixed markdown util #353
Added full support of Telegram Bot API 4.9
get_me (#296):dart: Added full support of Bot API 4.8
Message.answer_dice and Message.reply_dice methods (#306):game_die: Added full support of Bot API 4.7 (#294 #289)
Fixed reply KeyboardButton initializer with request_poll argument
aiogram.types.PollType).as_* and .to_* methods. It will no more mutate the object. (#247)Full support of Telegram Bot API v4.6 (Polls 2.0) #265
- #255 Updated CallbackData factory validity check. More correct for non-latin symbols - #256 Fixed renamed_argument decorator error - #257 One more f
renamed_argument decorator errorGet back quote_html and escape_md functions
quote_html and escape_md functions- Hot-fix of CommandStart filter
Added full support of Telegram Bot API 4.5 (#250, #251)
check_token methodsetup.py. No more use of internal pip APIAdded Message.send_copy method (forward message without forwarding)
Full support of Telegram Bot API 4.4
Modified bot privacy mode for the sake of consistency.
Your bot can now get updates about posts in channels . Added new fields channel_post and edited_channel_post to Update .
You can now update high scores to a lower value by using the new force parameter in setGameScore . Handy for punishing cheaters or fixing errors in your game's High Score table.
Starting today, messages with high scores will be updated with new high scores by default. Use disable_edit_message in setGameScore if you don't want this.
The edit_message parameter from setGameScore is no longer in use. For backward compatibility, it will be taken into account for a while, unless disable_edit_message is passed explicitly.
Added the new field forward_from_message_id to Message .
Added the new parameter cache_time to answerCallbackQuery . Will eventually work in Telegram apps - somewhere after version 3.14, maybe 3.15.
Renamed hide_keyboard to remove_keyboard in ReplyKeyboardRemove for clarity. hide_keyboard will still work for a while for backward compatibility.
Bot API 2.2. Introducing a new Gaming Platform! See this introduction for a brief overview. If you're not a developer, you may like this user-friendly blog post better.
New tools for building HTML5 games .
New method sendGame , new object InlineQueryResultGame , new field game in Message .
New parameter url in answerCallbackQuery . Create a game and accept the conditions using Botfather to send custom urls that open your games for the user.
New field callback_game in InlineKeyboardButton , new fields game_short_name and chat_instance in CallbackQuery , new object CallbackGame .
New methods setGameScore and getGameHighScores .
Other changes
Making life easier for webhook users. Added a detailed Guide to All Things Webhook that describes every pothole you can run into on the webhook road.
New method getWebhookInfo to check current webhook status.
Added the option to specify an HTTP URL for a file in all methods where InputFile or file_id can be used (except voice messages). Telegram will get the file from the specified URL and send it to the user. Files must be smaller than 5 MB for photos and smaller than 20 MB for all other types of content.
Use the new url parameter in answerCallbackQuery to create buttons that open your bot with user-specific parameters.
Added new field switch_inline_query_current_chat in InlineKeyboardButton .
Added caption fields to sendAudio , sendVoice , InlineQueryResultAudio , InlineQueryResultVoice , InlineQueryResultCachedAudio , and InlineQueryResultCachedVoice .
New field all_members_are_administrators in the Chat object.
Certain server responses may now contain the new parameters field with expanded info on errors that occurred while processing your requests.
Inline keyboards may now be used in group chats. Channels coming soon.
Check out @vote and @like for examples.
Bot API 2.1. Added more tools for group administrator bots. Your bot can now get a list of administrators and members count in a group, check a user's current status (administrator, creator, left the group, kicked from the group), and leave a group.
Added new methods: getChat , leaveChat , getChatAdministrators , getChatMember , getChatMembersCount .
Added support for edited messages and new mentions from Telegram v.3.9. New fields: edited_message in Update , edit_date in Message , user in MessageEntity . New value text_mention for the type field in MessageEntity .
Added the field emoji to the Sticker object. Your bot can now know the emoji a sticker corresponds to.
Added the field forward_from_chat to the Message object for messages forwarded from channels.
Introducing Bot API 2.0 . Check out this page for a review of this major update.
New inline keyboards with callback and URL buttons . Added new objects InlineKeyboardMarkup , InlineKeyboardButton and CallbackQuery , added reply_markup fields to all InlineQueryResult objects. Added field callback_query to the Update object, new method answerCallbackQuery .
Bots can now edit their messages . Added methods editMessageText , editMessageCaption , editMessageReplyMarkup .
Bots can request location and phone number from the user. The keyboard field in the object ReplyKeyboardMarkup now supports KeyboardButton , a new object that can have the fields request_location and request_contact .
Inline bots
Added support for all content types available on Telegram. 19 types of InlineQueryResult objects are now supported.
Inline bots can now substitute all kinds of content with text. Added 4 types of InputMessageContent objects.
Your inline bot can also ask users for permission to use their location. Added the new Botfather command /setinlinegeo , added field location to the InlineQuery object, added fields location and inline_message_id to the ChosenInlineResult object.
Added an easy way to switch between inline mode and a private chat with the bot - useful for settings, establishing external connections and teaching users how to use your bot in inline mode. Added parameters switch_pm_text and switch_pm_parameter to the method answerInlineQuery .
Miscellaneous
Added group administration tools. New methods kickChatMember and unbanChatMember .
Added fields venue , pinned_message and entities to the Message object. Added new objects MessageEntity and Venue , new methods sendVenue and sendContact .
Renamed the fields new_chat_participant and left_chat_participant of the Message object to new_chat_member and left_chat_member .
Added the disable_notification parameter to all methods that send messages or any kind.
Removed backward compatibility from the method sendAudio . Voice messages now must be sent using the method sendVoice . There is no more need to specify a non-empty title or performer while sending the audio by file_id .
Added support for Inline Mode , a new way for people to contact your bot by typing its username and a query in the text input field in any chat. Enable by sending /setinline to @BotFather .
New optional field inline_query added to the Update object.
Added new method answerInlineQuery and new objects InlineQuery , InlineQueryResultArticle , InlineQueryResultPhoto , InlineQueryResultGif , InlineQueryResultMpeg4Gif and InlineQueryResultVideo .
Added support for supergroups . The Type field in the Chat object can now contain 'supergroup'.
New optional fields added to the Message object: supergroup_chat_created , migrate_to_chat_id , migrate_from_chat_id and channel_chat_created .
Added initial channel support for bots (no Telegram clients support this at the moment, please wait for updates):
The Chat field in the Message is now of the new type Chat .
You can now pass a channel username (in the format @channelusername ) in the place of chat_id in all methods (and instead of from_chat_id in forwardMessage ). For this to work, the bot must be an administrator in the channel (and that's exactly what Telegram clients don't support yet - adding bots as administrators coming soon).
Bots can now download files and media sent by users.
Added getFile and File .
You can now pass parameters using application/json (please note that this doesn't work for file uploads: use multipart/form-data to upload files).
Added very basic markdown support . New field parse_mode added to sendMessage . For the moment messages with markdown will be displayed correctly only in Telegram for Android . Other official apps will catch up soon.
Added support for self-signed certificates: upload your certificate using the certificate parameter in the setWebhook method.
You can now make new requests when responding to webhook updates.
Added new type Voice and new method sendVoice for sending voice messages.
Earlier Audio and sendAudio should now be used for sending music files. Telegram clients will show such files in the in-app music player. If you were using sendAudio for your bot to send voice messages, please use sendVoice instead.
Added optional fields performer , title to the Audio object and sendAudio method.
Added optional field voice to the Message object.
The thumb field is now optional for Video , Sticker and Document objects
The API now supports both video and photo captions. The caption field has been removed from the Video object and added to the Message object instead.
caption and duration optional fields have been added to the sendVideo method.
Fixed typo: user_id in the Contact object is now correctly labeled as Integer, not String
The bot platform is officially launched .
Back to the Bot API Manual »
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
FAQ
Privacy
Press
iPhone/iPad
Android
Mobile Web
PC/Mac/Linux
macOS
Web-browser
API
Translations
Instant View
Provides latest Telegram Bot API (4.3)
data -> bucket in update_bucket for RedisStorage2 (#132)Implemented all new features from Telegram Bot API 4.2
is_member and is_admin methods of ChatMember and ChatMemberStatus was renamed to is_chat_member and is_chat_adminfunc filterMessage.edit_caption, Message.edit_media, Message.edit_reply_markup) (#121, #103, #104, #112)answer* methods to Message object (#112)CallbackData factoryCommandStart filterrequirements.txt and dev_requirements.txt filesImplemented CallbackData factory (example)
tar.gz #84ChatIdIsEmpty and NotEnoughRightsToRestrict)New syntax for annotations (PEP-563).
aiogram.utils.context;aiohttp_socks instead of aiosocksy for Socks4/5 proxy;types.ContentType was divided to types.ContentType and types.ContentTypes;.current() method in bot and dispatcher objects was renamed to get_current();You can read more details about this release in migration FAQ: https://aiogram.readthedocs.io/en/latest/migration_1_to_2.html
Added the ability to reply to messages in other chats or forum topics.
Added the class ExternalReplyInfo and the field external_reply of type ExternalReplyInfo to the class Message , containing information about a message that is replied to by the current message, but can be from another chat or forum topic.
Added the ability to quote a part of the replied message.
Added the class TextQuote and the field quote of type TextQuote to the class Message , which contains the part of the replied message text or caption that is quoted in the current message.
Added the class ReplyParameters and replaced parameters reply_to_message_id and allow_sending_without_reply in the methods copyMessage , sendMessage , sendPhoto , sendVideo , sendAnimation , sendAudio , sendDocument , sendSticker , sendVideoNote , sendVoice , sendLocation , sendVenue , sendContact , sendPoll , sendDice , sendInvoice , sendGame , and sendMediaGroup with the field reply_parameters of type ReplyParameters .
Link Preview Customization
Allowed to explicitly specify the URL that will be used for link preview generation in outgoing text messages.
Allowed to position link previews above the message text.
Allowed to choose media size in link previews.
Added the class LinkPreviewOptions and replaced the parameter disable_web_page_preview with link_preview_options in the methods sendMessage and editMessageText .
Replaced the field disable_web_page_preview with link_preview_options in the class InputTextMessageContent .
Added the field link_preview_options to the class Message with information about the link preview options used to send the message.
Block Quotation
Added support for “blockquote” entities in received messages.
Added support for “blockquote” entity parsing in “MarkdownV2” and “HTML” parse modes.
Allowed to explicitly specify “blockquote” entities in formatted texts.
Multiple Message Actions
Added the method deleteMessages to allow the deletion of multiple messages in a single request.
Added the method forwardMessages for forwarding of multiple messages in a single request.
Added the method copyMessages for copying of multiple messages in a single request.
Request for multiple users
Renamed the class KeyboardButtonRequestUser to KeyboardButtonRequestUsers and added the field max_quantity to it.
Renamed the field request_user in the class KeyboardButton to request_users . The old name will still work for backward compatibility.
Added the class UsersShared .
Replaced the field user_shared in the class Message with the field users_shared .
Chat Boost
Added updates about chat boost changes, represented by the classes ChatBoostUpdated and ChatBoostRemoved and the fields chat_boost and removed_chat_boost in the class Update . The bot must be an administrator in the chat to receive these updates.
Added the classes ChatBoostSourcePremium , ChatBoostSourceGiftCode and ChatBoostSourceGiveaway , representing different sources of a chat boost.
Added the method getUserChatBoosts for obtaining the list of all active boosts a user has contributed to a chat.
Giveaway
Added the class Giveaway and the field giveaway to the class Message for messages about scheduled giveaways.
Added the class GiveawayCreated and the field giveaway_created to the class Message for service messages about the creation of a scheduled giveaway.
Added the class GiveawayWinners and the field giveaway_winners to the class Message for messages about the completion of a giveaway with public winners.
Added the class GiveawayCompleted and the field giveaway_completed to the class Message for service messages about the completion of a giveaway without public winners.
Web App Changes
Added the field SettingsButton to the class WebApp .
Added the fields header_bg_color , accent_text_color , section_bg_color , section_header_text_color , subtitle_text_color , destructive_text_color to the class ThemeParams .
Web Apps no longer close when the method WebApp.openTelegramLink is called.
Other Changes
Added support for the fields emoji_status_custom_emoji_id and emoji_status_expiration_date in the class Chat for non-private chats.
Added the fields accent_color_id , background_custom_emoji_id , profile_accent_color_id , and profile_background_custom_emoji_id to the class Chat .
Added the field has_visible_history to the class Chat .
Added the class MessageOrigin and replaced the fields forward_from , forward_from_chat , forward_from_message_id , forward_signature , forward_sender_name , and forward_date with the field forward_origin of type MessageOrigin in the class Message .
Improved documentation for the field message of the class callbackQuery and the field pinned_message of the class Message by adding the classes MaybeInaccessibleMessage and InaccessibleMessage .
- Bot API 4.0
Bot API 4.0 ( #57 )
Now InlineQueryResultLocation has live_period;
Fixed crashing of polling process. (i think)
Nothing published for this version
Allow to use Socks5 proxy (need manually install aiosocksy).
aiosocksy).aiogram.utils.executor module.Fixed compability of setup.py with pip 10.0.0
setup.py with pip 10.0.0Implemented method InputFile.from_url(url: str) for downloading files.
InputFile.from_url(url: str) for downloading files.Fixed handling Venue's [#27, #26]
Full provide Telegram Bot API 3.6
Fatal Python error: PyImport_GetModuleDict: no module dictionary!Added more methods for data types (like message.reply_sticker(...) or file.download(...)
message.reply_sticker(...) or file.download(...)Bot( ... , parse_mode='HTML')Middleware.on_pre_process_<event type>aiogram.contrib.fsm_storage.rethinkdb)Nothing published for this version
Added example for middlewares and throttling manager.
Nothing published for this version
Danger! Fixed typo in word pooling. Now whatever all methods with that word marked as deprecated and original methods is renamed to polling. Check it…
types.InputFile for more easy sending local filestypes.ChatActions)Remaked data types serialozation/deserialization mechanism (Speed up).
BaseStorage.close() is awaitable! (FSM)aiogram.utils.context.ujson.In process: Tests and more pages of docs.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →