aiogram Documentation

Release 2.11.2

Illemius / Alex Root Junior

Nov 10, 2020

 CONTENTS

1 Official aiogram resources 3

2 Features 5

3 Contribute 7

4 Contents 9
4.1 Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3 Migration FAQ (1.4 -> 2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.4 Telegram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5 Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
4.6 Utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
4.7 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
4.8 Contribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
4.9 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

5 Indices and tables 227

Python Module Index 229

Index 231

i
ii
 aiogram Documentation, Release 2.11.2

aiogram is a pretty simple and fully asynchronous framework for Telegram Bot API written in Python 3.7 with asyncio
and aiohttp. It helps you to make your bots faster and simpler.

CONTENTS 1
aiogram Documentation, Release 2.11.2

2 CONTENTS
 CHAPTER

ONE

OFFICIAL AIOGRAM RESOURCES

• News: @aiogram_live
• Community: @aiogram
• Russian community: @aiogram_ru
• Pip: aiogram
• Docs: ReadTheDocs
• Source: Github repo
• Issues/Bug tracker: Github issues tracker
• Test bot: @aiogram_bot

3
aiogram Documentation, Release 2.11.2

4 Chapter 1. Official aiogram resources

 CHAPTER

TWO

FEATURES

• Asynchronous
• Awesome
• Makes things faster
• Has FSM
• Can reply into webhook. (In other words make requests in response to updates)

5
aiogram Documentation, Release 2.11.2

6 Chapter 2. Features
 CHAPTER

THREE

CONTRIBUTE

• Issue Tracker
• Source Code

7
aiogram Documentation, Release 2.11.2

8 Chapter 3. Contribute
 CHAPTER

FOUR

CONTENTS

4.1 Installation Guide

4.1.1 Using PIP

$ pip install -U aiogram

4.1.2 Using Pipenv

$ pipenv install aiogram

4.1.3 Using AUR

aiogram is also available in Arch User Repository, so you can install this framework on any Arch-based distribution
like ArchLinux, Antergos, Manjaro, etc. To do this, use your favorite AUR-helper and install the python-aiogram
package.

4.1.4 From sources

Development versions:

$ git clone https://github.com/aiogram/aiogram.git

$ cd aiogram
$ python setup.py install

Or if you want to install stable version (The same with version form PyPi):

$ git clone https://github.com/aiogram/aiogram.git

$ cd aiogram
$ git checkout master
$ python setup.py install

9
aiogram Documentation, Release 2.11.2

4.1.5 Recommendations

You can speedup your bots by following next instructions:

• Use uvloop instead of default asyncio loop.
uvloop is a fast, drop-in replacement of the built-in asyncio event loop. uvloop is implemented in
Cython and uses libuv under the hood.
Installation:

$ pip install uvloop

• Use ujson instead of the default json module.

UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python
2.5+ and 3.
Installation:

$ pip install ujson

• Use aiohttp speedups

– Use cchardet instead of the chardet module.
cChardet is a high speed universal character encoding detector.
Installation:

$ pip install cchardet

– Use aiodns for speeding up DNS resolving.

aiodns provides a simple way for doing asynchronous DNS resolutions.
Installation:

$ pip install aiodns

– Installing speedups altogether.

The following will get you aiohttp along with cchardet, aiodns and brotlipy in one
bundle.
Installation:

$ pip install aiohttp[speedups]

In addition, you don’t need do anything, aiogram automatically starts using that if it is found in your environment.

10 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

4.2 Quick start

4.2.1 Simple template

At first you have to import all necessary modules

import logging

from aiogram import Bot, Dispatcher, executor, types

Then you have to initialize bot and dispatcher instances. Bot token you can get from @BotFather

API_TOKEN = 'BOT TOKEN HERE'

# Configure logging
logging.basicConfig(level=logging.INFO)

# Initialize bot and dispatcher

bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

Next step: interaction with bots starts with one command. Register your first command handler:

@dp.message_handler(commands=['start', 'help'])
async def send_welcome(message: types.Message):
"""
This handler will be called when user sends `/start` or `/help` command
"""
await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")

If you want to handle all text messages in the chat simply add handler without filters:

@dp.message_handler()
async def echo(message: types.Message):
# old style:
# await bot.send_message(message.chat.id, message.text)

await message.answer(message.text)

Last step: run long polling.

if __name__ == '__main__':
executor.start_polling(dp, skip_updates=True)

4.2.2 Summary

1 """
2 This is a echo bot.
3 It echoes any incoming text messages.
4 """
5

6 import logging
7

8 from aiogram import Bot, Dispatcher, executor, types

(continues on next page)

4.2. Quick start 11

 aiogram Documentation, Release 2.11.2

(continued from previous page)

9

10 API_TOKEN = 'BOT TOKEN HERE'

11

12 # Configure logging
13 logging.basicConfig(level=logging.INFO)
14

15 # Initialize bot and dispatcher

16 bot = Bot(token=API_TOKEN)
17 dp = Dispatcher(bot)
18

19

20 @dp.message_handler(commands=['start', 'help'])
21 async def send_welcome(message: types.Message):
22 """
23 This handler will be called when user sends `/start` or `/help` command
24 """
25 await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
26

27

28

29 @dp.message_handler()
30 async def echo(message: types.Message):
31 # old style:
32 # await bot.send_message(message.chat.id, message.text)
33

34 await message.answer(message.text)
35

36

37 if __name__ == '__main__':
38 executor.start_polling(dp, skip_updates=True)

4.3 Migration FAQ (1.4 -> 2.0)

This update make breaking changes in aiogram API and drop backward capability with previous versions of frame-
work.
From this point aiogram supports only Python 3.7 and newer.

4.3.1 Changelog

• Used contextvars instead of aiogram.utils.context;

• Implemented filters factory;
• Implemented new filters mechanism;
• Allowed to customize command prefix in CommandsFilter;
• Implemented mechanism of passing results from filters (as dicts) as kwargs in handlers (like fixtures in pytest);
• Implemented states group feature;
• Implemented FSM storage’s proxy;
• Changed files uploading mechanism;
• Implemented pipe for uploading files from URL;

12 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• Implemented I18n Middleware;

• Errors handlers now should accept only two arguments (current update and exception);
• Used aiohttp_socks instead of aiosocksy for Socks4/5 proxy;
• types.ContentType was divided to types.ContentType and types.ContentTypes;
• Allowed to use rapidjson instead of ujson/json;
• .current() method in bot and dispatcher objects was renamed to get_current();

4.3.2 Instructions

Contextvars

Context utility (aiogram.utils.context) now is removed due to new features of Python 3.7 and all subclasses of
aiogram.types.base.TelegramObject, aiogram.Bot and aiogram.Dispatcher has .get_current()
and .set_current() methods for getting/setting contextual instances of objects.
Example:
async def my_handler(message: types.Message):
bot = Bot.get_current()
user = types.User.get_current()
...

Filters

Custom filters

Now func keyword argument can’t be used for passing filters to the list of filters instead of that you can pass the filters
as arguments:
@dp.message_handler(lambda message: message.text == 'foo')
@dp.message_handler(types.ChatType.is_private, my_filter)
async def ...

(func filter is still available until v2.1)

Filters factory

Also you can bind your own filters for using as keyword arguments:
from aiogram.dispatcher.filters import BoundFilter

class MyFilter(BoundFilter):
key = 'is_admin'

def __init__(self, is_admin):

self.is_admin = is_admin

async def check(self, message: types.Message):

member = await bot.get_chat_member(message.chat.id, message.from_user.id)
return member.is_chat_admin()
(continues on next page)

4.3. Migration FAQ (1.4 -> 2.0) 13

aiogram Documentation, Release 2.11.2

(continued from previous page)

dp.filters_factory.bind(MyFilter)

@dp.message_handler(is_admin=True)
async def ...

Customize commands prefix

Commands prefix can be changed by following one of two available methods:

@dp.message_handler(commands=['admin'], commands_prefix='!/')
@dp.message_handler(Command('admin', prefixes='!/'))
async def ...

Passing data from filters as keyword arguments to the handlers

You can pass any data from any filter to the handler by returning dict If any key from the received dictionary not in
the handler specification the key will be skipped and and will be unavailable from the handler
Before (<=v1.4)

async def my_filter(message: types.Message):

# do something here
message.conf['foo'] = 'foo'
message.conf['bar'] = 42
return True

@dp.message_handler(func=my_filter)
async def my_message_handler(message: types.Message):
bar = message.conf["bar"]
await message.reply(f'bar = {bar}')

Now (v2.0)

async def my_filter(message: types.Message):

# do something here
return {'foo': 'foo', 'bar': 42}

@dp.message_handler(my_filter)
async def my_message_handler(message: types.Message, bar: int):
await message.reply(f'bar = {bar}')

Other

Filters can also be used as logical expressions:

Text(equals='foo') | Text(endswith='Bar') | ~Text(contains='spam')

14 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

States group

You can use States objects and States groups instead of string names of the states. String values is still also be available.
Writing states group:

from aiogram.dispatcher.filters.state import State, StatesGroup

class UserForm(StatesGroup):
name = State() # Will be represented in storage as 'Form:name'
age = State() # Will be represented in storage as 'Form:age'
gender = State() # Will be represented in storage as 'Form:gender'

After that you can use states as UserForm.name and etc.

FSM storage’s proxy

Now Dispatcher.current_context() can’t be used as context-manager.

Implemented FSMContext.proxy() method which returns asynchronous FSMContextProxy context manager and can
be used for more simply getting data from the storage.
FSMContextProxy load all user-related data on initialization and dump it to the storage when proxy is closing if any
part of the data was changed.
Usage:

@dp.message_handler(commands=['click'])
async def cmd_start(message: types.Message, state: FSMContext):
async with state.proxy() as proxy: # proxy = FSMContextProxy(state); await proxy.
˓→load()

proxy.setdefault('counter', 0)
proxy['counter'] += 1
return await message.reply(f"Counter: {proxy['counter']}")

This method is not recommended in high-load solutions in reason named “race-condition”.

File uploading mechanism

Fixed uploading files. Removed BaseBot.send_file method. This allowed to send the thumb field.

Pipe for uploading files from URL

Known issue when Telegram can not accept sending file as URL. In this case need to download file locally and then
send.
In this case now you can send file from URL by using pipe. That means you download and send the file without saving
it.
You can open the pipe and use for uploading by calling types.InputFile.from_file(<URL>)
Example:

URL = 'https://docs.aiogram.dev/en/dev-2.x/_static/logo.png'

(continues on next page)

4.3. Migration FAQ (1.4 -> 2.0) 15

aiogram Documentation, Release 2.11.2

(continued from previous page)

@dp.message_handler(commands=['image, img'])
async def cmd_image(message: types.Message):
await bot.send_photo(message.chat.id, types.InputFile.from_url(URL))

I18n Middleware

You can internalize your bot by following next steps:

(Code snippets in this example related with examples/i18n_example.py)

First usage

1. Extract texts

pybabel extract i18n_example.py -o locales/mybot.pot

2. Create *.po files. For e.g. create en, ru, uk locales.

3. Translate texts
4. Compile translations

pybabel compile -d locales -D mybot

Updating translations

When you change the code of your bot you need to update po & mo files:
1. Regenerate pot file:

pybabel extract i18n_example.py -o locales/mybot.pot

2. Update po files

pybabel update -d locales -D mybot -i locales/mybot.pot

3. Update your translations

4. Compile mo files

pybabel compile -d locales -D mybot

Error handlers

Previously errors handlers had to have three arguments dispatcher, update and exception now dispatcher argument is
removed and will no longer be passed to the error handlers.

16 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Content types

Content types helper was divided to types.ContentType and types.ContentTypes.

In filters you can use types.ContentTypes but for comparing content types you must use types.ContentType class.

4.4 Telegram

4.4.1 Bot object

Low level API

Subclass of this class used only for splitting network interface from all of API methods.
class aiogram.bot.base.BaseBot(token: String, loop: Op-
tional[Union[asyncio.base_events.BaseEventLoop, asyn-
cio.events.AbstractEventLoop]] = None, connections_limit:
Optional[Integer] = None, proxy: Optional[String] = None,
proxy_auth: Optional[aiohttp.helpers.BasicAuth] = None,
validate_token: Optional[Boolean] = True, parse_mode: Op-
tional[String] = None, timeout: Optional[Union[Integer,
Float, aiohttp.client.ClientTimeout]] = None, server:
aiogram.bot.api.TelegramAPIServer = TelegramAPIS-
erver(base='https://api.telegram.org/bot{token}/{method}',
file='https://api.telegram.org/file/bot{token}/{path}'))
Bases: object
Base class for bot. It’s raw bot.
Instructions how to get Bot token is found here: https://core.telegram.org/bots#3-how-do-i-create-a-bot
Parameters
• token (str) – token from @BotFather
• loop (Optional Union asyncio.BaseEventLoop, asyncio.
AbstractEventLoop) – event loop
• connections_limit (int) – connections limit for aiohttp.ClientSession
• proxy (str) – HTTP proxy URL
• proxy_auth (Optional aiohttp.BasicAuth) – Authentication information
• validate_token (bool) – Validate token.
• parse_mode (str) – You can set default parse mode
• timeout (typing.Optional[typing.Union[base.Integer, base.
Float, aiohttp.ClientTimeout]]) – Request timeout
• server (TelegramAPIServer) – Telegram Bot API Server endpoint.
Raise when token is invalid throw an aiogram.utils.exceptions.ValidationError
request_timeout(timeout: Union[Integer, Float, aiohttp.client.ClientTimeout])
Context manager implements opportunity to change request timeout in current context
Parameters timeout (typing.Optional[typing.Union[base.Integer,
base.Float, aiohttp.ClientTimeout]]) – Request timeout

4.4. Telegram 17
aiogram Documentation, Release 2.11.2

Returns
close()
Close all client sessions
async request(method: String, data: Optional[Dict] = None, files: Optional[Dict] = None,
**kwargs) → Union[List, Dict, Boolean]
Make an request to Telegram Bot API
https://core.telegram.org/bots/api#making-requests
Parameters
• method (str) – API method
• data (dict) – request parameters
• files (dict) – files
Returns result
Return type Union[List, Dict]
Raise aiogram.exceptions.TelegramApiError
async download_file(file_path: String, destination: Optional[InputFile] = None, timeout: Op-
tional[Integer] = <object object>, chunk_size: Optional[Integer] = 65536,
seek: Optional[Boolean] = True) → Union[_io.BytesIO, _io.FileIO]
Download file by file_path to destination
if You want to automatically create destination (io.BytesIO) use default value of destination and handle
result of this method.
Parameters
• file_path (str) – file path on telegram server (You can get it from aiogram.
types.File)
• destination – filename or instance of io.IOBase. For e. g. io.BytesIO
• timeout – Integer
• chunk_size – Integer
• seek – Boolean - go to start of file when downloading is finished.
Returns destination
async send_file(file_type, method, file, payload) → Union[Dict, Boolean]
Send file
https://core.telegram.org/bots/api#inputfile
Parameters
• file_type – field name
• method – API method
• file – String or io.IOBase
• payload – request payload
Returns response

18 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Telegram Bot

This class based on aiogram.bot.base.BaseBot

class aiogram.bot.bot.Bot(token: String, loop: Optional[Union[asyncio.base_events.BaseEventLoop,
asyncio.events.AbstractEventLoop]] = None, connections_limit: Op-
tional[Integer] = None, proxy: Optional[String] = None, proxy_auth:
Optional[aiohttp.helpers.BasicAuth] = None, validate_token: Op-
tional[Boolean] = True, parse_mode: Optional[String] = None,
timeout: Optional[Union[Integer, Float, aiohttp.client.ClientTimeout]]
= None, server: aiogram.bot.api.TelegramAPIServer = Tele-
gramAPIServer(base='https://api.telegram.org/bot{token}/{method}',
file='https://api.telegram.org/file/bot{token}/{path}'))
Bases: aiogram.bot.base.BaseBot, aiogram.utils.mixins.DataMixin, aiogram.
utils.mixins.ContextInstanceMixin
Base bot class
Instructions how to get Bot token is found here: https://core.telegram.org/bots#3-how-do-i-create-a-bot
Parameters
• token (str) – token from @BotFather
• loop (Optional Union asyncio.BaseEventLoop, asyncio.
AbstractEventLoop) – event loop
• connections_limit (int) – connections limit for aiohttp.ClientSession
• proxy (str) – HTTP proxy URL
• proxy_auth (Optional aiohttp.BasicAuth) – Authentication information
• validate_token (bool) – Validate token.
• parse_mode (str) – You can set default parse mode
• timeout (typing.Optional[typing.Union[base.Integer, base.
Float, aiohttp.ClientTimeout]]) – Request timeout
• server (TelegramAPIServer) – Telegram Bot API Server endpoint.
Raise when token is invalid throw an aiogram.utils.exceptions.ValidationError
property me
Alias for self.get_me() but lazy and with caching.
Returns aiogram.types.User
async download_file_by_id(file_id: String, destination=None, timeout: Integer = 30,
chunk_size: Integer = 65536, seek: Boolean = True)
Download file by file_id to destination
if You want to automatically create destination (io.BytesIO) use default value of destination and handle
result of this method.
Parameters
• file_id – str
• destination – filename or instance of io.IOBase. For e. g. io.BytesIO
• timeout – int
• chunk_size – int

4.4. Telegram 19
aiogram Documentation, Release 2.11.2

• seek – bool - go to start of file when downloading is finished

Returns destination
async get_updates(offset: Optional[Integer] = None, limit: Optional[Integer] = None, timeout:
Optional[Integer] = None, allowed_updates: Optional[List[String]] = None)
→ List[aiogram.types.update.Update]
Use this method to receive incoming updates using long polling (wiki).
Notes 1. This method will not work if an outgoing webhook is set up. 2. In order to avoid getting duplicate
updates, recalculate offset after each server response.
Source: https://core.telegram.org/bots/api#getupdates
Parameters
• offset (typing.Optional[base.Integer]) – Identifier of the first update to be
returned
• limit (typing.Optional[base.Integer]) – Limits the number of updates to
be retrieved
• timeout (typing.Optional[base.Integer]) – Timeout in seconds for long
polling
• allowed_updates (typing.Union[typing.List[base.String],
None]) – List the types of updates you want your bot to receive
Returns An Array of Update objects is returned
Return type typing.List[types.Update]
async set_webhook(url: String, certificate: Optional[InputFile] = None, ip_address: Op-
tional[String] = None, max_connections: Optional[Integer] = None, al-
lowed_updates: Optional[List[String]] = None, drop_pending_updates: Op-
tional[Boolean] = None) → Boolean
Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever
there is an update for the bot, we will send an HTTPS POST request to the specified url, containing a
JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of
attempts. Returns True on success.
If you’d like to make sure that the Webhook request comes from Telegram, we recommend using a secret
path in the URL, e.g. https://www.example.com/<token>. Since nobody else knows your bot’s token, you
can be pretty sure it’s us.
Source: https://core.telegram.org/bots/api#setwebhook
Parameters
• url (base.String) – HTTPS url to send updates to. Use an empty string to remove
webhook integration
• certificate (typing.Optional[base.InputFile]) – Upload your public
key certificate so that the root certificate in use can be checked. See our self-signed guide
for details: https://core.telegram.org/bots/self-signed
• ip_address (typing.Optional[base.String]) – The fixed IP address which
will be used to send webhook requests instead of the IP address resolved through DNS
• max_connections (typing.Optional[base.Integer]) – Maximum allowed
number of simultaneous HTTPS connections to the webhook for update delivery, 1-100.
Defaults to 40. Use lower values to limit the load on your bot’s server, and higher values
to increase your bot’s throughput.

20 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• allowed_updates (typing.Optional[typing.List[base.String]]) –
A list of the update types you want your bot to receive. For example, specify [“mes-
sage”, “edited_channel_post”, “callback_query”] to only receive updates of these types.
See Update for a complete list of available update types. Specify an empty list to re-
ceive all updates regardless of type (default). If not specified, the previous setting will be
used. Please note that this parameter doesn’t affect updates created before the call to the
setWebhook, so unwanted updates may be received for a short period of time.
• drop_pending_updates (typing.Optional[base.Boolean]) – Pass True
to drop all pending updates
Returns Returns true
Return type base.Boolean
async delete_webhook(drop_pending_updates: Optional[Boolean] = None) → Boolean
Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True
on success.
Source: https://core.telegram.org/bots/api#deletewebhook
Parameters drop_pending_updates (typing.Optional[base.Boolean]) – Pass
True to drop all pending updates
Returns Returns True on success
Return type base.Boolean
async get_webhook_info() → aiogram.types.webhook_info.WebhookInfo
Use this method to get current webhook status. Requires no parameters.
If the bot is using getUpdates, will return an object with the url field empty.
Source: https://core.telegram.org/bots/api#getwebhookinfo
Returns On success, returns a WebhookInfo object
Return type types.WebhookInfo
async get_me() → aiogram.types.user.User
A simple method for testing your bot’s auth token. Requires no parameters.
Source: https://core.telegram.org/bots/api#getme
Returns Returns basic information about the bot in form of a User object
Return type types.User
async log_out() → Boolean
Use this method to log out from the cloud Bot API server before launching the bot locally. You must log
out the bot before running it locally, otherwise there is no guarantee that the bot will receive updates. After
a successful call, you will not be able to log in again using the same token for 10 minutes. Returns True
on success. Requires no parameters.
Source: https://core.telegram.org/bots/api#logout
Returns Returns True on success
Return type base.Boolean
close_bot() → Boolean
Use this method to close the bot instance before moving it from one local server to another. You need
to delete the webhook before calling this method to ensure that the bot isn’t launched again after server
restart. The method will return error 429 in the first 10 minutes after the bot is launched. Returns True on
success. Requires no parameters.

4.4. Telegram 21
aiogram Documentation, Release 2.11.2

Source: https://core.telegram.org/bots/api#close
Returns Returns True on success
Return type base.Boolean
async send_message(chat_id: Union[Integer, String], text: String,
parse_mode: Optional[String] = None, entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] =
None, disable_web_page_preview: Optional[Boolean] =
None, disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send text messages.
Source: https://core.telegram.org/bots/api#sendmessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• text (base.String) – Text of the message to be sent
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• entities (typing.Optional[typing.List[types.MessageEntity]]) –
List of special entities that appear in message text, which can be specified instead of
parse_mode
• disable_web_page_preview (typing.Optional[base.Boolean]) – Dis-
ables link previews for links in this message
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message

22 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

async forward_message(chat_id: Union[Integer, String], from_chat_id: Union[Integer, String],

message_id: Integer, disable_notification: Optional[Boolean] = None)
→ aiogram.types.message.Message
Use this method to forward messages of any kind.
Source: https://core.telegram.org/bots/api#forwardmessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• from_chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the chat where the original message was sent
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• message_id (base.Integer) – Message identifier in the chat specified in
from_chat_id
Returns On success, the sent Message is returned
Return type types.Message
async copy_message(chat_id: Union[Integer, String], from_chat_id: Union[Integer,
String], message_id: Integer, caption: Optional[String] =
None, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message_id.MessageId
Use this method to copy messages of any kind. The method is analogous to the method forwardMessages,
but the copied message doesn’t have a link to the original message. Returns the MessageId of the sent
message on success.
Source: https://core.telegram.org/bots/api#copymessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• from_chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the chat where the original message was sent (or channel username in the
format @channelusername)
• message_id (base.Integer) – Message identifier in the chat specified in
from_chat_id
• caption (typing.Optional[base.String]) – New caption for media, 0-1024
characters after entities parsing. If not specified, the original caption is kept
• parse_mode (typing.Optional[base.String]) – Mode for parsing entities in
the new caption. See formatting options for more details: https://core.telegram.org/bots/
api#formatting-options

4.4. Telegram 23
aiogram Documentation, Release 2.11.2

• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in the new caption,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user.
Returns On success, the sent Message is returned
Return type types.Message
async send_photo(chat_id: Union[Integer, String], photo: Union[InputFile, String], caption:
Optional[String] = None, parse_mode: Optional[String] = None, cap-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send photos.
Source: https://core.telegram.org/bots/api#sendphoto
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• photo (typing.Union[base.InputFile, base.String]) – Photo to send
• caption (typing.Optional[base.String]) – Photo caption (may also be used
when resending photos by file_id), 0-1024 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message

24 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_audio(chat_id: Union[Integer, String], audio: Union[InputFile, String], caption:
Optional[String] = None, parse_mode: Optional[String] = None, cap-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, duration: Optional[Integer] = None, performer: Op-
tional[String] = None, title: Optional[String] = None, thumb: Op-
tional[Union[InputFile, String]] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display them in the music player. Your
audio must be in the .mp3 format.
For sending voice messages, use the sendVoice method instead.
Source: https://core.telegram.org/bots/api#sendaudio
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• audio (typing.Union[base.InputFile, base.String]) – Audio file to
send
• caption (typing.Optional[base.String]) – Audio caption, 0-1024 charac-
ters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• duration (typing.Optional[base.Integer]) – Duration of the audio in sec-
onds
• performer (typing.Optional[base.String]) – Performer
• title (typing.Optional[base.String]) – Track name
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent

4.4. Telegram 25
aiogram Documentation, Release 2.11.2

• disable_notification (typing.Optional[base.Boolean]) – Sends the

message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_document(chat_id: Union[Integer, String], document: Union[InputFile,
String], thumb: Optional[Union[InputFile, String]] =
None, caption: Optional[String] = None, parse_mode:
Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] =
None, disable_content_type_detection: Optional[Boolean]
= None, disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send general files. On success, the sent Message is returned. Bots can currently send
files of any type of up to 50 MB in size, this limit may be changed in the future.
Source: https://core.telegram.org/bots/api#senddocument
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• document (typing.Union[base.InputFile, base.String]) – File to send
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent
• caption (typing.Optional[base.String]) – Document caption (may also be
used when resending documents by file_id), 0-1024 characters
• disable_content_type_detection (typing.Optional[base.
Boolean]) – Disables automatic server-side content type detection for files uploaded
using multipart/form-data
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.

26 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply], None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_video(chat_id: Union[Integer, String], video: Union[InputFile, String], duration:
Optional[Integer] = None, width: Optional[Integer] = None, height: Op-
tional[Integer] = None, thumb: Optional[Union[InputFile, String]] = None,
caption: Optional[String] = None, parse_mode: Optional[String] = None,
caption_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, supports_streaming: Optional[Boolean] = None, disable_notification:
Optional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as
Document).
Source: https://core.telegram.org/bots/api#sendvideo
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• video (typing.Union[base.InputFile, base.String]) – Video to send
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• width (typing.Optional[base.Integer]) – Video width
• height (typing.Optional[base.Integer]) – Video height
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent
• caption (typing.Optional[base.String]) – Video caption (may also be used
when resending videos by file_id), 0-1024 characters

4.4. Telegram 27
aiogram Documentation, Release 2.11.2

• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,

if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• supports_streaming (typing.Optional[base.Boolean]) – Pass True, if
the uploaded video is suitable for streaming
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_animation(chat_id: Union[Integer, String], animation: Union[InputFile,
String], duration: Optional[Integer] = None, width: Op-
tional[Integer] = None, height: Optional[Integer] = None, thumb:
Optional[Union[InputFile, String]] = None, caption: Optional[String]
= None, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound).
On success, the sent Message is returned. Bots can currently send animation files of up to 50 MB in size,
this limit may be changed in the future.
Source https://core.telegram.org/bots/api#sendanimation
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• animation (typing.Union[base.InputFile, base.String]) – Anima-
tion to send. Pass a file_id as String to send an animation that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get an animation
from the Internet, or upload a new animation using multipart/form-data

28 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• duration (typing.Optional[base.Integer]) – Duration of sent animation in

seconds
• width (typing.Optional[base.Integer]) – Animation width
• height (typing.Optional[base.Integer]) – Animation height
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• caption (typing.Optional[base.String]) – Animation caption (may also be
used when resending animation by file_id), 0-1024 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[typing.Union[types.
InlineKeyboardMarkup, types.ReplyKeyboardMarkup, types.
ReplyKeyboardRemove, types.ForceReply], None]) – Additional inter-
face options. A JSON-serialized object for an inline keyboard, custom reply keyboard,
instructions to remove reply keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_voice(chat_id: Union[Integer, String], voice: Union[InputFile, String], caption:
Optional[String] = None, parse_mode: Optional[String] = None, cap-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, duration: Optional[Integer] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice
message.
For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as
Audio or Document).
Source: https://core.telegram.org/bots/api#sendvoice

4.4. Telegram 29
aiogram Documentation, Release 2.11.2

Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• voice (typing.Union[base.InputFile, base.String]) – Audio file to
send
• caption (typing.Optional[base.String]) – Voice message caption, 0-1024
characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• duration (typing.Optional[base.Integer]) – Duration of the voice mes-
sage in seconds
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_video_note(chat_id: Union[Integer, String], video_note: Union[InputFile, String],
duration: Optional[Integer] = None, length: Optional[Integer] =
None, thumb: Optional[Union[InputFile, String]] = None, dis-
able_notification: Optional[Boolean] = None, reply_to_message_id:
Optional[Integer] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long. Use this method
to send video messages.
Source: https://core.telegram.org/bots/api#sendvideonote
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel

30 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• video_note (typing.Union[base.InputFile, base.String]) – Video

note to send
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• length (typing.Optional[base.Integer]) – Video width and height
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_media_group(chat_id: Union[Integer, String], media:
Union[aiogram.types.input_media.MediaGroup, List], dis-
able_notification: Optional[Boolean] = None, reply_to_message_id:
Optional[Integer] = None, allow_sending_without_reply: Op-
tional[Boolean] = None) → List[aiogram.types.message.Message]
Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio
files can be only group in an album with messages of the same type. On success, an array of Messages that
were sent is returned.
Source: https://core.telegram.org/bots/api#sendmediagroup
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• media (typing.Union[types.MediaGroup, typing.List]) – A JSON-
serialized array describing messages to be sent, must include 2-10 items
• disable_notification (typing.Optional[base.Boolean]) – Sends mes-
sages silently. Users will receive a notification with no sound.
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sages are a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
Returns On success, an array of the sent Messages is returned
Return type typing.List[types.Message]

4.4. Telegram 31
aiogram Documentation, Release 2.11.2

async send_location(chat_id: Union[Integer, String], latitude: Float, longitude: Float,

horizontal_accuracy: Optional[Float] = None, live_period: Op-
tional[Integer] = None, heading: Optional[Integer] = None, proxim-
ity_alert_radius: Optional[Integer] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send point on the map.
Source: https://core.telegram.org/bots/api#sendlocation
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• latitude (base.Float) – Latitude of the location
• longitude (base.Float) – Longitude of the location
• horizontal_accuracy (typing.Optional[base.Float]) – The radius of
uncertainty for the location, measured in meters; 0-1500
• live_period (typing.Optional[base.Integer]) – Period in seconds for
which the location will be updated
• heading (typing.Optional[base.Integer]) – For live locations, a direction
in which the user is moving, in degrees. Must be between 1 and 360 if specified.
• proximity_alert_radius (typing.Optional[base.Integer]) – For live
locations, a maximum distance for proximity alerts about approaching another chat mem-
ber, in meters. Must be between 1 and 100000 if specified.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message

32 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

async edit_message_live_location(latitude: Float, longitude: Float, chat_id:

Optional[Union[Integer, String]] = None,
message_id: Optional[Integer] = None, in-
line_message_id: Optional[String] = None, hori-
zontal_accuracy: Optional[Float] = None, heading:
Optional[Integer] = None, proximity_alert_radius:
Optional[Integer] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → aiogram.types.message.Message
Use this method to edit live location messages sent by the bot or via the bot (for inline bots). A location can
be edited until its live_period expires or editing is explicitly disabled by a call to stopMessageLiveLocation.
Source: https://core.telegram.org/bots/api#editmessagelivelocation
Parameters
• chat_id (typing.Union[base.Integer, base.String, None]) – Re-
quired if inline_message_id is not specified
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• latitude (base.Float) – Latitude of new location
• longitude (base.Float) – Longitude of new location
• horizontal_accuracy (typing.Optional[base.Float]) – The radius of
uncertainty for the location, measured in meters; 0-1500
• heading (typing.Optional[base.Integer]) – Direction in which the user is
moving, in degrees. Must be between 1 and 360 if specified.
• proximity_alert_radius (typing.Optional[base.Integer]) – For live
locations, a maximum distance for proximity alerts about approaching another chat mem-
ber, in meters. Must be between 1 and 100000 if specified.
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new inline keyboard
Returns On success, if the edited message was sent by the bot, the edited Message is returned,
otherwise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async stop_message_live_location(chat_id: Optional[Union[Integer, String]] = None, mes-
sage_id: Optional[Integer] = None, inline_message_id:
Optional[String] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → aiogram.types.message.Message
Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots)
before live_period expires.
Source: https://core.telegram.org/bots/api#stopmessagelivelocation
Parameters
• chat_id (typing.Union[base.Integer, base.String, None]) – Re-
quired if inline_message_id is not specified

4.4. Telegram 33
aiogram Documentation, Release 2.11.2

• message_id (typing.Optional[base.Integer]) – Required if in-

line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new inline keyboard
Returns On success, if the message was sent by the bot, the sent Message is returned, otherwise
True is returned.
Return type typing.Union[types.Message, base.Boolean]
async send_venue(chat_id: Union[Integer, String], latitude: Float, longitude: Float, title: String,
address: String, foursquare_id: Optional[String] = None, foursquare_type:
Optional[String] = None, google_place_id: Optional[String] = None,
google_place_type: Optional[String] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send information about a venue.
Source: https://core.telegram.org/bots/api#sendvenue
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• latitude (base.Float) – Latitude of the venue
• longitude (base.Float) – Longitude of the venue
• title (base.String) – Name of the venue
• address (base.String) – Address of the venue
• foursquare_id (typing.Optional[base.String]) – Foursquare identifier of
the venue
• foursquare_type (typing.Optional[base.String]) – Foursquare type of
the venue, if known
• google_place_id (typing.Optional[base.String]) – Google Places iden-
tifier of the venue
• google_place_type (typing.Optional[base.String]) – Google Places
type of the venue. See supported types: https://developers.google.com/places/
web-service/supported_types
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found

34 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_contact(chat_id: Union[Integer, String], phone_number: String, first_name:
String, last_name: Optional[String] = None, vcard: Op-
tional[String] = None, disable_notification: Optional[Boolean]
= None, reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send phone contacts.
Source: https://core.telegram.org/bots/api#sendcontact
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• phone_number (base.String) – Contact’s phone number
• first_name (base.String) – Contact’s first name
• last_name (typing.Optional[base.String]) – Contact’s last name
• vcard (typing.Optional[base.String]) – vcard
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message

4.4. Telegram 35
aiogram Documentation, Release 2.11.2

async send_poll(chat_id: Union[Integer, String], question: String, options: List[String],

is_anonymous: Optional[Boolean] = None, type: Optional[String]
= None, allows_multiple_answers: Optional[Boolean] = None, cor-
rect_option_id: Optional[Integer] = None, explanation: Optional[String]
= None, explanation_parse_mode: Optional[String] = None, explana-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, open_period: Optional[Integer] = None, close_date: Op-
tional[Union[Integer, datetime.datetime, datetime.timedelta]] = None,
is_closed: Optional[Boolean] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send a native poll. On success, the sent Message is returned.
Source: https://core.telegram.org/bots/api#sendpoll
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• question (base.String) – Poll question, 1-300 characters
• options (typing.List[base.String]) – A list of answer options, 2-10 strings
1-100 characters each
• is_anonymous (typing.Optional[base.Boolean]) – True, if the poll needs
to be anonymous, defaults to True
• type (typing.Optional[base.String]) – Poll type, “quiz” or “regular”, de-
faults to “regular”
• allows_multiple_answers (typing.Optional[base.Boolean]) – True,
if the poll allows multiple answers, ignored for polls in quiz mode, defaults to False
• correct_option_id (typing.Optional[base.Integer]) – 0-based identi-
fier of the correct answer option, required for polls in quiz mode
• explanation (typing.Optional[base.String]) – Text that is shown when
a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200
characters with at most 2 line feeds after entities parsing
• explanation_parse_mode (typing.Optional[base.String]) – Mode for
parsing entities in the explanation. See formatting options for more details.
• explanation_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which can be
specified instead of parse_mode
• open_period (typing.Optional[base.Integer]) – Amount of time in sec-
onds the poll will be active after creation, 5-600. Can’t be used together with close_date.
• close_date (typing.Union[base.Integer, datetime.datetime,
datetime.timedelta, None]) – Point in time (Unix timestamp) when the poll
will be automatically closed. Must be at least 5 and no more than 600 seconds in
the future. Can’t be used together with open_period.

36 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• is_closed (typing.Optional[base.Boolean]) – Pass True, if the poll needs

to be immediately closed
• disable_notification (typing.Optional[Boolean]) – Sends the message
silently. Users will receive a notification with no sound.
• reply_to_message_id (typing.Optional[Integer]) – If the message is a
reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async send_dice(chat_id: Union[Integer, String], disable_notification: Optional[Boolean] = None,
emoji: Optional[String] = None, reply_to_message_id: Optional[Integer] =
None, allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send an animated emoji that will display a random value. On success, the sent Message
is returned.
Source: https://core.telegram.org/bots/api#senddice
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• emoji (typing.Optional[base.String]) – Emoji on which the dice throw ani-
mation is based. Currently, must be one of “”, “”, “”, “”, or “”. Dice can have values 1-6
for “” and “”, values 1-5 for “” and “”, and values 1-64 for “”. Defaults to “”
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned

4.4. Telegram 37
aiogram Documentation, Release 2.11.2

Return type types.Message

async send_chat_action(chat_id: Union[Integer, String], action: String) → Boolean
Use this method when you need to tell the user that something is happening on the bot’s side. The status is
set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).
We only recommend using this method when a response from the bot will take a noticeable amount of time
to arrive.
Source: https://core.telegram.org/bots/api#sendchataction
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• action (base.String) – Type of action to broadcast
Returns Returns True on success
Return type base.Boolean
async get_user_profile_photos(user_id: Integer, offset: Optional[Integer] =
None, limit: Optional[Integer] = None) →
aiogram.types.user_profile_photos.UserProfilePhotos
Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object.
Source: https://core.telegram.org/bots/api#getuserprofilephotos
Parameters
• user_id (base.Integer) – Unique identifier of the target user
• offset (typing.Optional[base.Integer]) – Sequential number of the first
photo to be returned. By default, all photos are returned
• limit (typing.Optional[base.Integer]) – Limits the number of photos to be
retrieved. Values between 1—100 are accepted. Defaults to 100
Returns Returns a UserProfilePhotos object
Return type types.UserProfilePhotos
async get_file(file_id: String) → aiogram.types.file.File
Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can
download files of up to 20MB in size.
Note: This function may not preserve the original file name and MIME type. You should save the file’s
MIME type and name (if available) when the File object is received.
Source: https://core.telegram.org/bots/api#getfile
Parameters file_id (base.String) – File identifier to get info about
Returns On success, a File object is returned
Return type types.File
async kick_chat_member(chat_id: Union[Integer, String], user_id: Integer, until_date: Op-
tional[Union[Integer, datetime.datetime, datetime.timedelta]] = None)
→ Boolean
Use this method to kick a user from a group, a supergroup or a channel. In the case of supergroups
and channels, the user will not be able to return to the group on their own using invite links, etc., unless
unbanned first.
The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.

38 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group. Otherwise members may only be removed by the group’s creator or by
the member that added them.
Source: https://core.telegram.org/bots/api#kickchatmember
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target group or username of the target supergroup or channel
• user_id (base.Integer) – Unique identifier of the target user
• until_date (typing.Optional[base.Integer]) – Date when the user will be
unbanned, unix time
Returns Returns True on success
Return type base.Boolean
async unban_chat_member(chat_id: Union[Integer, String], user_id: Integer, only_if_banned:
Optional[Boolean] = None) → Boolean
Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to
the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator
for this to work. By default, this method guarantees that after the call the user is not a member of the chat,
but will be able to join it. So if the user is a member of the chat they will also be removed from the chat.
If you don’t want this, use the parameter only_if_banned. Returns True on success.
Source: https://core.telegram.org/bots/api#unbanchatmember
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target group or username of the target supergroup or channel (in the format
@username)
• user_id (base.Integer) – Unique identifier of the target user
• only_if_banned (typing.Optional[base.Boolean]) – Do nothing if the
user is not banned
Returns Returns True on success
Return type base.Boolean
async restrict_chat_member(chat_id: Union[Integer, String], user_id: Integer, permissions:
Optional[aiogram.types.chat_permissions.ChatPermissions] =
None, until_date: Optional[Union[Integer, datetime.datetime,
datetime.timedelta]] = None, can_send_messages: Op-
tional[Boolean] = None, can_send_media_messages: Op-
tional[Boolean] = None, can_send_other_messages: Op-
tional[Boolean] = None, can_add_web_page_previews: Op-
tional[Boolean] = None) → Boolean
Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup
for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift
restrictions from a user.
Source: https://core.telegram.org/bots/api#restrictchatmember
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target supergroup

4.4. Telegram 39
aiogram Documentation, Release 2.11.2

• user_id (base.Integer) – Unique identifier of the target user

• permissions (ChatPermissions) – New user permissions
• until_date (typing.Optional[base.Integer]) – Date when restrictions will
be lifted for the user, unix time
• can_send_messages (typing.Optional[base.Boolean]) – Pass True, if the
user can send text messages, contacts, locations and venues
• can_send_media_messages (typing.Optional[base.Boolean]) – Pass
True, if the user can send audios, documents, photos, videos, video notes and voice notes,
implies can_send_messages
• can_send_other_messages (typing.Optional[base.Boolean]) – Pass
True, if the user can send animations, games, stickers and use inline bots, implies
can_send_media_messages
• can_add_web_page_previews (typing.Optional[base.Boolean])
– Pass True, if the user may add web page previews to their messages, implies
can_send_media_messages
Returns Returns True on success
Return type base.Boolean
async promote_chat_member(chat_id: Union[Integer, String], user_id: Integer,
is_anonymous: Optional[Boolean] = None, can_change_info:
Optional[Boolean] = None, can_post_messages: Op-
tional[Boolean] = None, can_edit_messages: Op-
tional[Boolean] = None, can_delete_messages: Op-
tional[Boolean] = None, can_invite_users: Optional[Boolean]
= None, can_restrict_members: Optional[Boolean] =
None, can_pin_messages: Optional[Boolean] = None,
can_promote_members: Optional[Boolean] = None) → Boolean
Use this method to promote or demote a user in a supergroup or a channel. The bot must be an adminis-
trator in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean
parameters to demote a user.
Source: https://core.telegram.org/bots/api#promotechatmember
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• user_id (base.Integer) – Unique identifier of the target user
• is_anonymous (typing.Optional[base.Boolean]) – Pass True, if the admin-
istrator’s presence in the chat is hidden
• can_change_info (typing.Optional[base.Boolean]) – Pass True, if the
administrator can change chat title, photo and other settings
• can_post_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can create channel posts, channels only
• can_edit_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can edit messages of other users, channels only
• can_delete_messages (typing.Optional[base.Boolean]) – Pass True, if
the administrator can delete messages of other users

40 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• can_invite_users (typing.Optional[base.Boolean]) – Pass True, if the

administrator can invite new users to the chat
• can_restrict_members (typing.Optional[base.Boolean]) – Pass True,
if the administrator can restrict, ban or unban chat members
• can_pin_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can pin messages, supergroups only
• can_promote_members (typing.Optional[base.Boolean]) – Pass True, if
the administrator can add new administrators with a subset of his own privileges or demote
administrators that he has promoted, directly or indirectly (promoted by administrators that
were appointed by him)
Returns Returns True on success
Return type base.Boolean
async set_chat_administrator_custom_title(chat_id: Union[Integer, String], user_id:
Integer, custom_title: String) → Boolean
Use this method to set a custom title for an administrator in a supergroup promoted by the bot.
Returns True on success.
Source: https://core.telegram.org/bots/api#setchatadministratorcustomtitle
Parameters
• chat_id – Unique identifier for the target chat or username of the target supergroup
• user_id – Unique identifier of the target user
• custom_title – New custom title for the administrator; 0-16 characters, emoji are not
allowed
Returns True on success.
async set_chat_permissions(chat_id: Union[Integer, String], permissions:
aiogram.types.chat_permissions.ChatPermissions) → Boolean
Use this method to set default chat permissions for all members. The bot must be an administrator in the
group or a supergroup for this to work and must have the can_restrict_members admin rights.
Returns True on success.
Parameters
• chat_id – Unique identifier for the target chat or username of the target supergroup
• permissions – New default chat permissions
Returns True on success.
async export_chat_invite_link(chat_id: Union[Integer, String]) → String
Use this method to generate a new invite link for a chat; any previously generated link is revoked. The bot
must be an administrator in the chat for this to work and must have the appropriate admin rights.
Source: https://core.telegram.org/bots/api#exportchatinvitelink
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target channel
Returns Returns exported invite link as String on success
Return type base.String

4.4. Telegram 41
aiogram Documentation, Release 2.11.2

async set_chat_photo(chat_id: Union[Integer, String], photo: InputFile) → Boolean

Use this method to set a new profile photo for the chat. Photos can’t be changed for private chats. The bot
must be an administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#setchatphoto
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• photo (base.InputFile) – New chat photo, uploaded using multipart/form-data
Returns Returns True on success
Return type base.Boolean
async delete_chat_photo(chat_id: Union[Integer, String]) → Boolean
Use this method to delete a chat photo. Photos can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#deletechatphoto
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target channel
Returns Returns True on success
Return type base.Boolean
async set_chat_title(chat_id: Union[Integer, String], title: String) → Boolean
Use this method to change the title of a chat. Titles can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#setchattitle
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• title (base.String) – New chat title, 1-255 characters
Returns Returns True on success
Return type base.Boolean
async set_chat_description(chat_id: Union[Integer, String], description: Optional[String] =
None) → Boolean
Use this method to change the description of a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights.
Source: https://core.telegram.org/bots/api#setchatdescription
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel

42 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• description (typing.Optional[base.String]) – New chat description, 0-

255 characters
Returns Returns True on success
Return type base.Boolean
async pin_chat_message(chat_id: Union[Integer, String], message_id: Integer, dis-
able_notification: Optional[Boolean] = None) → Boolean
Use this method to add a message to the list of pinned messages in a chat. If the chat is not a private chat,
the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin
right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#pinchatmessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• message_id (base.Integer) – Identifier of a message to pin
• disable_notification (typing.Optional[base.Boolean]) – Pass True,
if it is not necessary to send a notification to all group members about the new pinned
message
Returns Returns True on success
Return type base.Boolean
async unpin_chat_message(chat_id: Union[Integer, String], message_id: Optional[Integer] =
None) → Boolean
Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private
chat, the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’
admin right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#unpinchatmessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel (in the format @channelusername)
• message_id (typing.Optional[base.Integer]) – Identifier of a message to
unpin. If not specified, the most recent pinned message (by sending date) will be unpinned.
Returns Returns True on success
Return type base.Boolean
async unpin_all_chat_messages(chat_id: Union[Integer, String]) → Boolean
Use this method to clear the list of pinned messages in a chat. If the chat is not a private chat, the bot must
be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in a
supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#unpinallchatmessages
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target channel (in the format @channeluser-
name)
Returns Returns True on success
Return type base.Boolean

4.4. Telegram 43
aiogram Documentation, Release 2.11.2

async leave_chat(chat_id: Union[Integer, String]) → Boolean

Use this method for your bot to leave a group, supergroup or channel.
Source: https://core.telegram.org/bots/api#leavechat
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target supergroup or channel
Returns Returns True on success
Return type base.Boolean
async get_chat(chat_id: Union[Integer, String]) → aiogram.types.chat.Chat
Use this method to get up to date information about the chat (current name of the user for one-on-one
conversations, current username of a user, group or channel, etc.).
Source: https://core.telegram.org/bots/api#getchat
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target supergroup or channel
Returns Returns a Chat object on success
Return type types.Chat
async get_chat_administrators(chat_id: Union[Integer, String]) →
List[aiogram.types.chat_member.ChatMember]
Use this method to get a list of administrators in a chat.
Source: https://core.telegram.org/bots/api#getchatadministrators
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target supergroup or channel
Returns On success, returns an Array of ChatMember objects that contains information about
all chat administrators except other bots. If the chat is a group or a supergroup and no
administrators were appointed, only the creator will be returned.
Return type typing.List[types.ChatMember]
async get_chat_members_count(chat_id: Union[Integer, String]) → Integer
Use this method to get the number of members in a chat.
Source: https://core.telegram.org/bots/api#getchatmemberscount
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target supergroup or channel
Returns Returns Int on success
Return type base.Integer
async get_chat_member(chat_id: Union[Integer, String], user_id: Integer) →
aiogram.types.chat_member.ChatMember
Use this method to get information about a member of a chat.
Source: https://core.telegram.org/bots/api#getchatmember
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target supergroup or channel
• user_id (base.Integer) – Unique identifier of the target user
Returns Returns a ChatMember object on success

44 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Return type types.ChatMember

async set_chat_sticker_set(chat_id: Union[Integer, String], sticker_set_name: String) →
Boolean
Use this method to set a new group sticker set for a supergroup. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this
method.
Source: https://core.telegram.org/bots/api#setchatstickerset
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target supergroup
• sticker_set_name (base.String) – Name of the sticker set to be set as the group
sticker set
Returns Returns True on success
Return type base.Boolean
async delete_chat_sticker_set(chat_id: Union[Integer, String]) → Boolean
Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this
method.
Source: https://core.telegram.org/bots/api#deletechatstickerset
Parameters chat_id (typing.Union[base.Integer, base.String]) – Unique
identifier for the target chat or username of the target supergroup
Returns Returns True on success
Return type base.Boolean
async answer_callback_query(callback_query_id: String, text: Optional[String] = None,
show_alert: Optional[Boolean] = None, url: Optional[String]
= None, cache_time: Optional[Integer] = None) → Boolean
Use this method to send answers to callback queries sent from inline keyboards. The answer will be
displayed to the user as a notification at the top of the chat screen or as an alert.
Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must
first create a game for your bot via @Botfather and accept the terms. Otherwise, you may use links like
t.me/your_bot?start=XXXX that open your bot with a parameter.
Source: https://core.telegram.org/bots/api#answercallbackquery
Parameters
• callback_query_id (base.String) – Unique identifier for the query to be an-
swered
• text (typing.Optional[base.String]) – Text of the notification. If not speci-
fied, nothing will be shown to the user, 0-1024 characters
• show_alert (typing.Optional[base.Boolean]) – If true, an alert will be
shown by the client instead of a notification at the top of the chat screen. Defaults to
false.

4.4. Telegram 45
aiogram Documentation, Release 2.11.2

• url (typing.Optional[base.String]) – URL that will be opened by the user’s

client
• cache_time (typing.Optional[base.Integer]) – The maximum amount of
time in seconds that the result of the callback query may be cached client-side.
Returns On success, True is returned
Return type base.Boolean
async set_my_commands(commands: List[aiogram.types.bot_command.BotCommand]) →
Boolean
Use this method to change the list of the bot’s commands.
Source: https://core.telegram.org/bots/api#setmycommands
Parameters commands – A JSON-serialized list of bot commands to be set as the list of the
bot’s commands. At most 100 commands can be specified.
Returns Returns True on success.
Return type base.Boolean
async get_my_commands() → List[aiogram.types.bot_command.BotCommand]
Use this method to get the current list of the bot’s commands.
Source: https://core.telegram.org/bots/api#getmycommands :return: Returns Array of BotCommand on
success. :rtype: typing.List[types.BotCommand]
async edit_message_text(text: String, chat_id: Optional[Union[Integer, String]] = None,
message_id: Optional[Integer] = None, inline_message_id: Op-
tional[String] = None, parse_mode: Optional[String] = None, en-
tities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_web_page_preview: Op-
tional[Boolean] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] =
None) → aiogram.types.message.Message
Use this method to edit text and game messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagetext
Parameters
• chat_id (typing.Union[base.Integer, base.String, None]) – Re-
quired if inline_message_id is not specified Unique identifier for the target chat or user-
name of the target channel
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• text (base.String) – New text of the message
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• entities (typing.Optional[typing.List[types.MessageEntity]]) –
List of special entities that appear in message text, which can be specified instead of
parse_mode

46 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• disable_web_page_preview (typing.Optional[base.Boolean]) – Dis-

ables link previews for links in this message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async edit_message_caption(chat_id: Optional[Union[Integer, String]] = None, mes-
sage_id: Optional[Integer] = None, inline_message_id:
Optional[String] = None, caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]]
= None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] =
None) → aiogram.types.message.Message
Use this method to edit captions of messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagecaption
Parameters
• chat_id (typing.Union[base.Integer, base.String, None]) – Re-
quired if inline_message_id is not specified Unique identifier for the target chat or user-
name of the target channel
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• caption (typing.Optional[base.String]) – New caption of the message
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.List[types.
MessageEntity]]) – List of special entities that appear in message text, which
can be specified instead of parse_mode
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async edit_message_media(media: aiogram.types.input_media.InputMedia, chat_id:
Optional[Union[Integer, String]] = None, mes-
sage_id: Optional[Integer] = None, inline_message_id:
Optional[String] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → Union[aiogram.types.message.Message, Boolean]
Use this method to edit audio, document, photo, or video messages. If a message is a part of a message
album, then it can be edited only to a photo or a video. Otherwise, message type can be changed arbitrarily.

4.4. Telegram 47
aiogram Documentation, Release 2.11.2

When inline message is edited, new file can’t be uploaded. Use previously uploaded file via its file_id or
specify a URL.
On success, if the edited message was sent by the bot, the edited Message is returned, otherwise True is
returned.
Source https://core.telegram.org/bots/api#editmessagemedia
Parameters
• chat_id (typing.Union[typing.Union[base.Integer, base.
String], None]) – Required if inline_message_id is not specified
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• media (types.InputMedia) – A JSON-serialized object for a new media content of
the message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new inline keyboard
Returns On success, if the edited message was sent by the bot, the edited Message is returned,
otherwise True is returned
Return type typing.Union[types.Message, base.Boolean]
async edit_message_reply_markup(chat_id: Optional[Union[Integer, String]] = None, mes-
sage_id: Optional[Integer] = None, inline_message_id:
Optional[String] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → aiogram.types.message.Message
Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagereplymarkup
Parameters
• chat_id (typing.Union[base.Integer, base.String, None]) – Re-
quired if inline_message_id is not specified Unique identifier for the target chat or user-
name of the target channel
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async stop_poll(chat_id: Union[String, Integer], message_id: Integer, reply_markup:
Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] = None) →
aiogram.types.poll.Poll
Use this method to stop a poll which was sent by the bot. On success, the stopped Poll with the final results
is returned.

48 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Parameters
• chat_id (typing.Union[base.String, base.Integer]) – Unique identi-
fier for the target chat or username of the target channel
• message_id (base.Integer) – Identifier of the original message with the poll
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new message inline keyboard.
Returns On success, the stopped Poll with the final results is returned.
Return type types.Poll
async delete_message(chat_id: Union[Integer, String], message_id: Integer) → Boolean
Use this method to delete a message, including service messages, with the following limitations: - A
message can only be deleted if it was sent less than 48 hours ago. - Bots can delete outgoing messages
in private chats, groups, and supergroups. - Bots can delete incoming messages in private chats. - Bots
granted can_post_messages permissions can delete outgoing messages in channels. - If the bot is an
administrator of a group, it can delete any message there. - If the bot has can_delete_messages permission
in a supergroup or a channel, it can delete any message there.
Source: https://core.telegram.org/bots/api#deletemessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• message_id (base.Integer) – Identifier of the message to delete
Returns Returns True on success
Return type base.Boolean
async send_sticker(chat_id: Union[Integer, String], sticker: Union[InputFile,
String], disable_notification: Optional[Boolean] = None,
reply_to_message_id: Optional[Integer] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None) →
aiogram.types.message.Message
Use this method to send .webp stickers.
Source: https://core.telegram.org/bots/api#sendsticker
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• sticker (typing.Union[base.InputFile, base.String]) – Sticker to
send
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message

4.4. Telegram 49
aiogram Documentation, Release 2.11.2

• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
Returns On success, the sent Message is returned
Return type types.Message
async get_sticker_set(name: String) → aiogram.types.sticker_set.StickerSet
Use this method to get a sticker set.
Source: https://core.telegram.org/bots/api#getstickerset
Parameters name (base.String) – Name of the sticker set
Returns On success, a StickerSet object is returned
Return type types.StickerSet
async upload_sticker_file(user_id: Integer, png_sticker: InputFile) →
aiogram.types.file.File
Use this method to upload a .png file with a sticker for later use in createNewStickerSet and addSticker-
ToSet methods (can be used multiple times).
Source: https://core.telegram.org/bots/api#uploadstickerfile
Parameters
• user_id (base.Integer) – User identifier of sticker file owner
• png_sticker (base.InputFile) – Png image with the sticker, must be up to 512
kilobytes in size, dimensions must not exceed 512px, and either width or height must be
exactly 512px.
Returns Returns the uploaded File on success
Return type types.File
async create_new_sticker_set(user_id: Integer, name: String, title: String, emo-
jis: String, png_sticker: Optional[Union[InputFile, String]]
= None, tgs_sticker: Optional[InputFile] = None, con-
tains_masks: Optional[Boolean] = None, mask_position: Op-
tional[aiogram.types.mask_position.MaskPosition] = None)
→ Boolean
Use this method to create a new sticker set owned by a user. The bot will be able to edit the sticker set thus
created. You must use exactly one of the fields png_sticker or tgs_sticker.
Source: https://core.telegram.org/bots/api#createnewstickerset
Parameters
• user_id (base.Integer) – User identifier of created sticker set owner
• name (base.String) – Short name of sticker set, to be used in t.me/addstickers/ URLs
(e.g., animals). Can contain only english letters, digits and underscores. Must begin with
a letter, can’t contain consecutive underscores and must end in “_by_<bot username>”.
<bot_username> is case insensitive. 1-64 characters.
• title (base.String) – Sticker set title, 1-64 characters

50 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• png_sticker (typing.Union[base.InputFile, base.String]) – PNG

image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed
512px, and either width or height must be exactly 512px. Pass a file_id as a String to
send a file that already exists on the Telegram servers, pass an HTTP URL as a String for
Telegram to get a file from the Internet, or upload a new one using multipart/form-data.
More info on https://core.telegram.org/bots/api#sending-files
• tgs_sticker (base.InputFile) – TGS animation with the sticker, up-
loaded using multipart/form-data. See https://core.telegram.org/animated_stickers#
technical-requirements for technical requirements
• emojis (base.String) – One or more emoji corresponding to the sticker
• contains_masks (typing.Optional[base.Boolean]) – Pass True, if a set of
mask stickers should be created
• mask_position (typing.Optional[types.MaskPosition]) – A JSON-
serialized object for position where the mask should be placed on faces
Returns Returns True on success
Return type base.Boolean
async add_sticker_to_set(user_id: Integer, name: String, emojis: String, png_sticker:
Optional[Union[InputFile, String]] = None, tgs_sticker:
Optional[InputFile] = None, mask_position: Op-
tional[aiogram.types.mask_position.MaskPosition] = None)
→ Boolean
Use this method to add a new sticker to a set created by the bot. You must use exactly one of the fields
png_sticker or tgs_sticker. Animated stickers can be added to animated sticker sets and only to them.
Animated sticker sets can have up to 50 stickers. Static sticker sets can have up to 120 stickers.
Source: https://core.telegram.org/bots/api#addstickertoset
Parameters
• user_id (base.Integer) – User identifier of sticker set owner
• name (base.String) – Sticker set name
• png_sticker (typing.Union[base.InputFile, base.String]) – PNG
image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed
512px, and either width or height must be exactly 512px. Pass a file_id as a String to
send a file that already exists on the Telegram servers, pass an HTTP URL as a String for
Telegram to get a file from the Internet, or upload a new one using multipart/form-data.
More info on https://core.telegram.org/bots/api#sending-files
• tgs_sticker (base.InputFile) – TGS animation with the sticker, up-
loaded using multipart/form-data. See https://core.telegram.org/animated_stickers#
technical-requirements for technical requirements
• emojis (base.String) – One or more emoji corresponding to the sticker
• mask_position (typing.Optional[types.MaskPosition]) – A JSON-
serialized object for position where the mask should be placed on faces
Returns Returns True on success
Return type base.Boolean
async set_sticker_position_in_set(sticker: String, position: Integer) → Boolean
Use this method to move a sticker in a set created by the bot to a specific position.
Source: https://core.telegram.org/bots/api#setstickerpositioninset

4.4. Telegram 51
aiogram Documentation, Release 2.11.2

Parameters
• sticker (base.String) – File identifier of the sticker
• position (base.Integer) – New sticker position in the set, zero-based
Returns Returns True on success
Return type base.Boolean
async delete_sticker_from_set(sticker: String) → Boolean
Use this method to delete a sticker from a set created by the bot.
Source: https://core.telegram.org/bots/api#deletestickerfromset
Parameters sticker (base.String) – File identifier of the sticker
Returns Returns True on success
Return type base.Boolean
async set_sticker_set_thumb(name: String, user_id: Integer, thumb: Op-
tional[Union[InputFile, String]] = None) → Boolean
Use this method to set the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker
sets only.
Source: https://core.telegram.org/bots/api#setstickersetthumb
Parameters
• name (base.String) – Sticker set name
• user_id (base.Integer) – User identifier of the sticker set owner
• thumb (typing.Union[base.InputFile, base.String]) – A PNG image
with the thumbnail, must be up to 128 kilobytes in size and have width and height ex-
actly 100px, or a TGS animation with the thumbnail up to 32 kilobytes in size; see
https://core.telegram.org/animated_stickers#technical-requirements for animated sticker
technical requirements. Pass a file_id as a String to send a file that already exists
on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file
from the Internet, or upload a new one using multipart/form-data. More info on https:
//core.telegram.org/bots/api#sending-files. Animated sticker set thumbnail can’t be up-
loaded via HTTP URL.
Returns Returns True on success
Return type base.Boolean
async answer_inline_query(inline_query_id: String, results:
List[aiogram.types.inline_query_result.InlineQueryResult],
cache_time: Optional[Integer] = None, is_personal: Op-
tional[Boolean] = None, next_offset: Optional[String] = None,
switch_pm_text: Optional[String] = None, switch_pm_parameter:
Optional[String] = None) → Boolean
Use this method to send answers to an inline query. No more than 50 results per query are allowed.
Source: https://core.telegram.org/bots/api#answerinlinequery
Parameters
• inline_query_id (base.String) – Unique identifier for the answered query
• results (typing.List[types.InlineQueryResult]) – A JSON-serialized
array of results for the inline query

52 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• cache_time (typing.Optional[base.Integer]) – The maximum amount of

time in seconds that the result of the inline query may be cached on the server. Defaults to
300.
• is_personal (typing.Optional[base.Boolean]) – Pass True, if results may
be cached on the server side only for the user that sent the query. By default, results may
be returned to any user who sends the same query
• next_offset (typing.Optional[base.String]) – Pass the offset that a client
should send in the next query with the same text to receive more results. Pass an empty
string if there are no more results or if you don‘t support pagination. Offset length can’t
exceed 64 bytes.
• switch_pm_text (typing.Optional[base.String]) – If passed, clients will
display a button with specified text that switches the user to a private chat with the bot and
sends the bot a start message with the parameter switch_pm_parameter
• switch_pm_parameter (typing.Optional[base.String]) – Deep-linking
parameter for the /start message sent to the bot when user presses the switch button. 1-64
characters, only A-Z, a-z, 0-9, _ and - are allowed.
Returns On success, True is returned
Return type base.Boolean
async send_invoice(chat_id: Integer, title: String, description: String, payload: String,
provider_token: String, start_parameter: String, currency: String,
prices: List[aiogram.types.labeled_price.LabeledPrice], provider_data:
Optional[Dict] = None, photo_url: Optional[String] = None,
photo_size: Optional[Integer] = None, photo_width: Optional[Integer]
= None, photo_height: Optional[Integer] = None, need_name: Op-
tional[Boolean] = None, need_phone_number: Optional[Boolean] =
None, need_email: Optional[Boolean] = None, need_shipping_address:
Optional[Boolean] = None, send_phone_number_to_provider: Op-
tional[Boolean] = None, send_email_to_provider: Optional[Boolean] =
None, is_flexible: Optional[Boolean] = None, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] = None)
→ aiogram.types.message.Message
Use this method to send invoices.
Source: https://core.telegram.org/bots/api#sendinvoice
Parameters
• chat_id (base.Integer) – Unique identifier for the target private chat
• title (base.String) – Product name, 1-32 characters
• description (base.String) – Product description, 1-255 characters
• payload (base.String) – Bot-defined invoice payload, 1-128 bytes This will not be
displayed to the user, use for your internal processes.
• provider_token (base.String) – Payments provider token, obtained via Botfa-
ther
• start_parameter (base.String) – Unique deep-linking parameter that can be
used to generate this invoice when used as a start parameter

4.4. Telegram 53
aiogram Documentation, Release 2.11.2

• currency (base.String) – Three-letter ISO 4217 currency code, see more on cur-
rencies
• prices (typing.List[types.LabeledPrice]) – Price breakdown, a list of
components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• provider_data (typing.Optional[typing.Dict]) – JSON-encoded data
about the invoice, which will be shared with the payment provider
• photo_url (typing.Optional[base.String]) – URL of the product photo for
the invoice
• photo_size (typing.Optional[base.Integer]) – Photo size
• photo_width (typing.Optional[base.Integer]) – Photo width
• photo_height (typing.Optional[base.Integer]) – Photo height
• need_name (typing.Optional[base.Boolean]) – Pass True, if you require the
user’s full name to complete the order
• need_phone_number (typing.Optional[base.Boolean]) – Pass True, if
you require the user’s phone number to complete the order
• need_email (typing.Optional[base.Boolean]) – Pass True, if you require
the user’s email to complete the order
• need_shipping_address (typing.Optional[base.Boolean]) – Pass True,
if you require the user’s shipping address to complete the order
• send_phone_number_to_provider (typing.Optional[base.Boolean])
– Pass True, if user’s phone number should be sent to provider
• send_email_to_provider (typing.Optional[base.Boolean]) – Pass
True, if user’s email address should be sent to provider
• is_flexible (typing.Optional[base.Boolean]) – Pass True, if the final
price depends on the shipping method
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard If empty, one ‘Pay total price’ button will
be shown. If not empty, the first button must be a Pay button.
Returns On success, the sent Message is returned
Return type types.Message
async answer_shipping_query(shipping_query_id: String, ok: Boolean, shipping_options: Op-
tional[List[aiogram.types.shipping_option.ShippingOption]] =
None, error_message: Optional[String] = None) → Boolean
If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot
API will send an Update with a shipping_query field to the bot.
Source: https://core.telegram.org/bots/api#answershippingquery

54 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Parameters
• shipping_query_id (base.String) – Unique identifier for the query to be an-
swered
• ok (base.Boolean) – Specify True if delivery to the specified address is possible and
False if there are any problems (for example, if delivery to the specified address is not
possible)
• shipping_options (typing.Union[typing.List[types.
ShippingOption], None]) – Required if ok is True. A JSON-serialized array of
available shipping options
• error_message (typing.Optional[base.String]) – Required if ok is False
Error message in human readable form that explains why it is impossible to complete the
order (e.g. “Sorry, delivery to your desired address is unavailable’). Telegram will display
this message to the user.
Returns On success, True is returned
Return type base.Boolean
async answer_pre_checkout_query(pre_checkout_query_id: String, ok: Boolean, er-
ror_message: Optional[String] = None) → Boolean
Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in
the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout
queries.
Source: https://core.telegram.org/bots/api#answerprecheckoutquery
Parameters
• pre_checkout_query_id (base.String) – Unique identifier for the query to be
answered
• ok (base.Boolean) – Specify True if everything is alright (goods are available, etc.)
and the bot is ready to proceed with the order. Use False if there are any problems.
• error_message (typing.Optional[base.String]) – Required if ok is False
Error message in human readable form that explains the reason for failure to proceed with
the checkout (e.g. “Sorry, somebody just bought the last of our amazing black T-shirts
while you were busy filling out your payment details. Please choose a different color or
garment!”). Telegram will display this message to the user.
Returns On success, True is returned
Return type base.Boolean
async set_passport_data_errors(user_id: Integer, errors:
List[aiogram.types.passport_element_error.PassportElementError])
→ Boolean
Informs a user that some of the Telegram Passport elements they provided contains errors. The user will
not be able to re-submit their Passport to you until the errors are fixed (the contents of the field for which
you returned the error must change). Returns True on success.
Use this if the data submitted by the user doesn’t satisfy the standards your service requires for any reason.
For example, if a birthday date seems invalid, a submitted document is blurry, a scan shows evidence of
tampering, etc. Supply some details in the error message to make sure the user knows how to correct the
issues.
Source https://core.telegram.org/bots/api#setpassportdataerrors
Parameters

4.4. Telegram 55
aiogram Documentation, Release 2.11.2

• user_id (base.Integer) – User identifier

• errors (typing.List[types.PassportElementError]) – A JSON-
serialized array describing the errors
Returns Returns True on success
Return type base.Boolean
async send_game(chat_id: Integer, game_short_name: String, disable_notification: Op-
tional[Boolean] = None, reply_to_message_id: Optional[Integer] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] = None) →
aiogram.types.message.Message
Use this method to send a game.
Source: https://core.telegram.org/bots/api#sendgame
Parameters
• chat_id (base.Integer) – Unique identifier for the target chat
• game_short_name (base.String) – Short name of the game, serves as the unique
identifier for the game. Set up your games via Botfather.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• reply_to_message_id (typing.Optional[base.Integer]) – If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard If empty, one ‘Play game_title’ button will
be shown. If not empty, the first button must launch the game.
Returns On success, the sent Message is returned
Return type types.Message
async set_game_score(user_id: Integer, score: Integer, force: Optional[Boolean]
= None, disable_edit_message: Optional[Boolean] = None,
chat_id: Optional[Integer] = None, message_id: Optional[Integer]
= None, inline_message_id: Optional[String] = None) →
aiogram.types.message.Message
Use this method to set the score of the specified user in a game.
Source: https://core.telegram.org/bots/api#setgamescore
Parameters
• user_id (base.Integer) – User identifier
• score (base.Integer) – New score, must be non-negative
• force (typing.Optional[base.Boolean]) – Pass True, if the high score is al-
lowed to decrease This can be useful when fixing mistakes or banning cheaters
• disable_edit_message (typing.Optional[base.Boolean]) – Pass True,
if the game message should not be automatically edited to include the current scoreboard

56 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• chat_id (typing.Optional[base.Integer]) – Required if inline_message_id

is not specified. Unique identifier for the target chat
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
Returns On success, if the message was sent by the bot, returns the edited Message, otherwise
returns True Returns an error, if the new score is not greater than the user’s current score in
the chat and force is False.
Return type typing.Union[types.Message, base.Boolean]
async get_game_high_scores(user_id: Integer, chat_id: Optional[Integer] =
None, message_id: Optional[Integer] = None, in-
line_message_id: Optional[String] = None) →
List[aiogram.types.game_high_score.GameHighScore]
Use this method to get data for high score tables.
This method will currently return scores for the target user, plus two of his closest neighbors on each side.
Will also return the top three users if the user and his neighbors are not among them. Please note that this
behavior is subject to change.
Source: https://core.telegram.org/bots/api#getgamehighscores
Parameters
• user_id (base.Integer) – Target user id
• chat_id (typing.Optional[base.Integer]) – Required if inline_message_id
is not specified. Unique identifier for the target chat
• message_id (typing.Optional[base.Integer]) – Required if in-
line_message_id is not specified. Identifier of the sent message
• inline_message_id (typing.Optional[base.String]) – Required if
chat_id and message_id are not specified. Identifier of the inline message
Returns Will return the score of the specified user and several of his neighbors in a game On
success, returns an Array of GameHighScore objects. This method will currently return
scores for the target user, plus two of his closest neighbors on each side. Will also return the
top three users if the user and his neighbors are not among them.
Return type typing.List[types.GameHighScore]

API Helpers

class aiogram.bot.api.TelegramAPIServer(base: str, file: str)

Bases: object
Base config for API Endpoints
api_url(token: str, method: str) → str
Generate URL for API methods
Parameters
• token – Bot token
• method – API method name (case insensitive)

4.4. Telegram 57
aiogram Documentation, Release 2.11.2

Returns URL
file_url(token: str, path: str) → str
Generate URL for downloading files
Parameters
• token – Bot token
• path – file path
Returns URL
aiogram.bot.api.check_token(token: str) → bool
Validate BOT token
Parameters token –
Returns
aiogram.bot.api.check_result(method_name: str, content_type: str, status_code: int, body: str)
Checks whether result is a valid API response. A result is considered invalid if: - The server returned an HTTP
response code other than 200 - The content of the result is invalid JSON. - The method call was unsuccessful
(The JSON ‘ok’ field equals False)
Parameters
• method_name – The name of the method called
• status_code – status code
• content_type – content type of result
• body – result body
Returns The result parsed to a JSON dictionary
Raises ApiException – if one of the above listed cases is applicable
aiogram.bot.api.guess_filename(obj)
Get file name from object
Parameters obj –
Returns
aiogram.bot.api.compose_data(params=None, files=None)
Prepare request data
Parameters
• params –
• files –
Returns
class aiogram.bot.api.Methods
Bases: aiogram.utils.helper.Helper
Helper for Telegram API Methods listed on https://core.telegram.org/bots/api
List is updated to Bot API 5.0

58 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

4.4.2 Telegram data types

Bases

Base TelegramObject

MetaTelegramObject

class aiogram.types.base.MetaTelegramObject(name: str, bases: Tuple[Type], namespace:

Dict[str, Any], **kwargs: Any)
Bases: type
Metaclass for telegram objects

TelegramObject

class aiogram.types.base.TelegramObject(conf: Optional[Dict[str, Any]] = None, **kwargs:

Any)
Bases: aiogram.utils.mixins.ContextInstanceMixin
Abstract class for telegram objects
Deserialize object
Parameters
• conf –
• kwargs –
property props
Get props
Returns dict with props
property props_aliases
Get aliases for props
Returns
property values
Get values
Returns
classmethod to_object(data: Dict[str, Any]) → T
Deserialize object
Parameters data –
Returns
to_python() → Dict[str, Any]
Get object as JSON serializable
Returns
clean() → None
Remove empty values
as_json() → str
Get object as JSON string

4.4. Telegram 59
aiogram Documentation, Release 2.11.2

Returns JSON
Return type str
iter_keys() → Generator[Any, None, None]
Iterate over keys
Returns
iter_values() → Generator[Any, None, None]
Iterate over values
Returns

Fields

BaseField

class aiogram.types.fields.BaseField(*, base=None, default=None, alias=None,

on_change=None)
Bases: object
Base field (prop)
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
get_value(instance)
Get value for the current object instance
Parameters instance –
Returns
set_value(instance, value, parent=None)
Set prop value
Parameters
• instance –
• value –
• parent –
Returns
abstract serialize(value)
Serialize value to python
Parameters value –
Returns

60 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

abstract deserialize(value, parent=None)

Deserialize python object value to TelegramObject value
export(instance)
Alias for serialize but for current Object instance
Parameters instance –
Returns

Field

class aiogram.types.fields.Field(*, base=None, default=None, alias=None,

on_change=None)
Bases: aiogram.types.fields.BaseField
Simple field
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
serialize(value)
Serialize value to python
Parameters value –
Returns
deserialize(value, parent=None)
Deserialize python object value to TelegramObject value

ListField

class aiogram.types.fields.ListField(*args, **kwargs)

Bases: aiogram.types.fields.Field
Field contains list ob objects
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
serialize(value)
Serialize value to python

4.4. Telegram 61
aiogram Documentation, Release 2.11.2

Parameters value –
Returns
deserialize(value, parent=None)
Deserialize python object value to TelegramObject value

ListOfLists

class aiogram.types.fields.ListOfLists(*, base=None, default=None, alias=None,

on_change=None)
Bases: aiogram.types.fields.Field
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
serialize(value)
Serialize value to python
Parameters value –
Returns
deserialize(value, parent=None)
Deserialize python object value to TelegramObject value

DateTimeField

class aiogram.types.fields.DateTimeField(*, base=None, default=None, alias=None,

on_change=None)
Bases: aiogram.types.fields.Field
In this field st_ored datetime
in: unixtime out: datetime
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
serialize(value: datetime.datetime)
Serialize value to python
Parameters value –

62 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Returns
deserialize(value, parent=None)
Deserialize python object value to TelegramObject value

TextField

class aiogram.types.fields.TextField(*, prefix=None, suffix=None, default=None,

alias=None)
Bases: aiogram.types.fields.Field
Init prop
Parameters
• base – class for child element
• default – default value
• alias – alias name (for e.g. field ‘from’ has to be named ‘from_user’ as ‘from’ is a builtin
Python keyword
• on_change – callback will be called when value is changed
serialize(value)
Serialize value to python
Parameters value –
Returns
deserialize(value, parent=None)
Deserialize python object value to TelegramObject value

Mixins

Downloadable

class aiogram.types.mixins.Downloadable
Bases: object
Mixin for files
async download(destination=None, timeout=30, chunk_size=65536, seek=True, make_dirs=True)
Download file
Parameters
• destination – filename or instance of io.IOBase. For e. g. io.BytesIO
• timeout – Integer
• chunk_size – Integer
• seek – Boolean - go to start of file when downloading is finished.
• make_dirs – Make dirs if not exist
Returns destination
async get_file()
Get file information

4.4. Telegram 63
aiogram Documentation, Release 2.11.2

Returns aiogram.types.File
async get_url()
Get file url.
Attention!! This method has security vulnerabilities for the reason that result contains bot’s access token
in open form. Use at your own risk!
Returns url

Types

StickerSet

class aiogram.types.sticker_set.StickerSet(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents a sticker set.
https://core.telegram.org/bots/api#stickerset
Deserialize object
Parameters
• conf –
• kwargs –

EncryptedCredentials

class aiogram.types.encrypted_credentials.EncryptedCredentials(conf: Op-

tional[Dict[str,
Any]] = None,
**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Contains data required for decrypting and authenticating EncryptedPassportElement. See the Telegram Passport
Documentation for a complete description of the data decryption and authentication processes.
https://core.telegram.org/bots/api#encryptedcredentials
Deserialize object
Parameters
• conf –
• kwargs –

64 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

CallbackQuery

class aiogram.types.callback_query.CallbackQuery(conf: Optional[Dict[str, Any]] =

None, **kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents an incoming callback query from a callback button in an inline keyboard.
If the button that originated the query was attached to a message sent by the bot, the field message will be
present.
If the button was attached to a message sent via the bot (in inline mode), the field inline_message_id will be
present.
Exactly one of the fields data or game_short_name will be present.
https://core.telegram.org/bots/api#callbackquery
Deserialize object
Parameters
• conf –
• kwargs –
async answer(text: Optional[String] = None, show_alert: Optional[Boolean] = None, url: Op-
tional[String] = None, cache_time: Optional[Integer] = None)
Use this method to send answers to callback queries sent from inline keyboards. The answer will be
displayed to the user as a notification at the top of the chat screen or as an alert.
Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must
first create a game for your bot via @Botfather and accept the terms. Otherwise, you may use links like
t.me/your_bot?start=XXXX that open your bot with a parameter.
Source: https://core.telegram.org/bots/api#answercallbackquery
Parameters
• text (typing.Optional[base.String]) – Text of the notification. If not speci-
fied, nothing will be shown to the user, 0-200 characters
• show_alert (typing.Optional[base.Boolean]) – If true, an alert will be
shown by the client instead of a notification at the top of the chat screen. Defaults to
false.
• url (typing.Optional[base.String]) – URL that will be opened by the user’s
client.
• cache_time (typing.Optional[base.Integer]) – The maximum amount of
time in seconds that the result of the callback query may be cached client-side.
Returns On success, True is returned.
Return type base.Boolean

4.4. Telegram 65
aiogram Documentation, Release 2.11.2

SuccessfulPayment

class aiogram.types.successful_payment.SuccessfulPayment(conf: Optional[Dict[str,

Any]] = None, **kwargs:
Any)
Bases: aiogram.types.base.TelegramObject
This object contains basic information about a successful payment.
https://core.telegram.org/bots/api#successfulpayment
Deserialize object
Parameters
• conf –
• kwargs –

MessageEntity

class aiogram.types.message_entity.MessageEntity(type: String, offset: Integer, length:

Integer, url: String = None, user:
aiogram.types.user.User = None, lan-
guage: String = None, **kwargs)
Bases: aiogram.types.base.TelegramObject
This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc.
https://core.telegram.org/bots/api#messageentity
Deserialize object
Parameters
• conf –
• kwargs –
get_text(text)
Get value of entity
Parameters text – full text
Returns part of text
parse(text, as_html=True)
Get entity value with markup
Parameters
• text – original text
• as_html – as html?
Returns entity text with markup

66 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

MessageEntityType

class aiogram.types.message_entity.MessageEntityType
Bases: aiogram.utils.helper.Helper
List of entity types
Key MENTION
Key HASHTAG
Key CASHTAG
Key BOT_COMMAND
Key URL
Key EMAIL
Key PHONE_NUMBER
Key BOLD
Key ITALIC
Key CODE
Key PRE
Key UNDERLINE
Key STRIKETHROUGH
Key TEXT_LINK
Key TEXT_MENTION

ShippingQuery

class aiogram.types.shipping_query.ShippingQuery(conf: Optional[Dict[str, Any]] =

None, **kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object contains information about an incoming shipping query.
https://core.telegram.org/bots/api#shippingquery
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 67
aiogram Documentation, Release 2.11.2

PassportData

class aiogram.types.passport_data.PassportData(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Contains information about Telegram Passport data shared with the bot by the user.
https://core.telegram.org/bots/api#passportdata
Deserialize object
Parameters
• conf –
• kwargs –

InlineKeyboardMarkup

class aiogram.types.inline_keyboard.InlineKeyboardMarkup(row_width=3, in-

line_keyboard=None,
**kwargs)
Bases: aiogram.types.base.TelegramObject
This object represents an inline keyboard that appears right next to the message it belongs to.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will display unsup-
ported message.
https://core.telegram.org/bots/api#inlinekeyboardmarkup
Deserialize object
Parameters
• conf –
• kwargs –
add(*args)
Add buttons
Parameters args –
Returns self
Return type types.InlineKeyboardMarkup
row(*args)
Add row
Parameters args –
Returns self
Return type types.InlineKeyboardMarkup
insert(button)
Insert button to last row
Parameters button –
Returns self

68 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Return type types.InlineKeyboardMarkup

InlineKeyboardButton

class aiogram.types.inline_keyboard.InlineKeyboardButton(text: String, url: String

= None, login_url:
aiogram.types.login_url.LoginUrl
= None, callback_data:
String = None,
switch_inline_query:
String = None,
switch_inline_query_current_chat:
String = None,
callback_game:
aiogram.types.callback_game.CallbackGame
= None, pay: Boolean =
None, **kwargs)
Bases: aiogram.types.base.TelegramObject
This object represents one button of an inline keyboard. You must use exactly one of the optional fields.
https://core.telegram.org/bots/api#inlinekeyboardbutton
Deserialize object
Parameters
• conf –
• kwargs –

User

class aiogram.types.user.User(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a Telegram user or bot.
https://core.telegram.org/bots/api#user
Deserialize object
Parameters
• conf –
• kwargs –
property full_name
You can get full name of user.
Returns str
property mention
You can get user’s username to mention him Full name will be returned if user has no username
Returns str
property locale
Get user’s locale

4.4. Telegram 69
aiogram Documentation, Release 2.11.2

Returns babel.core.Locale

Video

class aiogram.types.video.Video(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a video file.
https://core.telegram.org/bots/api#video
Deserialize object
Parameters
• conf –
• kwargs –

EncryptedPassportElement

class aiogram.types.encrypted_passport_element.EncryptedPassportElement(conf:
Op-
tional[Dict[str,
Any]]
=
None,
**kwargs:
Any)
Bases: aiogram.types.base.TelegramObject
Contains information about documents or other Telegram Passport elements shared with the bot by the user.
https://core.telegram.org/bots/api#encryptedpassportelement
Deserialize object
Parameters
• conf –
• kwargs –

Game

class aiogram.types.game.Game(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a game.
Use BotFather to create and edit games, their short names will act as unique identifiers.
https://core.telegram.org/bots/api#game
Deserialize object
Parameters
• conf –
• kwargs –

70 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

File

class aiogram.types.file.File(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a file ready to be downloaded.
The file can be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>.
It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested
by calling getFile.
Maximum file size to download is 20 MB
https://core.telegram.org/bots/api#file
Deserialize object
Parameters
• conf –
• kwargs –

LabeledPrice

class aiogram.types.labeled_price.LabeledPrice(label: String, amount: Integer)

Bases: aiogram.types.base.TelegramObject
This object represents a portion of the price for goods or services.
https://core.telegram.org/bots/api#labeledprice
Deserialize object
Parameters
• conf –
• kwargs –

CallbackGame

class aiogram.types.callback_game.CallbackGame(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
A placeholder, currently holds no information. Use BotFather to set up your game.
https://core.telegram.org/bots/api#callbackgame
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 71
aiogram Documentation, Release 2.11.2

ReplyKeyboardMarkup

class aiogram.types.reply_keyboard.ReplyKeyboardMarkup(keyboard: Op-

tional[List[List[aiogram.types.reply_keyboard.Keybo
= None, resize_keyboard:
Boolean = None,
one_time_keyboard:
Boolean = None, selec-
tive: Boolean = None,
row_width: Integer = 3)
Bases: aiogram.types.base.TelegramObject
This object represents a custom keyboard with reply options (see Introduction to bots for details and examples).
https://core.telegram.org/bots/api#replykeyboardmarkup
Deserialize object
Parameters
• conf –
• kwargs –
add(*args)
Add buttons
Parameters args –
Returns self
Return type types.ReplyKeyboardMarkup
row(*args)
Add row
Parameters args –
Returns self
Return type types.ReplyKeyboardMarkup
insert(button)
Insert button to last row
Parameters button –
Returns self
Return type types.ReplyKeyboardMarkup

KeyboardButton

class aiogram.types.reply_keyboard.KeyboardButton(text: String, request_contact:

Boolean = None, request_location:
Boolean = None, request_poll:
aiogram.types.reply_keyboard.KeyboardButtonPollType
= None, **kwargs)
Bases: aiogram.types.base.TelegramObject
This object represents one button of the reply keyboard. For simple text buttons String can be used instead of
this object to specify text of the button. Optional fields request_contact, request_location, and request_poll are

72 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

mutually exclusive. Note: request_contact and request_location options will only work in Telegram versions
released after 9 April, 2016. Older clients will ignore them. Note: request_poll option will only work in
Telegram versions released after 23 January, 2020. Older clients will receive unsupported message.
https://core.telegram.org/bots/api#keyboardbutton
Deserialize object
Parameters
• conf –
• kwargs –

ReplyKeyboardRemove

class aiogram.types.reply_keyboard.ReplyKeyboardRemove(selective: Boolean = None)

Bases: aiogram.types.base.TelegramObject
Upon receiving a message with this object, Telegram clients will remove the current custom keyboard and
display the default letter-keyboard. By default, custom keyboards are displayed until a new keyboard is sent by
a bot. An exception is made for one-time keyboards that are hidden immediately after the user presses a button
(see ReplyKeyboardMarkup).
https://core.telegram.org/bots/api#replykeyboardremove
Deserialize object
Parameters
• conf –
• kwargs –

Chat

class aiogram.types.chat.Chat(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a chat.
https://core.telegram.org/bots/api#chat
Deserialize object
Parameters
• conf –
• kwargs –
property mention
Get mention if a Chat has a username, or get full name if this is a Private Chat, otherwise None is returned
property shifted_id
Get shifted id of chat, e.g. for private links
For example: -1001122334455 -> 1122334455
async get_url() → String
Use this method to get chat link. Private chat returns user link. Other chat types return either username
link (if they are public) or invite link (if they are private). :return: link :rtype: base.String

4.4. Telegram 73
aiogram Documentation, Release 2.11.2

async update_chat()
User this method to update Chat data
Returns None
async set_photo(photo: aiogram.types.input_file.InputFile) → Boolean
Use this method to set a new profile photo for the chat. Photos can’t be changed for private chats. The bot
must be an administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#setchatphoto
Parameters photo (base.InputFile) – New chat photo, uploaded using multipart/form-
data
Returns Returns True on success.
Return type base.Boolean
async delete_photo() → Boolean
Use this method to delete a chat photo. Photos can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#deletechatphoto
Returns Returns True on success.
Return type base.Boolean
async set_title(title: String) → Boolean
Use this method to change the title of a chat. Titles can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group.
Source: https://core.telegram.org/bots/api#setchattitle
Parameters title (base.String) – New chat title, 1-255 characters
Returns Returns True on success.
Return type base.Boolean
async set_description(description: String) → Boolean
Use this method to change the description of a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights.
Source: https://core.telegram.org/bots/api#setchatdescription
Parameters description (typing.Optional[base.String]) – New chat descrip-
tion, 0-255 characters
Returns Returns True on success.
Return type base.Boolean
async kick(user_id: Integer, until_date: Optional[Union[Integer, datetime.datetime, date-
time.timedelta]] = None) → Boolean
Use this method to kick a user from a group, a supergroup or a channel. In the case of supergroups

74 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

and channels, the user will not be able to return to the group on their own using invite links, etc., unless
unbanned first.
The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’
setting is off in the target group. Otherwise members may only be removed by the group’s creator or by
the member that added them.
Source: https://core.telegram.org/bots/api#kickchatmember
Parameters
• user_id (base.Integer) – Unique identifier of the target user
• until_date (typing.Optional[base.Integer]) – Date when the user will be
unbanned, unix time.
Returns Returns True on success.
Return type base.Boolean
async unban(user_id: Integer, only_if_banned: Optional[Boolean] = None) → Boolean
Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to
the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator
for this to work. By default, this method guarantees that after the call the user is not a member of the chat,
but will be able to join it. So if the user is a member of the chat they will also be removed from the chat.
If you don’t want this, use the parameter only_if_banned. Returns True on success.
Source: https://core.telegram.org/bots/api#unbanchatmember
Parameters
• user_id (base.Integer) – Unique identifier of the target user
• only_if_banned (typing.Optional[base.Boolean]) – Do nothing if the
user is not banned
Returns Returns True on success.
Return type base.Boolean
async restrict(user_id: Integer, permissions: Optional[aiogram.types.chat_permissions.ChatPermissions]
= None, until_date: Optional[Union[Integer, datetime.datetime, date-
time.timedelta]] = None, can_send_messages: Optional[Boolean]
= None, can_send_media_messages: Optional[Boolean] =
None, can_send_other_messages: Optional[Boolean] = None,
can_add_web_page_previews: Optional[Boolean] = None) → Boolean
Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup
for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift
restrictions from a user.
Source: https://core.telegram.org/bots/api#restrictchatmember
Parameters
• user_id (base.Integer) – Unique identifier of the target user
• permissions (ChatPermissions) – New user permissions
• until_date (typing.Optional[base.Integer]) – Date when restrictions will
be lifted for the user, unix time.
• can_send_messages (typing.Optional[base.Boolean]) – Pass True, if the
user can send text messages, contacts, locations and venues

4.4. Telegram 75
aiogram Documentation, Release 2.11.2

• can_send_media_messages (typing.Optional[base.Boolean]) – Pass

True, if the user can send audios, documents, photos, videos, video notes and voice notes,
implies can_send_messages
• can_send_other_messages (typing.Optional[base.Boolean]) – Pass
True, if the user can send animations, games, stickers and use inline bots, implies
can_send_media_messages
• can_add_web_page_previews (typing.Optional[base.Boolean])
– Pass True, if the user may add web page previews to their messages, implies
can_send_media_messages
Returns Returns True on success.
Return type base.Boolean
async promote(user_id: Integer, is_anonymous: Optional[Boolean] = None, can_change_info:
Optional[Boolean] = None, can_post_messages: Optional[Boolean] = None,
can_edit_messages: Optional[Boolean] = None, can_delete_messages: Op-
tional[Boolean] = None, can_invite_users: Optional[Boolean] = None,
can_restrict_members: Optional[Boolean] = None, can_pin_messages: Op-
tional[Boolean] = None, can_promote_members: Optional[Boolean] = None) →
Boolean
Use this method to promote or demote a user in a supergroup or a channel. The bot must be an adminis-
trator in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean
parameters to demote a user.
Source: https://core.telegram.org/bots/api#promotechatmember
Parameters
• user_id (base.Integer) – Unique identifier of the target user
• is_anonymous (typing.Optional[base.Boolean]) – Pass True, if the admin-
istrator’s presence in the chat is hidden
• can_change_info (typing.Optional[base.Boolean]) – Pass True, if the
administrator can change chat title, photo and other settings
• can_post_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can create channel posts, channels only
• can_edit_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can edit messages of other users, channels only
• can_delete_messages (typing.Optional[base.Boolean]) – Pass True, if
the administrator can delete messages of other users
• can_invite_users (typing.Optional[base.Boolean]) – Pass True, if the
administrator can invite new users to the chat
• can_restrict_members (typing.Optional[base.Boolean]) – Pass True,
if the administrator can restrict, ban or unban chat members
• can_pin_messages (typing.Optional[base.Boolean]) – Pass True, if the
administrator can pin messages, supergroups only
• can_promote_members (typing.Optional[base.Boolean]) – Pass True, if
the administrator can add new administrators with a subset of his own privileges or demote
administrators that he has promoted, directly or indirectly (promoted by administrators that
were appointed by him)
Returns Returns True on success.

76 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Return type base.Boolean

async set_permissions(permissions: aiogram.types.chat_permissions.ChatPermissions) →
Boolean
Use this method to set default chat permissions for all members. The bot must be an administrator in the
group or a supergroup for this to work and must have the can_restrict_members admin rights.
Returns True on success.
Parameters permissions – New default chat permissions
Returns True on success.
async set_administrator_custom_title(user_id: Integer, custom_title: String) →
Boolean
Use this method to set a custom title for an administrator in a supergroup promoted by the bot.
Returns True on success.
Source: https://core.telegram.org/bots/api#setchatadministratorcustomtitle
Parameters
• user_id – Unique identifier of the target user
• custom_title – New custom title for the administrator; 0-16 characters, emoji are not
allowed
Returns True on success.
async pin_message(message_id: Integer, disable_notification: Optional[Boolean] = False) →
Boolean
Use this method to add a message to the list of pinned messages in a chat. If the chat is not a private chat,
the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin
right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#pinchatmessage
Parameters
• message_id (base.Integer) – Identifier of a message to pin
• disable_notification (typing.Optional[base.Boolean]) – Pass True,
if it is not necessary to send a notification to all group members about the new pinned
message
Returns Returns True on success
Return type base.Boolean
async unpin_message(message_id: Optional[Integer] = None) → Boolean
Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private
chat, the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’
admin right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#unpinchatmessage
Parameters message_id (typing.Optional[base.Integer]) – Identifier of a mes-
sage to unpin. If not specified, the most recent pinned message (by sending date) will be
unpinned.
Returns Returns True on success
Return type base.Boolean

4.4. Telegram 77
aiogram Documentation, Release 2.11.2

async unpin_all_messages()
Use this method to clear the list of pinned messages in a chat. If the chat is not a private chat, the bot must
be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in a
supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#unpinallchatmessages
Returns Returns True on success
Return type base.Boolean
async leave() → Boolean
Use this method for your bot to leave a group, supergroup or channel.
Source: https://core.telegram.org/bots/api#leavechat
Returns Returns True on success.
Return type base.Boolean
async get_administrators() → List[aiogram.types.chat_member.ChatMember]
Use this method to get a list of administrators in a chat.
Source: https://core.telegram.org/bots/api#getchatadministrators
Returns On success, returns an Array of ChatMember objects that contains information about
all chat administrators except other bots. If the chat is a group or a supergroup and no
administrators were appointed, only the creator will be returned.
Return type typing.List[types.ChatMember]
async get_members_count() → Integer
Use this method to get the number of members in a chat.
Source: https://core.telegram.org/bots/api#getchatmemberscount
Returns Returns Int on success.
Return type base.Integer
async get_member(user_id: Integer) → aiogram.types.chat_member.ChatMember
Use this method to get information about a member of a chat.
Source: https://core.telegram.org/bots/api#getchatmember
Parameters user_id (base.Integer) – Unique identifier of the target user
Returns Returns a ChatMember object on success.
Return type types.ChatMember
async set_sticker_set(sticker_set_name: String) → Boolean
Use this method to set a new group sticker set for a supergroup. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this
method.
Source: https://core.telegram.org/bots/api#setchatstickerset
Parameters sticker_set_name (base.String) – Name of the sticker set to be set as the
group sticker set
Returns Returns True on success
Return type base.Boolean

78 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

async delete_sticker_set() → Boolean

Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the
chat for this to work and must have the appropriate admin rights.
Use the field can_set_sticker_set optionally returned in getChat requests to check if the bot can use this
method.
Source: https://core.telegram.org/bots/api#deletechatstickerset
Returns Returns True on success
Return type base.Boolean
async do(action: String) → Boolean
Use this method when you need to tell the user that something is happening on the bot’s side. The status is
set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).
We only recommend using this method when a response from the bot will take a noticeable amount of time
to arrive.
Source: https://core.telegram.org/bots/api#sendchataction
Parameters action (base.String) – Type of action to broadcast.
Returns Returns True on success.
Return type base.Boolean
async export_invite_link() → String
Use this method to export an invite link to a supergroup or a channel. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights.
Source: https://core.telegram.org/bots/api#exportchatinvitelink
Returns Returns exported invite link as String on success.
Return type base.String

ChatType

class aiogram.types.chat.ChatType
Bases: aiogram.utils.helper.Helper
List of chat types
Key PRIVATE
Key GROUP
Key SUPER_GROUP
Key SUPERGROUP
Key CHANNEL
classmethod is_private(obj) → bool
Check chat is private
Parameters obj –
Returns
classmethod is_group(obj) → bool
Check chat is group

4.4. Telegram 79
aiogram Documentation, Release 2.11.2

Parameters obj –
Returns
classmethod is_super_group(obj) → bool
Check chat is super-group
Parameters obj –
Returns
classmethod is_group_or_super_group(obj) → bool
Check chat is group or super-group
Parameters obj –
Returns
classmethod is_channel(obj) → bool
Check chat is channel
Parameters obj –
Returns

ChatActions

class aiogram.types.chat.ChatActions
Bases: aiogram.utils.helper.Helper
List of chat actions
Key TYPING
Key UPLOAD_PHOTO
Key RECORD_VIDEO
Key UPLOAD_VIDEO
Key RECORD_AUDIO
Key UPLOAD_AUDIO
Key UPLOAD_DOCUMENT
Key FIND_LOCATION
Key RECORD_VIDEO_NOTE
Key UPLOAD_VIDEO_NOTE
classmethod calc_timeout(text, timeout=0.8)
Calculate timeout for text
Parameters
• text –
• timeout –
Returns
async classmethod typing(sleep=None)
Do typing
Parameters sleep – sleep timeout

80 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

Returns
async classmethod upload_photo(sleep=None)
Do upload_photo
Parameters sleep – sleep timeout
Returns
async classmethod record_video(sleep=None)
Do record video
Parameters sleep – sleep timeout
Returns
async classmethod upload_video(sleep=None)
Do upload video
Parameters sleep – sleep timeout
Returns
async classmethod record_audio(sleep=None)
Do record audio
Parameters sleep – sleep timeout
Returns
async classmethod upload_audio(sleep=None)
Do upload audio
Parameters sleep – sleep timeout
Returns
async classmethod upload_document(sleep=None)
Do upload document
Parameters sleep – sleep timeout
Returns
async classmethod find_location(sleep=None)
Do find location
Parameters sleep – sleep timeout
Returns
async classmethod record_video_note(sleep=None)
Do record video note
Parameters sleep – sleep timeout
Returns
async classmethod upload_video_note(sleep=None)
Do upload video note
Parameters sleep – sleep timeout
Returns

4.4. Telegram 81
aiogram Documentation, Release 2.11.2

Document

class aiogram.types.document.Document(conf: Optional[Dict[str, Any]] = None, **kwargs:

Any)
Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a general file (as opposed to photos, voice messages and audio files).
https://core.telegram.org/bots/api#document
Deserialize object
Parameters
• conf –
• kwargs –

Audio

class aiogram.types.audio.Audio(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents an audio file to be treated as music by the Telegram clients.
https://core.telegram.org/bots/api#audio
Deserialize object
Parameters
• conf –
• kwargs –

ForceReply

class aiogram.types.force_reply.ForceReply(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Upon receiving a message with this object, Telegram clients will display a reply interface to the user (act as if
the user has selected the bot‘s message and tapped ’Reply’). This can be extremely useful if you want to create
user-friendly step-by-step interfaces without having to sacrifice privacy mode.
Example: A poll bot for groups runs in privacy mode (only receives commands, replies to its messages and
mentions). There could be two ways to create a new poll
The last option is definitely more attractive. And if you use ForceReply in your bot‘s questions, it will receive
the user’s answers even if it only receives replies, commands and mentions — without any extra work for the
user.
https://core.telegram.org/bots/api#forcereply
Deserialize object
Parameters
• conf –
• kwargs –

82 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

classmethod create(selective: Optional[Boolean] = None)

Create new force reply
Parameters selective –
Returns

PassportElementError

class aiogram.types.passport_element_error.PassportElementError(conf: Op-

tional[Dict[str,
Any]] = None,
**kwargs:
Any)
Bases: aiogram.types.base.TelegramObject
This object represents an error in the Telegram Passport element which was submitted that should be resolved
by the user.
https://core.telegram.org/bots/api#passportelementerror
Deserialize object
Parameters
• conf –
• kwargs –

PassportElementErrorDataField

class aiogram.types.passport_element_error.PassportElementErrorDataField(source:
String,
type:
String,
field_name:
String,
data_hash:
String,
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue in one of the data fields that was provided by the user. The error is considered resolved
when the field’s value changes.
https://core.telegram.org/bots/api#passportelementerrordatafield
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 83
aiogram Documentation, Release 2.11.2

PassportElementErrorFile

class aiogram.types.passport_element_error.PassportElementErrorFile(source:
String,
type:
String,
file_hash:
String,
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue with a document scan. The error is considered resolved when the file with the document
scan changes.
https://core.telegram.org/bots/api#passportelementerrorfile
Deserialize object
Parameters
• conf –
• kwargs –

PassportElementErrorFiles

class aiogram.types.passport_element_error.PassportElementErrorFiles(source:
String,
type:
String,
file_hashes:
List[String],
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue with a list of scans. The error is considered resolved when the list of files containing the
scans changes.
https://core.telegram.org/bots/api#passportelementerrorfiles
Deserialize object
Parameters
• conf –
• kwargs –

84 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

PassportElementErrorFrontSide

class aiogram.types.passport_element_error.PassportElementErrorFrontSide(source:
String,
type:
String,
file_hash:
String,
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue with the front side of a document. The error is considered resolved when the file with the
front side of the document changes.
https://core.telegram.org/bots/api#passportelementerrorfrontside
Deserialize object
Parameters
• conf –
• kwargs –

PassportElementErrorReverseSide

class aiogram.types.passport_element_error.PassportElementErrorReverseSide(source:
String,
type:
String,
file_hash:
String,
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue with the reverse side of a document. The error is considered resolved when the file with
reverse side of the document changes.
https://core.telegram.org/bots/api#passportelementerrorreverseside
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 85
aiogram Documentation, Release 2.11.2

PassportElementErrorSelfie

class aiogram.types.passport_element_error.PassportElementErrorSelfie(source:
String,
type:
String,
file_hash:
String,
mes-
sage:
String)
Bases: aiogram.types.passport_element_error.PassportElementError
Represents an issue with the selfie with a document. The error is considered resolved when the file with the
selfie changes.
https://core.telegram.org/bots/api#passportelementerrorselfie
Deserialize object
Parameters
• conf –
• kwargs –

ShippingAddress

class aiogram.types.shipping_address.ShippingAddress(conf: Optional[Dict[str, Any]]

= None, **kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents a shipping address.
https://core.telegram.org/bots/api#shippingaddress
Deserialize object
Parameters
• conf –
• kwargs –

ResponseParameters

class aiogram.types.response_parameters.ResponseParameters(conf: Op-

tional[Dict[str, Any]]
= None, **kwargs:
Any)
Bases: aiogram.types.base.TelegramObject
Contains information about why a request was unsuccessful.
https://core.telegram.org/bots/api#responseparameters
Deserialize object
Parameters
• conf –

86 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• kwargs –

OrderInfo

class aiogram.types.order_info.OrderInfo(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents information about an order.
https://core.telegram.org/bots/api#orderinfo
Deserialize object
Parameters
• conf –
• kwargs –

GameHighScore

class aiogram.types.game_high_score.GameHighScore(conf: Optional[Dict[str, Any]] =

None, **kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents one row of the high scores table for a game. And that‘s about all we’ve got for now. If
you’ve got any questions, please check out our Bot FAQ
https://core.telegram.org/bots/api#gamehighscore
Deserialize object
Parameters
• conf –
• kwargs –

Sticker

class aiogram.types.sticker.Sticker(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a sticker.
https://core.telegram.org/bots/api#sticker
Deserialize object
Parameters
• conf –
• kwargs –
async set_position_in_set(position: Integer) → Boolean
Use this method to move a sticker in a set created by the bot to a specific position.
Source: https://core.telegram.org/bots/api#setstickerpositioninset
Parameters position (base.Integer) – New sticker position in the set, zero-based

4.4. Telegram 87
aiogram Documentation, Release 2.11.2

Returns Returns True on success

Return type base.Boolean
async delete_from_set() → Boolean
Use this method to delete a sticker from a set created by the bot.
Source: https://core.telegram.org/bots/api#deletestickerfromset
Parameters sticker (base.String) – File identifier of the sticker
Returns Returns True on success
Return type base.Boolean

InlineQuery

class aiogram.types.inline_query.InlineQuery(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents an incoming inline query.
When the user sends an empty query, your bot could return some default or trending results.
https://core.telegram.org/bots/api#inlinequery
Deserialize object
Parameters
• conf –
• kwargs –
async answer(results: List[aiogram.types.inline_query_result.InlineQueryResult], cache_time: Op-
tional[Integer] = None, is_personal: Optional[Boolean] = None, next_offset:
Optional[String] = None, switch_pm_text: Optional[String] = None,
switch_pm_parameter: Optional[String] = None)
Use this method to send answers to an inline query. No more than 50 results per query are allowed.
Source: https://core.telegram.org/bots/api#answerinlinequery
Parameters
• results (typing.List[types.InlineQueryResult]) – A JSON-serialized
array of results for the inline query
• cache_time (typing.Optional[base.Integer]) – The maximum amount of
time in seconds that the result of the inline query may be cached on the server. Defaults to
300.
• is_personal (typing.Optional[base.Boolean]) – Pass True, if results may
be cached on the server side only for the user that sent the query. By default, results may
be returned to any user who sends the same query
• next_offset (typing.Optional[base.String]) – Pass the offset that a client
should send in the next query with the same text to receive more results. Pass an empty
string if there are no more results or if you don‘t support pagination. Offset length can’t
exceed 64 bytes.
• switch_pm_text (typing.Optional[base.String]) – If passed, clients will
display a button with specified text that switches the user to a private chat with the bot and
sends the bot a start message with the parameter switch_pm_parameter

88 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• switch_pm_parameter (typing.Optional[base.String]) – Deep-linking

parameter for the /start message sent to the bot when user presses the switch button. 1-64
characters, only A-Z, a-z, 0-9, _ and - are allowed.
Returns On success, True is returned
Return type base.Boolean

Location

class aiogram.types.location.Location(conf: Optional[Dict[str, Any]] = None, **kwargs:

Any)
Bases: aiogram.types.base.TelegramObject
This object represents a point on the map.
https://core.telegram.org/bots/api#location
Deserialize object
Parameters
• conf –
• kwargs –

Animation

class aiogram.types.animation.Animation(conf: Optional[Dict[str, Any]] = None, **kwargs:

Any)
Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
You can provide an animation for your game so that it looks stylish in chats (check out Lumberjack for an
example). This object represents an animation file to be displayed in the message containing a game.
https://core.telegram.org/bots/api#animation
Deserialize object
Parameters
• conf –
• kwargs –

InputMedia

class aiogram.types.input_media.InputMedia(*args, **kwargs)

Bases: aiogram.types.base.TelegramObject
This object represents the content of a media message to be sent. It should be one of
• InputMediaAnimation
• InputMediaDocument
• InputMediaAudio
• InputMediaPhoto
• InputMediaVideo

4.4. Telegram 89
aiogram Documentation, Release 2.11.2

That is only base class.

https://core.telegram.org/bots/api#inputmedia
Deserialize object
Parameters
• conf –
• kwargs –

InputMediaAnimation

class aiogram.types.input_media.InputMediaAnimation(media: InputFile, thumb:

Union[InputFile, String] =
None, caption: String = None,
width: Integer = None, height:
Integer = None, duration: Inte-
ger = None, parse_mode: String
= None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]
= None, **kwargs)
Bases: aiogram.types.input_media.InputMedia
Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent.
https://core.telegram.org/bots/api#inputmediaanimation
Deserialize object
Parameters
• conf –
• kwargs –

InputMediaDocument

class aiogram.types.input_media.InputMediaDocument(media: InputFile, thumb: Op-

tional[Union[InputFile, String]]
= None, caption: String =
None, parse_mode: String
= None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]]
= None, dis-
able_content_type_detection:
Optional[Boolean] = None,
**kwargs)
Bases: aiogram.types.input_media.InputMedia
Represents a general file to be sent.
https://core.telegram.org/bots/api#inputmediadocument
Deserialize object
Parameters
• conf –

90 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

• kwargs –

InputMediaAudio

class aiogram.types.input_media.InputMediaAudio(media: InputFile, thumb:

Union[InputFile, String] = None, cap-
tion: String = None, duration: Integer
= None, performer: String = None,
title: String = None, parse_mode:
String = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]]
= None, **kwargs)
Bases: aiogram.types.input_media.InputMedia
Represents an audio file to be treated as music to be sent.
https://core.telegram.org/bots/api#inputmediaaudio
Deserialize object
Parameters
• conf –
• kwargs –

InputMediaPhoto

class aiogram.types.input_media.InputMediaPhoto(media: InputFile, caption: String

= None, parse_mode: String
= None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]]
= None, **kwargs)
Bases: aiogram.types.input_media.InputMedia
Represents a photo to be sent.
https://core.telegram.org/bots/api#inputmediaphoto
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 91
aiogram Documentation, Release 2.11.2

InputMediaVideo

class aiogram.types.input_media.InputMediaVideo(media: InputFile, thumb:

Union[InputFile, String] = None,
caption: String = None, width: Integer
= None, height: Integer = None, du-
ration: Integer = None, parse_mode:
String = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]]
= None, supports_streaming: Boolean
= None, **kwargs)
Bases: aiogram.types.input_media.InputMedia
Represents a video to be sent.
https://core.telegram.org/bots/api#inputmediavideo
Deserialize object
Parameters
• conf –
• kwargs –

MediaGroup

class aiogram.types.input_media.MediaGroup(medias: Op-

tional[List[Union[aiogram.types.input_media.InputMedia,
Dict]]] = None)
Bases: aiogram.types.base.TelegramObject
Helper for sending media group
Deserialize object
Parameters
• conf –
• kwargs –
attach_many(*medias: Union[aiogram.types.input_media.InputMedia, Dict])
Attach list of media
Parameters medias –
attach(media: Union[aiogram.types.input_media.InputMedia, Dict])
Attach media
Parameters media –
attach_photo(photo: Union[aiogram.types.input_media.InputMediaPhoto, InputFile], caption:
String = None)
Attach photo
Parameters
• photo –
• caption –

92 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

attach_video(video: Union[aiogram.types.input_media.InputMediaVideo, InputFile], thumb:

Union[InputFile, String] = None, caption: String = None, width: Integer = None,
height: Integer = None, duration: Integer = None)
Attach video
Parameters
• video –
• caption –
• width –
• height –
• duration –
to_python() → List
Get object as JSON serializable
Returns

InlineQueryResult

class aiogram.types.inline_query_result.InlineQueryResult(**kwargs)
Bases: aiogram.types.base.TelegramObject
This object represents one result of an inline query.
Telegram clients currently support results of the following 20 types
https://core.telegram.org/bots/api#inlinequeryresult
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 93
aiogram Documentation, Release 2.11.2

InlineQueryResultArticle

class aiogram.types.inline_query_result.InlineQueryResultArticle(*, id:

String, title:
String, in-
put_message_content:
aiogram.types.input_message_content
re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.
= None,
url: Op-
tional[String]
= None,
hide_url:
Op-
tional[Boolean]
= None,
descrip-
tion: Op-
tional[String]
= None,
thumb_url:
Op-
tional[String]
= None,
thumb_width:
Op-
tional[Integer]
= None,
thumb_height:
Op-
tional[Integer]
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to an article or web page.
https://core.telegram.org/bots/api#inlinequeryresultarticle
Deserialize object
Parameters
• conf –
• kwargs –

94 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

InlineQueryResultPhoto

class aiogram.types.inline_query_result.InlineQueryResultPhoto(*, id: String,

photo_url:
String,
thumb_url:
String,
photo_width:
Op-
tional[Integer]
= None,
photo_height:
Op-
tional[Integer]
= None,
title: Op-
tional[String]
= None, de-
scription: Op-
tional[String]
= None, cap-
tion: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None, cap-
tion_entities:
Op-
tional[List[aiogram.types.message_entity
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.Inl
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_con
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a photo.
By default, this photo will be sent by the user with optional caption. Alternatively, you can use in-
put_message_content to send a message with the specified content instead of the photo.
https://core.telegram.org/bots/api#inlinequeryresultphoto
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 95
aiogram Documentation, Release 2.11.2

InlineQueryResultGif

class aiogram.types.inline_query_result.InlineQueryResultGif(*, id: String,

gif_url: String,
gif_width: Op-
tional[Integer] =
None, gif_height:
Optional[Integer]
= None,
gif_duration: Op-
tional[Integer] =
None, thumb_url:
Optional[String]
= None, title:
Optional[String]
= None, caption:
Optional[String] =
None, parse_mode:
Optional[String]
= None, re-
ply_markup: Op-
tional[aiogram.types.inline_keyboard.Inline
= None, cap-
tion_entities: Op-
tional[List[aiogram.types.message_entity.M
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_conten
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to an animated GIF file.
By default, this animated GIF file will be sent by the user with optional caption. Alternatively, you can use
input_message_content to send a message with the specified content instead of the animation.
https://core.telegram.org/bots/api#inlinequeryresultgif
Deserialize object
Parameters
• conf –
• kwargs –

96 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

InlineQueryResultMpeg4Gif

class aiogram.types.inline_query_result.InlineQueryResultMpeg4Gif(*, id:

String,
mpeg4_url:
String,
thumb_url:
String,
mpeg4_width:
Op-
tional[Integer]
= None,
mpeg4_height:
Op-
tional[Integer]
= None,
mpeg4_duration:
Op-
tional[Integer]
= None,
title: Op-
tional[String]
= None,
caption:
Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard
= None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.message_e
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a video animation (H.264/MPEG-4 AVC video without sound).
By default, this animated MPEG-4 file will be sent by the user with optional caption. Alternatively, you can use
input_message_content to send a message with the specified content instead of the animation.
https://core.telegram.org/bots/api#inlinequeryresultmpeg4gif
Deserialize object
Parameters

4.4. Telegram 97
aiogram Documentation, Release 2.11.2

• conf –
• kwargs –

InlineQueryResultVideo

class aiogram.types.inline_query_result.InlineQueryResultVideo(*, id: String,

video_url:
String,
mime_type:
String,
thumb_url:
String, ti-
tle: String,
caption: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None,
video_width:
Op-
tional[Integer]
= None,
video_height:
Op-
tional[Integer]
= None,
video_duration:
Op-
tional[Integer]
= None, de-
scription: Op-
tional[String]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.Inl
= None, cap-
tion_entities:
Op-
tional[List[aiogram.types.message_entity
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_con
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a page containing an embedded video player or a video file.
By default, this video file will be sent by the user with an optional caption. Alternatively, you can use in-
put_message_content to send a message with the specified content instead of the video.

98 Chapter 4. Contents
 aiogram Documentation, Release 2.11.2

If an InlineQueryResultVideo message contains an embedded video (e.g., YouTube), you must replace its con-
tent using input_message_content.
https://core.telegram.org/bots/api#inlinequeryresultvideo
Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultAudio

class aiogram.types.inline_query_result.InlineQueryResultAudio(*, id: String, au-

dio_url: String,
title: String,
caption: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None, per-
former: Op-
tional[String]
= None, au-
dio_duration:
Op-
tional[Integer]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.Inl
= None, cap-
tion_entities:
Op-
tional[List[aiogram.types.message_entity
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_con
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to an mp3 audio file. By default, this audio file will be sent by the user. Alternatively, you can
use input_message_content to send a message with the specified content instead of the audio.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultaudio
Deserialize object
Parameters
• conf –

4.4. Telegram 99
aiogram Documentation, Release 2.11.2

• kwargs –

InlineQueryResultVoice

class aiogram.types.inline_query_result.InlineQueryResultVoice(*, id: String,

voice_url:
String, ti-
tle: String,
caption: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None,
voice_duration:
Op-
tional[Integer]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.Inl
= None, cap-
tion_entities:
Op-
tional[List[aiogram.types.message_entity
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_con
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a voice recording in an .ogg container encoded with OPUS.
By default, this voice recording will be sent by the user. Alternatively, you can use input_message_content to
send a message with the specified content instead of the the voice message.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultvoice
Deserialize object
Parameters
• conf –
• kwargs –

100 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InlineQueryResultDocument

class aiogram.types.inline_query_result.InlineQueryResultDocument(*, id:

String, title:
String, cap-
tion: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.message_e
= None,
docu-
ment_url:
Op-
tional[String]
= None,
mime_type:
Op-
tional[String]
= None,
descrip-
tion: Op-
tional[String]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_
= None,
thumb_url:
Op-
tional[String]
= None,
thumb_width:
Op-
tional[Integer]
= None,
thumb_height:
Op-
tional[Integer]
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a file.
By default, this file will be sent by the user with an optional caption. Alternatively, you can use in-

4.4. Telegram 101

aiogram Documentation, Release 2.11.2

put_message_content to send a message with the specified content instead of the file. Currently, only .PDF
and .ZIP files can be sent using this method.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultdocument
Deserialize object
Parameters
• conf –
• kwargs –

102 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InlineQueryResultLocation

class aiogram.types.inline_query_result.InlineQueryResultLocation(*, id:

String, lati-
tude: Float,
longitude:
Float, title:
String,
horizon-
tal_accuracy:
Op-
tional[Float]
= None,
live_period:
Op-
tional[Integer]
= None,
head-
ing: Op-
tional[Integer]
= None,
proxim-
ity_alert_radius:
Op-
tional[Integer]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_
= None,
thumb_url:
Op-
tional[String]
= None,
thumb_width:
Op-
tional[Integer]
= None,
thumb_height:
Op-
tional[Integer]
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a location on a map.
By default, the location will be sent by the user. Alternatively, you can use input_message_content to send a
message with the specified content instead of the location.
https://core.telegram.org/bots/api#inlinequeryresultlocation
Deserialize object

4.4. Telegram 103

aiogram Documentation, Release 2.11.2

Parameters
• conf –
• kwargs –

InlineQueryResultVenue

class aiogram.types.inline_query_result.InlineQueryResultVenue(*, id: String,

latitude: Float,
longitude:
Float, title:
String, ad-
dress: String,
foursquare_id:
Op-
tional[String]
= None,
foursquare_type:
Op-
tional[String]
= None,
google_place_id:
Op-
tional[String]
= None,
google_place_type:
Op-
tional[String]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.Inl
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_con
= None,
thumb_url: Op-
tional[String]
= None,
thumb_width:
Op-
tional[Integer]
= None,
thumb_height:
Op-
tional[Integer]
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a venue. By default, the venue will be sent by the user.
Alternatively, you can use input_message_content to send a message with the specified content instead of the
venue.

104 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultvenue
Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultContact

class aiogram.types.inline_query_result.InlineQueryResultContact(*, id: String,

phone_number:
String,
first_name:
String,
last_name:
Op-
tional[String]
= None, re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboard.
= None, in-
put_message_content:
Op-
tional[aiogram.types.input_message_c
= None,
thumb_url:
Op-
tional[String]
= None,
thumb_width:
Op-
tional[Integer]
= None,
thumb_height:
Op-
tional[Integer]
= None,
foursquare_type:
Op-
tional[String]
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a contact with a phone number.
By default, this contact will be sent by the user. Alternatively, you can use input_message_content to send a
message with the specified content instead of the contact.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultcontact

4.4. Telegram 105

aiogram Documentation, Release 2.11.2

Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultGame

class aiogram.types.inline_query_result.InlineQueryResultGame(*, id: String,

game_short_name:
String, re-
ply_markup: Op-
tional[aiogram.types.inline_keyboard.Inlin
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a Game.
Note: This will only work in Telegram versions released after October 1, 2016. Older clients will not display
any inline results if a game result is among them.
https://core.telegram.org/bots/api#inlinequeryresultgame
Deserialize object
Parameters
• conf –
• kwargs –

106 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InlineQueryResultCachedPhoto

class aiogram.types.inline_query_result.InlineQueryResultCachedPhoto(*, id:

String,
photo_file_id:
String,
title:
Op-
tional[String]
=
None,
de-
scrip-
tion:
Op-
tional[String]
=
None,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.messa
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_key
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_mess
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a photo stored on the Telegram servers.
By default, this photo will be sent by the user with an optional caption. Alternatively, you can use in-
put_message_content to send a message with the specified content instead of the photo.
https://core.telegram.org/bots/api#inlinequeryresultcachedphoto

4.4. Telegram 107

aiogram Documentation, Release 2.11.2

Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultCachedGif

class aiogram.types.inline_query_result.InlineQueryResultCachedGif(*, id:

String,
gif_file_id:
String,
title: Op-
tional[String]
= None,
cap-
tion: Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.message_
= None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_keyboa
= None,
in-
put_message_content:
Op-
tional[aiogram.types.input_messag
= None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to an animated GIF file stored on the Telegram servers.
By default, this animated GIF file will be sent by the user with an optional caption. Alternatively, you can use
input_message_content to send a message with specified content instead of the animation.
https://core.telegram.org/bots/api#inlinequeryresultcachedgif
Deserialize object
Parameters
• conf –
• kwargs –

108 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InlineQueryResultCachedMpeg4Gif

class aiogram.types.inline_query_result.InlineQueryResultCachedMpeg4Gif(*,
id:
String,
mpeg4_file_id:
String,
ti-
tle:
Op-
tional[String]
=
None,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.m
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a video animation (H.264/MPEG-4 AVC video without sound) stored on the Telegram
servers.
By default, this animated MPEG-4 file will be sent by the user with an optional caption. Alternatively, you can
use input_message_content to send a message with the specified content instead of the animation.
https://core.telegram.org/bots/api#inlinequeryresultcachedmpeg4gif
Deserialize object
Parameters
• conf –

4.4. Telegram 109

aiogram Documentation, Release 2.11.2

• kwargs –

InlineQueryResultCachedSticker

class aiogram.types.inline_query_result.InlineQueryResultCachedSticker(*,
id:
String,
sticker_file_id:
String,
re-
ply_markup:
Op-
tional[aiogram.types.inline_k
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_m
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a sticker stored on the Telegram servers.
By default, this sticker will be sent by the user. Alternatively, you can use input_message_content to send a
message with the specified content instead of the sticker.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultcachedsticker
Deserialize object
Parameters
• conf –
• kwargs –

110 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InlineQueryResultCachedDocument

class aiogram.types.inline_query_result.InlineQueryResultCachedDocument(*,
id:
String,
ti-
tle:
String,
doc-
u-
ment_file_id:
String,
de-
scrip-
tion:
Op-
tional[String]
=
None,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.m
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a file stored on the Telegram servers. By default, this file will be sent by the user with an
optional caption. Alternatively, you can use input_message_content to send a message with the specified content
instead of the file.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.

4.4. Telegram 111

aiogram Documentation, Release 2.11.2

https://core.telegram.org/bots/api#inlinequeryresultcacheddocument
Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultCachedVideo

class aiogram.types.inline_query_result.InlineQueryResultCachedVideo(*, id:

String,
video_file_id:
String,
title:
String,
de-
scrip-
tion:
Op-
tional[String]
=
None,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.messa
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_key
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_mess
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult

112 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Represents a link to a video file stored on the Telegram servers.

By default, this video file will be sent by the user with an optional caption. Alternatively, you can use in-
put_message_content to send a message with the specified content instead of the video.
https://core.telegram.org/bots/api#inlinequeryresultcachedvideo
Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultCachedVoice

class aiogram.types.inline_query_result.InlineQueryResultCachedVoice(*, id:

String,
voice_file_id:
String,
title:
String,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.messa
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_key
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_mess
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to a voice message stored on the Telegram servers.

4.4. Telegram 113

aiogram Documentation, Release 2.11.2

By default, this voice message will be sent by the user. Alternatively, you can use input_message_content to
send a message with the specified content instead of the voice message.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultcachedvoice
Deserialize object
Parameters
• conf –
• kwargs –

InlineQueryResultCachedAudio

class aiogram.types.inline_query_result.InlineQueryResultCachedAudio(*, id:

String,
au-
dio_file_id:
String,
cap-
tion:
Op-
tional[String]
=
None,
parse_mode:
Op-
tional[String]
=
None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.messa
=
None,
re-
ply_markup:
Op-
tional[aiogram.types.inline_key
=
None,
in-
put_message_content:
Op-
tional[aiogram.types.input_mess
=
None)
Bases: aiogram.types.inline_query_result.InlineQueryResult
Represents a link to an mp3 audio file stored on the Telegram servers.
By default, this audio file will be sent by the user. Alternatively, you can use input_message_content to send a
message with the specified content instead of the audio.

114 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inlinequeryresultcachedaudio
Deserialize object
Parameters
• conf –
• kwargs –

InputFile

class aiogram.types.input_file.InputFile(path_or_bytesio: Union[str, io.IOBase, path-

lib.Path], filename=None, conf=None)
Bases: aiogram.types.base.TelegramObject
This object represents the contents of a file to be uploaded. Must be posted using multipart/form-data in the
usual way that files are uploaded via the browser.
Also that is not typical TelegramObject!
https://core.telegram.org/bots/api#inputfile
Parameters
• path_or_bytesio –
• filename –
• conf –
get_filename() → str
Get file name
Returns name
get_file()
Get file object
Returns
classmethod from_url(url, filename=None, chunk_size=65536)
Download file from URL
Manually is not required action. You can send urls instead!
Parameters
• url – target URL
• filename – optional. set custom file name
• chunk_size –
Returns InputFile
save(filename, chunk_size=65536)
Write file to disk
Parameters
• filename –
• chunk_size –

4.4. Telegram 115

aiogram Documentation, Release 2.11.2

to_python()
Get object as JSON serializable
Returns
classmethod to_object(data)
Deserialize object
Parameters data –
Returns

PreCheckoutQuery

class aiogram.types.pre_checkout_query.PreCheckoutQuery(conf: Optional[Dict[str,

Any]] = None, **kwargs:
Any)
Bases: aiogram.types.base.TelegramObject
This object contains information about an incoming pre-checkout query. Your bot can offer users HTML5 games
to play solo or to compete against each other in groups and one-on-one chats.
Create games via @BotFather using the /newgame command.
Please note that this kind of power requires responsibility: you will need to accept the terms for each game that
your bots will be offering.
https://core.telegram.org/bots/api#precheckoutquery
Deserialize object
Parameters
• conf –
• kwargs –

Voice

class aiogram.types.voice.Voice(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a voice note.
https://core.telegram.org/bots/api#voice
Deserialize object
Parameters
• conf –
• kwargs –

116 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InputMessageContent

class aiogram.types.input_message_content.InputMessageContent(conf: Op-

tional[Dict[str,
Any]] = None,
**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents the content of a message to be sent as a result of an inline query.
Telegram clients currently support the following 4 types
https://core.telegram.org/bots/api#inputmessagecontent
Deserialize object
Parameters
• conf –
• kwargs –

InputContactMessageContent

class aiogram.types.input_message_content.InputContactMessageContent(phone_number:
String,
first_name:
Op-
tional[String]
=
None,
last_name:
Op-
tional[String]
=
None)
Bases: aiogram.types.input_message_content.InputMessageContent
Represents the content of a contact message to be sent as the result of an inline query.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inputcontactmessagecontent
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 117

aiogram Documentation, Release 2.11.2

InputLocationMessageContent

class aiogram.types.input_message_content.InputLocationMessageContent(latitude:
Float,
longi-
tude:
Float,
hori-
zon-
tal_accuracy:
Op-
tional[Float]
=
None,
live_period:
Op-
tional[Integer]
=
None,
head-
ing:
Op-
tional[Integer]
=
None,
prox-
im-
ity_alert_radius:
Op-
tional[Integer]
=
None)
Bases: aiogram.types.input_message_content.InputMessageContent
Represents the content of a location message to be sent as the result of an inline query.
https://core.telegram.org/bots/api#inputlocationmessagecontent
Deserialize object
Parameters
• conf –
• kwargs –

118 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

InputTextMessageContent

class aiogram.types.input_message_content.InputTextMessageContent(message_text:
Op-
tional[String]
= None,
parse_mode:
Op-
tional[String]
= None,
cap-
tion_entities:
Op-
tional[List[aiogram.types.message_e
= None,
dis-
able_web_page_preview:
Op-
tional[Boolean]
= None)
Bases: aiogram.types.input_message_content.InputMessageContent
Represents the content of a text message to be sent as the result of an inline query.
https://core.telegram.org/bots/api#inputtextmessagecontent
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 119

aiogram Documentation, Release 2.11.2

InputVenueMessageContent

class aiogram.types.input_message_content.InputVenueMessageContent(latitude:
Op-
tional[Float]
= None,
longi-
tude: Op-
tional[Float]
= None,
title: Op-
tional[String]
= None,
address:
Op-
tional[String]
= None,
foursquare_id:
Op-
tional[String]
= None,
foursquare_type:
Op-
tional[String]
= None,
google_place_id:
Op-
tional[String]
= None,
google_place_type:
Op-
tional[String]
= None)
Bases: aiogram.types.input_message_content.InputMessageContent
Represents the content of a venue message to be sent as the result of an inline query.
Note: This will only work in Telegram versions released after 9 April, 2016. Older clients will ignore them.
https://core.telegram.org/bots/api#inputvenuemessagecontent
Deserialize object
Parameters
• conf –
• kwargs –

120 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Update

class aiogram.types.update.Update(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents an incoming update. At most one of the optional parameters can be present in any given
update.
https://core.telegram.org/bots/api#update
Deserialize object
Parameters
• conf –
• kwargs –

AllowedUpdates

class aiogram.types.update.AllowedUpdates
Bases: aiogram.utils.helper.Helper
Helper for allowed_updates parameter in getUpdates and setWebhook methods.
You can use &, + or | operators for make combination of allowed updates.
Example:

>>> bot.get_updates(allowed_updates=AllowedUpdates.MESSAGE + AllowedUpdates.

˓→EDITED_MESSAGE)

PhotoSize

class aiogram.types.photo_size.PhotoSize(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents one size of a photo or a file / sticker thumbnail.
https://core.telegram.org/bots/api#photosize
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 121

aiogram Documentation, Release 2.11.2

Venue

class aiogram.types.venue.Venue(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a venue.
https://core.telegram.org/bots/api#venue
Deserialize object
Parameters
• conf –
• kwargs –

ChosenInlineResult

class aiogram.types.chosen_inline_result.ChosenInlineResult(conf: Op-

tional[Dict[str,
Any]] = None,
**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Represents a result of an inline query that was chosen by the user and sent to their chat partner.
Note: It is necessary to enable inline feedback via @Botfather in order to receive these objects in updates. Your
bot can accept payments from Telegram users. Please see the introduction to payments for more details on the
process and how to set up payments for your bot. Please note that users will need Telegram v.4.0 or higher to
use payments (released on May 18, 2017).
https://core.telegram.org/bots/api#choseninlineresult
Deserialize object
Parameters
• conf –
• kwargs –

VideoNote

class aiogram.types.video_note.VideoNote(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject, aiogram.types.mixins.Downloadable
This object represents a video message (available in Telegram apps as of v.4.0).
https://core.telegram.org/bots/api#videonote
Deserialize object
Parameters
• conf –
• kwargs –

122 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

WebhookInfo

class aiogram.types.webhook_info.WebhookInfo(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Contains information about the current status of a webhook.
https://core.telegram.org/bots/api#webhookinfo
Deserialize object
Parameters
• conf –
• kwargs –

PassportFile

class aiogram.types.passport_file.PassportFile(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents a file uploaded to Telegram Passport. Currently all Telegram Passport files are in JPEG
format when decrypted and don’t exceed 10MB.
https://core.telegram.org/bots/api#passportfile
Deserialize object
Parameters
• conf –
• kwargs –

ChatMember

class aiogram.types.chat_member.ChatMember(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object contains information about one member of a chat.
https://core.telegram.org/bots/api#chatmember
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 123

aiogram Documentation, Release 2.11.2

ChatMemberStatus

class aiogram.types.chat_member.ChatMemberStatus
Bases: aiogram.utils.helper.Helper
Chat member status

ShippingOption

class aiogram.types.shipping_option.ShippingOption(id: String, title: String, prices:

List[aiogram.types.labeled_price.LabeledPrice]
= None)
Bases: aiogram.types.base.TelegramObject
This object represents one shipping option.
https://core.telegram.org/bots/api#shippingoption
Deserialize object
Parameters
• conf –
• kwargs –
add(price: aiogram.types.labeled_price.LabeledPrice)
Add price
Parameters price –
Returns

ChatPhoto

class aiogram.types.chat_photo.ChatPhoto(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represents a chat photo.
https://core.telegram.org/bots/api#chatphoto
Deserialize object
Parameters
• conf –
• kwargs –
async download_small(destination=None, timeout=30, chunk_size=65536, seek=True,
make_dirs=True)
Download file
Parameters
• destination – filename or instance of io.IOBase. For e. g. io.BytesIO
• timeout – Integer
• chunk_size – Integer

124 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• seek – Boolean - go to start of file when downloading is finished.

• make_dirs – Make dirs if not exist
Returns destination
async download_big(destination=None, timeout=30, chunk_size=65536, seek=True,
make_dirs=True)
Download file
Parameters
• destination – filename or instance of io.IOBase. For e. g. io.BytesIO
• timeout – Integer
• chunk_size – Integer
• seek – Boolean - go to start of file when downloading is finished.
• make_dirs – Make dirs if not exist
Returns destination

Contact

class aiogram.types.contact.Contact(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a phone contact.
https://core.telegram.org/bots/api#contact
Deserialize object
Parameters
• conf –
• kwargs –

Message

class aiogram.types.message.Message(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object represents a message.
https://core.telegram.org/bots/api#message
Deserialize object
Parameters
• conf –
• kwargs –
is_forward() → bool
Check that the message is forwarded. Only forward_date is required to be in forwarded message.
Returns bool
is_command() → bool
Check message text is command

4.4. Telegram 125

aiogram Documentation, Release 2.11.2

Returns bool
get_full_command() → Optional[Tuple[str, str]]
Split command and args
Returns tuple of (command, args)
get_command(pure=False) → Optional[str]
Get command from message
Returns
get_args() → Optional[str]
Get arguments
Returns
parse_entities(as_html=True) → str
Text or caption formatted as HTML or Markdown.
Returns str
property md_text
Text or caption formatted as markdown.
Returns str
property html_text
Text or caption formatted as HTML
Returns str
property url
Get URL for the message
Returns str
link(text, as_html=True) → str
Generate URL for using in text messages with HTML or MD parse mode
Parameters
• text – link label
• as_html – generate as HTML
Returns str
async answer(text: String, parse_mode: Optional[String] = None, enti-
ties: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_web_page_preview: Optional[Boolean] =
None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False) →
aiogram.types.message.Message
Answer to this message
Parameters
• text (base.String) – Text of the message to be sent

126 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,

if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• entities (typing.Optional[typing.List[MessageEntity]]) – List of
special entities that appear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (typing.Optional[base.Boolean]) – Dis-
ables link previews for links in this message
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async answer_photo(photo: Union[InputFile, String], caption: Optional[String] =
None, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] =
None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False)
→ aiogram.types.message.Message
Use this method to send photos.
Source: https://core.telegram.org/bots/api#sendphoto
Parameters
• photo (typing.Union[base.InputFile, base.String]) – Photo to send
• caption (typing.Optional[base.String]) – Photo caption (may also be used
when resending photos by file_id), 0-1024 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound

4.4. Telegram 127

aiogram Documentation, Release 2.11.2

• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async answer_audio(audio: Union[InputFile, String], caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] = None,
duration: Optional[Integer] = None, performer: Optional[String] =
None, title: Optional[String] = None, thumb: Optional[Union[InputFile,
String]] = None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False)
→ aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display them in the music player. Your
audio must be in the .mp3 format.
For sending voice messages, use the sendVoice method instead.
Source: https://core.telegram.org/bots/api#sendaudio
Parameters
• audio (typing.Union[base.InputFile, base.String]) – Audio file to
send.
• caption (typing.Optional[base.String]) – Audio caption, 0-200 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• duration (typing.Optional[base.Integer]) – Duration of the audio in sec-
onds
• performer (typing.Optional[base.String]) – Performer
• title (typing.Optional[base.String]) – Track name
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.

128 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• disable_notification (typing.Optional[base.Boolean]) – Sends the

message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_animation(animation: Union[InputFile, String], duration: Optional[Integer]
= None, width: Optional[Integer] = None, height: Op-
tional[Integer] = None, thumb: Optional[Union[InputFile,
String]] = None, caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_notification: Optional[Boolean]
= None, allow_sending_without_reply: Op-
tional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean
= False) → aiogram.types.message.Message
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound).
On success, the sent Message is returned. Bots can currently send animation files of up to 50 MB in size,
this limit may be changed in the future.
Source https://core.telegram.org/bots/api#sendanimation
Parameters
• animation (typing.Union[base.InputFile, base.String]) – Anima-
tion to send. Pass a file_id as String to send an animation that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get an animation
from the Internet, or upload a new animation using multipart/form-data
• duration (typing.Optional[base.Integer]) – Duration of sent animation in
seconds
• width (typing.Optional[base.Integer]) – Animation width
• height (typing.Optional[base.Integer]) – Animation height
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• caption (typing.Optional[base.String]) – Animation caption (may also be
used when resending animation by file_id), 0-1024 characters

4.4. Telegram 129

aiogram Documentation, Release 2.11.2

• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,

if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[typing.Union[types.
InlineKeyboardMarkup, types.ReplyKeyboardMarkup, types.
ReplyKeyboardRemove, types.ForceReply], None]) – Additional inter-
face options. A JSON-serialized object for an inline keyboard, custom reply keyboard,
instructions to remove reply keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async answer_document(document: Union[InputFile, String], thumb: Optional[Union[InputFile,
String]] = None, caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_content_type_detection: Op-
tional[Boolean] = None, disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
False) → aiogram.types.message.Message
Use this method to send general files. On success, the sent Message is returned. Bots can currently send
files of any type of up to 50 MB in size, this limit may be changed in the future.
Source: https://core.telegram.org/bots/api#senddocument
Parameters
• document (typing.Union[base.InputFile, base.String]) – File to send
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent
• caption (typing.Optional[base.String]) – Document caption (may also be
used when resending documents by file_id), 0-1024 characters
• disable_content_type_detection (typing.Optional[base.
Boolean]) – Disables automatic server-side content type detection for files uploaded
using multipart/form-data
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.

130 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply], None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (typing.Optional[base.Boolean]) – True if the message is a reply
Returns On success, the sent Message is returned
Return type types.Message
async answer_video(video: Union[InputFile, String], duration: Optional[Integer] = None,
width: Optional[Integer] = None, height: Optional[Integer] = None,
thumb: Optional[Union[InputFile, String]] = None, caption: Op-
tional[String] = None, parse_mode: Optional[String] = None, cap-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, supports_streaming: Optional[Boolean] = None,
disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False)
→ aiogram.types.message.Message
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as
Document).
Source: https://core.telegram.org/bots/api#sendvideo
Parameters
• video (typing.Union[base.InputFile, base.String]) – Video to send.
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• width (typing.Optional[base.Integer]) – Video width
• height (typing.Optional[base.Integer]) – Video height
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent. The thumbnail should be in JPEG format and less than 200 kB
in size. A thumbnail‘s width and height should not exceed 320.
• caption (typing.Optional[base.String]) – Video caption (may also be used
when resending videos by file_id), 0-200 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption

4.4. Telegram 131

aiogram Documentation, Release 2.11.2

• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• supports_streaming (typing.Optional[base.Boolean]) – Pass True, if
the uploaded video is suitable for streaming
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_voice(voice: Union[InputFile, String], caption: Optional[String] =
None, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] =
None, duration: Optional[Integer] = None, disable_notification:
Optional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False)
→ aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice
message.
For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as
Audio or Document).
Source: https://core.telegram.org/bots/api#sendvoice
Parameters
• voice (typing.Union[base.InputFile, base.String]) – Audio file to
send.
• caption (typing.Optional[base.String]) – Voice message caption, 0-200
characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode

132 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• duration (typing.Optional[base.Integer]) – Duration of the voice mes-

sage in seconds
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_video_note(video_note: Union[InputFile, String], duration: Optional[Integer]
= None, length: Optional[Integer] = None, thumb: Op-
tional[Union[InputFile, String]] = None, disable_notification:
Optional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean
= False) → aiogram.types.message.Message
As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long. Use this method
to send video messages.
Source: https://core.telegram.org/bots/api#sendvideonote
Parameters
• video_note (typing.Union[base.InputFile, base.String]) – Video
note to send.
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• length (typing.Optional[base.Integer]) – Video width and height
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized

4.4. Telegram 133

aiogram Documentation, Release 2.11.2

object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_media_group(media: Union[aiogram.types.input_media.MediaGroup,
List], disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply:
Boolean = False) → List[aiogram.types.message.Message]
Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio
files can be only group in an album with messages of the same type. On success, an array of Messages that
were sent is returned.
Source: https://core.telegram.org/bots/api#sendmediagroup
Parameters
• media (typing.Union[types.MediaGroup, typing.List]) – A JSON-
serialized array describing photos and videos to be sent
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, an array of the sent Messages is returned.
Return type typing.List[types.Message]
async answer_location(latitude: Float, longitude: Float, live_period: Op-
tional[Integer] = None, disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
False) → aiogram.types.message.Message
Use this method to send point on the map.
Source: https://core.telegram.org/bots/api#sendlocation
Parameters
• latitude (base.Float) – Latitude of the location
• longitude (base.Float) – Longitude of the location
• live_period (typing.Optional[base.Integer]) – Period in seconds for
which the location will be updated
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.

134 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_venue(latitude: Float, longitude: Float, title: String, address: String,
foursquare_id: Optional[String] = None, foursquare_type: Optional[String]
= None, google_place_id: Optional[String] = None, google_place_type:
Optional[String] = None, disable_notification: Optional[Boolean] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False)
→ aiogram.types.message.Message
Use this method to send information about a venue.
Source: https://core.telegram.org/bots/api#sendvenue
Parameters
• latitude (base.Float) – Latitude of the venue
• longitude (base.Float) – Longitude of the venue
• title (base.String) – Name of the venue
• address (base.String) – Address of the venue
• foursquare_id (typing.Optional[base.String]) – Foursquare identifier of
the venue
• foursquare_type (typing.Optional[base.String]) – Foursquare type of
the venue, if known
• google_place_id (typing.Optional[base.String]) – Google Places iden-
tifier of the venue
• google_place_type (typing.Optional[base.String]) – Google Places
type of the venue. See supported types: https://developers.google.com/places/
web-service/supported_types
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized

4.4. Telegram 135

aiogram Documentation, Release 2.11.2

object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_contact(phone_number: String, first_name: String, last_name: Optional[String]
= None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
False) → aiogram.types.message.Message
Use this method to send phone contacts.
Source: https://core.telegram.org/bots/api#sendcontact
Parameters
• phone_number (base.String) – Contact’s phone number
• first_name (base.String) – Contact’s first name
• last_name (typing.Optional[base.String]) – Contact’s last name
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_sticker(sticker: Union[InputFile, String], disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
False) → aiogram.types.message.Message
Use this method to send .webp stickers.
Source: https://core.telegram.org/bots/api#sendsticker
Parameters
• sticker (typing.Union[base.InputFile, base.String]) – Sticker to
send.

136 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• disable_notification (typing.Optional[base.Boolean]) – Sends the

message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async answer_poll(question: String, options: List[String], is_anonymous: Op-
tional[Boolean] = None, type: Optional[String] = None, al-
lows_multiple_answers: Optional[Boolean] = None, correct_option_id:
Optional[Integer] = None, explanation: Optional[String] = None, ex-
planation_parse_mode: Optional[String] = None, explanation_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] = None,
open_period: Optional[Integer] = None, close_date: Optional[Union[Integer,
datetime.datetime, datetime.timedelta]] = None, is_closed: Op-
tional[Boolean] = None, disable_notification: Optional[Boolean] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False) →
aiogram.types.message.Message
Use this method to send a native poll. On success, the sent Message is returned.
Source: https://core.telegram.org/bots/api#sendpoll
Parameters
• question (base.String) – Poll question, 1-255 characters
• options (typing.List[base.String]) – List of answer options, 2-10 strings 1-
100 characters each
• is_anonymous (typing.Optional[base.Boolean]) – True, if the poll needs
to be anonymous, defaults to True
• type (typing.Optional[base.String]) – Poll type, “quiz” or “regular”, de-
faults to “regular”
• allows_multiple_answers (typing.Optional[base.Boolean]) – True,
if the poll allows multiple answers, ignored for polls in quiz mode, defaults to False
• correct_option_id (typing.Optional[base.Integer]) – 0-based identi-
fier of the correct answer option, required for polls in quiz mode
• explanation (typing.Optional[base.String]) – Text that is shown when
a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200
characters with at most 2 line feeds after entities parsing

4.4. Telegram 137

aiogram Documentation, Release 2.11.2

• explanation_parse_mode (typing.Optional[base.String]) – Mode for

parsing entities in the explanation. See formatting options for more details.
• explanation_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• open_period (typing.Optional[base.Integer]) – Amount of time in sec-
onds the poll will be active after creation, 5-600. Can’t be used together with close_date.
• close_date (typing.Union[base.Integer, datetime.datetime,
datetime.timedelta, None]) – Point in time (Unix timestamp) when the poll
will be automatically closed. Must be at least 5 and no more than 600 seconds in the
future. Can’t be used together with open_period.
• is_closed (typing.Optional[base.Boolean]) – Pass True, if the poll needs
to be immediately closed
• disable_notification (typing.Optional[Boolean]) – Sends the message
silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async answer_dice(emoji: Optional[String] = None, disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = False) →
aiogram.types.message.Message
Use this method to send an animated emoji that will display a random value. On success, the sent Message
is returned.
Source: https://core.telegram.org/bots/api#senddice
Parameters
• emoji (typing.Optional[base.String]) – Emoji on which the dice throw ani-
mation is based. Currently, must be one of “”, “”, “”, “”, or “”. Dice can have values 1-6
for “” and “”, values 1-5 for “” and “”, and values 1-64 for “”. Defaults to “”
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found

138 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply(text: String, parse_mode: Optional[String] = None, entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] = None, dis-
able_web_page_preview: Optional[Boolean] = None, disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply: Optional[Boolean] = None, re-
ply_markup: Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Reply to this message
Parameters
• text (base.String) – Text of the message to be sent
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• entities (typing.Optional[typing.List[MessageEntity]]) – List of
special entities that appear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (typing.Optional[base.Boolean]) – Dis-
ables link previews for links in this message
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message

4.4. Telegram 139

aiogram Documentation, Release 2.11.2

async reply_photo(photo: Union[InputFile, String], caption: Optional[String] =

None, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] =
None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Use this method to send photos.
Source: https://core.telegram.org/bots/api#sendphoto
Parameters
• photo (typing.Union[base.InputFile, base.String]) – Photo to send
• caption (typing.Optional[base.String]) – Photo caption (may also be used
when resending photos by file_id), 0-1024 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async reply_audio(audio: Union[InputFile, String], caption: Optional[String] =
None, parse_mode: Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] = None, dura-
tion: Optional[Integer] = None, performer: Optional[String] = None,
title: Optional[String] = None, thumb: Optional[Union[InputFile,
String]] = None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display them in the music player. Your

140 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

audio must be in the .mp3 format.

For sending voice messages, use the sendVoice method instead.
Source: https://core.telegram.org/bots/api#sendaudio
Parameters
• audio (typing.Union[base.InputFile, base.String]) – Audio file to
send.
• caption (typing.Optional[base.String]) – Audio caption, 0-200 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• duration (typing.Optional[base.Integer]) – Duration of the audio in sec-
onds
• performer (typing.Optional[base.String]) – Performer
• title (typing.Optional[base.String]) – Track name
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message

4.4. Telegram 141

aiogram Documentation, Release 2.11.2

async reply_animation(animation: Union[InputFile, String], duration: Optional[Integer]

= None, width: Optional[Integer] = None, height: Op-
tional[Integer] = None, thumb: Optional[Union[InputFile,
String]] = None, caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, disable_notification: Optional[Boolean]
= None, allow_sending_without_reply: Op-
tional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
True) → aiogram.types.message.Message
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound).
On success, the sent Message is returned. Bots can currently send animation files of up to 50 MB in size,
this limit may be changed in the future.
Source https://core.telegram.org/bots/api#sendanimation
Parameters
• animation (typing.Union[base.InputFile, base.String]) – Anima-
tion to send. Pass a file_id as String to send an animation that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get an animation
from the Internet, or upload a new animation using multipart/form-data
• duration (typing.Optional[base.Integer]) – Duration of sent animation in
seconds
• width (typing.Optional[base.Integer]) – Animation width
• height (typing.Optional[base.Integer]) – Animation height
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• caption (typing.Optional[base.String]) – Animation caption (may also be
used when resending animation by file_id), 0-1024 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[typing.Union[types.
InlineKeyboardMarkup, types.ReplyKeyboardMarkup, types.
ReplyKeyboardRemove, types.ForceReply], None]) – Additional inter-

142 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

face options. A JSON-serialized object for an inline keyboard, custom reply keyboard,
instructions to remove reply keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async reply_document(document: Union[InputFile, String], thumb: Optional[Union[InputFile,
String]] = None, caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] =
None, disable_content_type_detection: Optional[Boolean] =
None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
True) → aiogram.types.message.Message
Use this method to send general files. On success, the sent Message is returned. Bots can currently send
files of any type of up to 50 MB in size, this limit may be changed in the future.
Source: https://core.telegram.org/bots/api#senddocument
Parameters
• document (typing.Union[base.InputFile, base.String]) – File to send
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent
• caption (typing.Optional[base.String]) – Document caption (may also be
used when resending documents by file_id), 0-1024 characters
• disable_content_type_detection (typing.Optional[base.
Boolean]) – Disables automatic server-side content type detection for files uploaded
using multipart/form-data
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply], None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (typing.Optional[base.Boolean]) – True if the message is a reply

4.4. Telegram 143

aiogram Documentation, Release 2.11.2

Returns On success, the sent Message is returned

Return type types.Message
async reply_video(video: Union[InputFile, String], duration: Optional[Integer] = None,
width: Optional[Integer] = None, height: Optional[Integer] = None,
thumb: Optional[Union[InputFile, String]] = None, caption: Op-
tional[String] = None, parse_mode: Optional[String] = None, cap-
tion_entities: Optional[List[aiogram.types.message_entity.MessageEntity]]
= None, supports_streaming: Optional[Boolean] = None,
disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as
Document).
Source: https://core.telegram.org/bots/api#sendvideo
Parameters
• video (typing.Union[base.InputFile, base.String]) – Video to send.
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• width (typing.Optional[base.Integer]) – Video width
• height (typing.Optional[base.Integer]) – Video height
• thumb (typing.Union[base.InputFile, base.String, None]) –
Thumbnail of the file sent. The thumbnail should be in JPEG format and less than 200 kB
in size. A thumbnail‘s width and height should not exceed 320.
• caption (typing.Optional[base.String]) – Video caption (may also be used
when resending videos by file_id), 0-200 characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• supports_streaming (typing.Optional[base.Boolean]) – Pass True, if
the uploaded video is suitable for streaming
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized

144 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_voice(voice: Union[InputFile, String], caption: Optional[String] = None,
parse_mode: Optional[String] = None, caption_entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] = None, duration:
Optional[Integer] = None, disable_notification: Optional[Boolean] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice
message.
For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as
Audio or Document).
Source: https://core.telegram.org/bots/api#sendvoice
Parameters
• voice (typing.Union[base.InputFile, base.String]) – Audio file to
send.
• caption (typing.Optional[base.String]) – Voice message caption, 0-200
characters
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in the
media caption
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• duration (typing.Optional[base.Integer]) – Duration of the voice mes-
sage in seconds
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.

4.4. Telegram 145

aiogram Documentation, Release 2.11.2

Return type types.Message

async reply_video_note(video_note: Union[InputFile, String], duration: Optional[Integer]
= None, length: Optional[Integer] = None, thumb: Op-
tional[Union[InputFile, String]] = None, disable_notification:
Optional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean
= True) → aiogram.types.message.Message
As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long. Use this method
to send video messages.
Source: https://core.telegram.org/bots/api#sendvideonote
Parameters
• video_note (typing.Union[base.InputFile, base.String]) – Video
note to send.
• duration (typing.Optional[base.Integer]) – Duration of sent video in sec-
onds
• length (typing.Optional[base.Integer]) – Video width and height
• thumb (typing.Union[typing.Union[base.InputFile, base.
String], None]) – Thumbnail of the file sent. The thumbnail should be in
JPEG format and less than 200 kB in size. A thumbnail‘s width and height should not
exceed 320.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (:obj:`typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove, types.ForceReply, None] `)
– Additional interface options. A JSON-serialized object for an inline keyboard, custom
reply keyboard, instructions to remove reply keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_media_group(media: Union[aiogram.types.input_media.MediaGroup,
List], disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply:
Boolean = True) → List[aiogram.types.message.Message]
Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio
files can be only group in an album with messages of the same type. On success, an array of Messages that
were sent is returned.
Source: https://core.telegram.org/bots/api#sendmediagroup
Parameters

146 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• media (typing.Union[types.MediaGroup, typing.List]) – A JSON-

serialized array describing photos and videos to be sent
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, an array of the sent Messages is returned.
Return type typing.List[types.Message]
async reply_location(latitude: Float, longitude: Float, live_period: Optional[Integer] = None,
disable_notification: Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
True) → aiogram.types.message.Message
Use this method to send point on the map.
Source: https://core.telegram.org/bots/api#sendlocation
Parameters
• latitude (base.Float) – Latitude of the location
• longitude (base.Float) – Longitude of the location
• live_period (typing.Optional[base.Integer]) – Period in seconds for
which the location will be updated
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_venue(latitude: Float, longitude: Float, title: String, address: String, foursquare_id:
Optional[String] = None, foursquare_type: Optional[String] = None,
google_place_id: Optional[String] = None, google_place_type: Op-
tional[String] = None, disable_notification: Optional[Boolean] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True) →
aiogram.types.message.Message
Use this method to send information about a venue.

4.4. Telegram 147

aiogram Documentation, Release 2.11.2

Source: https://core.telegram.org/bots/api#sendvenue
Parameters
• latitude (base.Float) – Latitude of the venue
• longitude (base.Float) – Longitude of the venue
• title (base.String) – Name of the venue
• address (base.String) – Address of the venue
• foursquare_id (typing.Optional[base.String]) – Foursquare identifier of
the venue
• foursquare_type (typing.Optional[base.String]) – Foursquare type of
the venue, if known
• google_place_id (typing.Optional[base.String]) – Google Places iden-
tifier of the venue
• google_place_type (typing.Optional[base.String]) – Google Places
type of the venue. See supported types: https://developers.google.com/places/
web-service/supported_types
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_contact(phone_number: String, first_name: String, last_name: Optional[String]
= None, disable_notification: Optional[Boolean] = None, al-
low_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
True) → aiogram.types.message.Message
Use this method to send phone contacts.
Source: https://core.telegram.org/bots/api#sendcontact
Parameters
• phone_number (base.String) – Contact’s phone number
• first_name (base.String) – Contact’s first name
• last_name (typing.Optional[base.String]) – Contact’s last name

148 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• disable_notification (typing.Optional[base.Boolean]) – Sends the

message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_poll(question: String, options: List[String], is_anonymous: Op-
tional[Boolean] = None, type: Optional[String] = None, al-
lows_multiple_answers: Optional[Boolean] = None, correct_option_id:
Optional[Integer] = None, explanation: Optional[String] = None, ex-
planation_parse_mode: Optional[String] = None, explanation_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] = None,
open_period: Optional[Integer] = None, close_date: Optional[Union[Integer,
datetime.datetime, datetime.timedelta]] = None, is_closed: Op-
tional[Boolean] = None, disable_notification: Optional[Boolean] = None,
allow_sending_without_reply: Optional[Boolean] = None, reply_markup:
Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True)
→ aiogram.types.message.Message
Use this method to send a native poll. On success, the sent Message is returned.
Source: https://core.telegram.org/bots/api#sendpoll
Parameters
• question (base.String) – Poll question, 1-255 characters
• options (typing.List[base.String]) – List of answer options, 2-10 strings 1-
100 characters each
• is_anonymous (typing.Optional[base.Boolean]) – True, if the poll needs
to be anonymous, defaults to True
• type (typing.Optional[base.String]) – Poll type, “quiz” or “regular”, de-
faults to “regular”
• allows_multiple_answers (typing.Optional[base.Boolean]) – True,
if the poll allows multiple answers, ignored for polls in quiz mode, defaults to False
• correct_option_id (typing.Optional[base.Integer]) – 0-based identi-
fier of the correct answer option, required for polls in quiz mode
• explanation (typing.Optional[base.String]) – Text that is shown when
a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200
characters with at most 2 line feeds after entities parsing

4.4. Telegram 149

aiogram Documentation, Release 2.11.2

• explanation_parse_mode (typing.Optional[base.String]) – Mode for

parsing entities in the explanation. See formatting options for more details.
• explanation_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• open_period (typing.Optional[base.Integer]) – Amount of time in sec-
onds the poll will be active after creation, 5-600. Can’t be used together with close_date.
• close_date (typing.Union[base.Integer, datetime.datetime,
datetime.timedelta, None]) – Point in time (Unix timestamp) when the poll
will be automatically closed. Must be at least 5 and no more than 600 seconds in the
future. Can’t be used together with open_period.
• is_closed (typing.Optional[base.Boolean]) – Pass True, if the poll needs
to be immediately closed
• disable_notification (typing.Optional[Boolean]) – Sends the message
silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned
Return type types.Message
async reply_sticker(sticker: Union[InputFile, String], disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean =
True) → aiogram.types.message.Message
Use this method to send .webp stickers.
Source: https://core.telegram.org/bots/api#sendsticker
Parameters
• sticker (typing.Union[base.InputFile, base.String]) – Sticker to
send.
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound.
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,

150 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

types.ForceReply, None]) – Additional interface options. A JSON-serialized

object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async reply_dice(emoji: Optional[String] = None, disable_notification: Op-
tional[Boolean] = None, allow_sending_without_reply:
Optional[Boolean] = None, reply_markup: Op-
tional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardRemove,
aiogram.types.force_reply.ForceReply]] = None, reply: Boolean = True)
→ aiogram.types.message.Message
Use this method to send an animated emoji that will display a random value. On success, the sent Message
is returned.
Source: https://core.telegram.org/bots/api#senddice
Parameters
• emoji (typing.Optional[base.String]) – Emoji on which the dice throw ani-
mation is based. Currently, must be one of “”, “”, “”, “”, or “”. Dice can have values 1-6
for “” and “”, values 1-5 for “” and “”, and values 1-64 for “”. Defaults to “”
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
• allow_sending_without_reply (typing.Optional[base.Boolean]) –
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (typing.Union[types.InlineKeyboardMarkup,
types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove,
types.ForceReply, None]) – Additional interface options. A JSON-serialized
object for an inline keyboard, custom reply keyboard, instructions to remove reply
keyboard or to force a reply from the user
• reply (base.Boolean) – fill ‘reply_to_message_id’
Returns On success, the sent Message is returned.
Return type types.Message
async forward(chat_id: Union[Integer, String], disable_notification: Optional[Boolean] = None)
→ aiogram.types.message.Message
Forward this message
Source: https://core.telegram.org/bots/api#forwardmessage
Parameters
• chat_id (typing.Union[base.Integer, base.String]) – Unique identi-
fier for the target chat or username of the target channel
• disable_notification (typing.Optional[base.Boolean]) – Sends the
message silently. Users will receive a notification with no sound
Returns On success, the sent Message is returned

4.4. Telegram 151

aiogram Documentation, Release 2.11.2

Return type types.Message

async edit_text(text: String, parse_mode: Optional[String] = None, entities: Op-
tional[List[aiogram.types.message_entity.MessageEntity]] = None, dis-
able_web_page_preview: Optional[Boolean] = None, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] = None) →
Union[aiogram.types.message.Message, Boolean]
Use this method to edit text and game messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagetext
Parameters
• text (base.String) – New text of the message
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• entities (typing.Optional[typing.List[MessageEntity]]) – List of
special entities that appear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (typing.Optional[base.Boolean]) – Dis-
ables link previews for links in this message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard.
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async edit_caption(caption: String, parse_mode: Optional[String] = None, caption_entities:
Optional[List[aiogram.types.message_entity.MessageEntity]] = None, re-
ply_markup: Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → Union[aiogram.types.message.Message, Boolean]
Use this method to edit captions of messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagecaption
Parameters
• caption (typing.Optional[base.String]) – New caption of the message
• parse_mode (typing.Optional[base.String]) – Send Markdown or HTML,
if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your
bot’s message.
• caption_entities (typing.Optional[typing.
List[MessageEntity]]) – List of special entities that appear in message text,
which can be specified instead of parse_mode
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for an inline keyboard
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async edit_media(media: aiogram.types.input_media.InputMedia, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup] = None) →
Union[aiogram.types.message.Message, Boolean]

152 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Use this method to edit audio, document, photo, or video messages. If a message is a part of a message
album, then it can be edited only to a photo or a video. Otherwise, message type can be changed arbitrarily.
When inline message is edited, new file can’t be uploaded. Use previously uploaded file via its file_id or
specify a URL.
On success, if the edited message was sent by the bot, the edited Message is returned, otherwise True is
returned.
Source https://core.telegram.org/bots/api#editmessagemedia
Parameters
• media (types.InputMedia) – A JSON-serialized object for a new media content of
the message
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new inline keyboard
Returns On success, if the edited message was sent by the bot, the edited Message is returned,
otherwise True is returned
Return type typing.Union[types.Message, base.Boolean]
async edit_reply_markup(reply_markup: Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → Union[aiogram.types.message.Message, Boolean]
Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots).
Source: https://core.telegram.org/bots/api#editmessagereplymarkup
Parameters reply_markup (typing.Optional[types.
InlineKeyboardMarkup]) – A JSON-serialized object for an inline keyboard
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async delete_reply_markup() → Union[aiogram.types.message.Message, Boolean]
Use this method to delete reply markup of messages sent by the bot or via the bot (for inline bots).
Returns On success, if edited message is sent by the bot, the edited Message is returned, other-
wise True is returned.
Return type typing.Union[types.Message, base.Boolean]
async edit_live_location(latitude: Float, longitude: Float, reply_markup: Op-
tional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]
= None) → Union[aiogram.types.message.Message, Boolean]
Use this method to edit live location messages sent by the bot or via the bot (for inline bots). A location can
be edited until its live_period expires or editing is explicitly disabled by a call to stopMessageLiveLocation.
Source: https://core.telegram.org/bots/api#editmessagelivelocation
Parameters
• latitude (base.Float) – Latitude of new location
• longitude (base.Float) – Longitude of new location
• reply_markup (typing.Optional[types.InlineKeyboardMarkup]) – A
JSON-serialized object for a new inline keyboard.
Returns On success, if the edited message was sent by the bot, the edited Message is returned,
otherwise True is returned.
Return type typing.Union[types.Message, base.Boolean]

4.4. Telegram 153

aiogram Documentation, Release 2.11.2

async stop_live_location(reply_markup: Optional[aiogram.types.inline_keyboard.InlineKeyboardMarkup]

= None) → Union[aiogram.types.message.Message, Boolean]
Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots)
before live_period expires.
Source: https://core.telegram.org/bots/api#stopmessagelivelocation
Parameters reply_markup (typing.Optional[types.
InlineKeyboardMarkup]) – A JSON-serialized object for a new inline keyboard.
Returns On success, if the message was sent by the bot, the sent Message is returned, otherwise
True is returned.
Return type typing.Union[types.Message, base.Boolean]
async delete() → Boolean
Use this method to delete a message, including service messages, with the following limitations: - A
message can only be deleted if it was sent less than 48 hours ago. - Bots can delete outgoing messages
in private chats, groups, and supergroups. - Bots can delete incoming messages in private chats. - Bots
granted can_post_messages permissions can delete outgoing messages in channels. - If the bot is an
administrator of a group, it can delete any message there. - If the bot has can_delete_messages permission
in a supergroup or a channel, it can delete any message there.
Source: https://core.telegram.org/bots/api#deletemessage
Returns Returns True on success
Return type base.Boolean
async pin(disable_notification: Optional[Boolean] = None) → Boolean
Use this method to add a message to the list of pinned messages in a chat. If the chat is not a private chat,
the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin
right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#pinchatmessage
Parameters disable_notification (typing.Optional[base.Boolean]) – Pass
True, if it is not necessary to send a notification to all group members about the new pinned
message
Returns Returns True on success
Return type base.Boolean
async unpin() → Boolean
Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private
chat, the bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’
admin right in a supergroup or ‘can_edit_messages’ admin right in a channel. Returns True on success.
Source: https://core.telegram.org/bots/api#unpinchatmessage
Returns Returns True on success
Return type base.Boolean
send_copy(chat_id: Union[str, int], disable_notification: Optional[bool] = None, dis-
able_web_page_preview: Optional[bool] = None, reply_to_message_id: Op-
tional[int] = None, allow_sending_without_reply: Optional[Boolean] = None, re-
ply_markup: Optional[Union[aiogram.types.inline_keyboard.InlineKeyboardMarkup,
aiogram.types.reply_keyboard.ReplyKeyboardMarkup]] = None) →
aiogram.types.message.Message
Send copy of current message
Parameters

154 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• chat_id –
• disable_notification –
• disable_web_page_preview – for text messages only
• reply_to_message_id –
• allow_sending_without_reply –
• reply_markup –
Returns

ContentType

class aiogram.types.message.ContentType
Bases: aiogram.utils.helper.Helper
List of message content types
WARNING: Single elements
Key TEXT
Key AUDIO
Key DOCUMENT
Key GAME
Key PHOTO
Key STICKER
Key VIDEO
Key VIDEO_NOTE
Key VOICE
Key CONTACT
Key LOCATION
Key VENUE
Key NEW_CHAT_MEMBERS
Key LEFT_CHAT_MEMBER
Key INVOICE
Key SUCCESSFUL_PAYMENT
Key CONNECTED_WEBSITE
Key MIGRATE_TO_CHAT_ID
Key MIGRATE_FROM_CHAT_ID
Key UNKNOWN
Key ANY

4.4. Telegram 155

aiogram Documentation, Release 2.11.2

ContentTypes

class aiogram.types.message.ContentTypes
Bases: aiogram.utils.helper.Helper
List of message content types
WARNING: List elements.
Key TEXT
Key AUDIO
Key DOCUMENT
Key GAME
Key PHOTO
Key STICKER
Key VIDEO
Key VIDEO_NOTE
Key VOICE
Key CONTACT
Key LOCATION
Key VENUE
Key NEW_CHAT_MEMBERS
Key LEFT_CHAT_MEMBER
Key INVOICE
Key SUCCESSFUL_PAYMENT
Key CONNECTED_WEBSITE
Key MIGRATE_TO_CHAT_ID
Key MIGRATE_FROM_CHAT_ID
Key UNKNOWN
Key ANY

ParseMode

class aiogram.types.message.ParseMode
Bases: aiogram.utils.helper.Helper
Parse modes
Key MARKDOWN
Key HTML

156 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

MaskPosition

class aiogram.types.mask_position.MaskPosition(conf: Optional[Dict[str, Any]] = None,

**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object describes the position on faces where a mask should be placed by default.
https://core.telegram.org/bots/api#maskposition
Deserialize object
Parameters
• conf –
• kwargs –

UserProfilePhotos

class aiogram.types.user_profile_photos.UserProfilePhotos(conf: Optional[Dict[str,

Any]] = None,
**kwargs: Any)
Bases: aiogram.types.base.TelegramObject
This object represent a user’s profile pictures.
https://core.telegram.org/bots/api#userprofilephotos
Deserialize object
Parameters
• conf –
• kwargs –

Invoice

class aiogram.types.invoice.Invoice(conf: Optional[Dict[str, Any]] = None, **kwargs: Any)

Bases: aiogram.types.base.TelegramObject
This object contains basic information about an invoice.
https://core.telegram.org/bots/api#invoice
Deserialize object
Parameters
• conf –
• kwargs –

4.4. Telegram 157

aiogram Documentation, Release 2.11.2

AuthWidgetData

class aiogram.types.auth_widget_data.AuthWidgetData(conf: Optional[Dict[str, Any]] =

None, **kwargs: Any)
Bases: aiogram.types.base.TelegramObject
Deserialize object
Parameters
• conf –
• kwargs –
classmethod parse(request: aiohttp.web_request.Request) →
aiogram.types.auth_widget_data.AuthWidgetData
Parse request as Telegram auth widget data.
Parameters request –
Returns AuthWidgetData
Raise aiohttp.web.HTTPBadRequest

4.5 Dispatcher

4.5.1 Filters

Basics

Filter factory greatly simplifies the reuse of filters when registering handlers.

Filters factory

class aiogram.dispatcher.filters.FiltersFactory(dispatcher)
Bases: object
Filters factory
bind(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter], validator: Op-
tional[Callable] = None, event_handlers: Optional[List[aiogram.dispatcher.handler.Handler]]
= None, exclude_event_handlers: Optional[Iterable[aiogram.dispatcher.handler.Handler]] =
None)
Register filter
Parameters
• callback – callable or subclass of AbstractFilter
• validator – custom validator.
• event_handlers – list of instances of Handler
• exclude_event_handlers – list of excluded event handlers (Handler)
unbind(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter])
Unregister filter
Parameters callback – callable of subclass of AbstractFilter

158 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

resolve(event_handler, *custom_filters, **full_config) → List[Union[Callable,

aiogram.dispatcher.filters.filters.AbstractFilter]]
Resolve filters to filters-set
Parameters
• event_handler –
• custom_filters –
• full_config –
Returns

Builtin filters

aiogram has some builtin filters. Here you can see all of them:

Command

class aiogram.dispatcher.filters.Command(commands: Union[Iterable, str], prefixes:

Union[Iterable, str] = '/', ignore_case: bool
= True, ignore_mention: bool = False, ig-
nore_caption: bool = True)
Bases: aiogram.dispatcher.filters.filters.Filter
You can handle commands by using this filter.
If filter is successful processed the Command.CommandObj will be passed to the handler arguments.
By default this filter is registered for messages and edited messages handlers.
Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:

@dp.message_handler(commands=['myCommand'])
@dp.message_handler(Command(['myCommand']))
@dp.message_handler(commands=['myCommand'], commands_prefix='!/')

Parameters
• commands – Command or list of commands always without leading slashes (prefix)
• prefixes – Allowed commands prefix. By default is slash. If you change the default
behavior pass the list of prefixes to this argument.
• ignore_case – Ignore case of the command
• ignore_mention – Ignore mention in command (By default this filter pass only the
commands addressed to current bot)
• ignore_caption – Ignore caption from message (in message types like photo, video,
audio, etc) By default is True. If you want check commands in captions, you also should set
required content_types.
Examples:

4.5. Dispatcher 159

aiogram Documentation, Release 2.11.2

@dp.message_handler(commands=['myCommand'], commands_ignore_
˓→caption=False, content_types=ContentType.ANY)

@dp.message_handler(Command(['myCommand'], ignore_caption=False),
˓→content_types=[ContentType.TEXT, ContentType.DOCUMENT])

classmethod validate(full_config: Dict[str, Any]) → Optional[Dict[str, Any]]

Validator for filters factory
From filters factory this filter can be registered with arguments:
• command
• commands_prefix (will be passed as prefixes)
• commands_ignore_mention (will be passed as ignore_mention)
• commands_ignore_caption (will be passed as ignore_caption)

Parameters full_config –
Returns config or empty dict

async check(message: aiogram.types.message.Message)

Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns
class CommandObj(prefix: str = '/', command: str = '', mention: str = None, args: str = None)
Bases: object
Instance of this object is always has command and it prefix.
Can be passed as keyword argument command to the handler
Instance of this object is always has command and it prefix.
Can be passed as keyword argument command to the handler
prefix: str = '/'
Command without prefix and mention
command: str = ''
Mention (if available)
mention: str = None
Command argument
args: str = None
property mentioned
This command has mention?
Returns
property text
Generate original text from object
Returns

160 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

CommandStart

class aiogram.dispatcher.filters.CommandStart(deep_link: Optional[Union[str, Pat-

tern[str]]] = None, encoded: bool =
False)
Bases: aiogram.dispatcher.filters.builtin.Command
This filter based on Command filter but can handle only /start command.
Also this filter can handle deep-linking arguments.
Example:

@dp.message_handler(CommandStart(re.compile(r'ref-([\d]+)')))

Parameters
• deep_link – string or compiled regular expression (by re.compile(...)).
• encoded – set True if you’re waiting for encoded payload (default - False).

async check(message: aiogram.types.message.Message)

If deep-linking is passed to the filter result of the matching will be passed as deep_link to the handler
Parameters message –
Returns

CommandHelp

class aiogram.dispatcher.filters.CommandHelp
Bases: aiogram.dispatcher.filters.builtin.Command
This filter based on Command filter but can handle only /help command.
Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:

@dp.message_handler(commands=['myCommand'])
@dp.message_handler(Command(['myCommand']))
@dp.message_handler(commands=['myCommand'], commands_prefix='!/')

Parameters
• commands – Command or list of commands always without leading slashes (prefix)
• prefixes – Allowed commands prefix. By default is slash. If you change the default
behavior pass the list of prefixes to this argument.
• ignore_case – Ignore case of the command
• ignore_mention – Ignore mention in command (By default this filter pass only the
commands addressed to current bot)
• ignore_caption – Ignore caption from message (in message types like photo, video,
audio, etc) By default is True. If you want check commands in captions, you also should set
required content_types.
Examples:

4.5. Dispatcher 161

aiogram Documentation, Release 2.11.2

@dp.message_handler(commands=['myCommand'], commands_ignore_
˓→caption=False, content_types=ContentType.ANY)

@dp.message_handler(Command(['myCommand'], ignore_caption=False),
˓→content_types=[ContentType.TEXT, ContentType.DOCUMENT])

CommandSettings

class aiogram.dispatcher.filters.CommandSettings
Bases: aiogram.dispatcher.filters.builtin.Command
This filter based on Command filter but can handle only /settings command.
Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:

@dp.message_handler(commands=['myCommand'])
@dp.message_handler(Command(['myCommand']))
@dp.message_handler(commands=['myCommand'], commands_prefix='!/')

Parameters
• commands – Command or list of commands always without leading slashes (prefix)
• prefixes – Allowed commands prefix. By default is slash. If you change the default
behavior pass the list of prefixes to this argument.
• ignore_case – Ignore case of the command
• ignore_mention – Ignore mention in command (By default this filter pass only the
commands addressed to current bot)
• ignore_caption – Ignore caption from message (in message types like photo, video,
audio, etc) By default is True. If you want check commands in captions, you also should set
required content_types.
Examples:

@dp.message_handler(commands=['myCommand'], commands_ignore_
˓→caption=False, content_types=ContentType.ANY)

@dp.message_handler(Command(['myCommand'], ignore_caption=False),
˓→content_types=[ContentType.TEXT, ContentType.DOCUMENT])

CommandPrivacy

class aiogram.dispatcher.filters.CommandPrivacy
Bases: aiogram.dispatcher.filters.builtin.Command
This filter based on Command filter but can handle only /privacy command.
Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:

@dp.message_handler(commands=['myCommand'])
@dp.message_handler(Command(['myCommand']))
@dp.message_handler(commands=['myCommand'], commands_prefix='!/')

162 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Parameters
• commands – Command or list of commands always without leading slashes (prefix)
• prefixes – Allowed commands prefix. By default is slash. If you change the default
behavior pass the list of prefixes to this argument.
• ignore_case – Ignore case of the command
• ignore_mention – Ignore mention in command (By default this filter pass only the
commands addressed to current bot)
• ignore_caption – Ignore caption from message (in message types like photo, video,
audio, etc) By default is True. If you want check commands in captions, you also should set
required content_types.
Examples:

@dp.message_handler(commands=['myCommand'], commands_ignore_
˓→caption=False, content_types=ContentType.ANY)

@dp.message_handler(Command(['myCommand'], ignore_caption=False),
˓→content_types=[ContentType.TEXT, ContentType.DOCUMENT])

Text

class aiogram.dispatcher.filters.Text(equals: Optional[Union[str, babel.support.LazyProxy,

Iterable[Union[str, babel.support.LazyProxy]]]]
= None, contains: Optional[Union[str, ba-
bel.support.LazyProxy, Iterable[Union[str, ba-
bel.support.LazyProxy]]]] = None, startswith:
Optional[Union[str, babel.support.LazyProxy, It-
erable[Union[str, babel.support.LazyProxy]]]]
= None, endswith: Optional[Union[str, ba-
bel.support.LazyProxy, Iterable[Union[str,
babel.support.LazyProxy]]]] = None, ig-
nore_case=False)
Bases: aiogram.dispatcher.filters.filters.Filter
Simple text filter
Check text for one of pattern. Only one mode can be used in one filter. In every pattern, a single string is treated
as a list with 1 element.
Parameters
• equals – True if object’s text in the list
• contains – True if object’s text contains all strings from the list
• startswith – True if object’s text starts with any of strings from the list
• endswith – True if object’s text ends with any of strings from the list
• ignore_case – case insensitive
classmethod validate(full_config: Dict[str, Any])
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config

4.5. Dispatcher 163

aiogram Documentation, Release 2.11.2

async check(obj: Union[aiogram.types.message.Message, aiogram.types.callback_query.CallbackQuery,

aiogram.types.inline_query.InlineQuery, aiogram.types.poll.Poll])
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

HashTag

class aiogram.dispatcher.filters.HashTag(hashtags=None, cashtags=None)

Bases: aiogram.dispatcher.filters.filters.Filter
Filter for hashtag’s and cashtag’s
classmethod validate(full_config: Dict[str, Any])
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config
async check(message: aiogram.types.message.Message)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

Regexp

class aiogram.dispatcher.filters.Regexp(regexp)
Bases: aiogram.dispatcher.filters.filters.Filter
Regexp filter for messages and callback query
classmethod validate(full_config: Dict[str, Any])
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config
async check(obj: Union[aiogram.types.message.Message, aiogram.types.callback_query.CallbackQuery,
aiogram.types.inline_query.InlineQuery, aiogram.types.poll.Poll])
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

164 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

RegexpCommandsFilter

class aiogram.dispatcher.filters.RegexpCommandsFilter(regexp_commands)
Bases: aiogram.dispatcher.filters.filters.BoundFilter
Check commands by regexp in message
async check(message)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

ContentTypeFilter

class aiogram.dispatcher.filters.ContentTypeFilter(content_types)
Bases: aiogram.dispatcher.filters.filters.BoundFilter
Check message content type
async check(message)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

IsSenderContact

class aiogram.dispatcher.filters.IsSenderContact(is_sender_contact: bool)

Bases: aiogram.dispatcher.filters.filters.BoundFilter
Filter check that the contact matches the sender
is_sender_contact=True - contact matches the sender is_sender_contact=False - result will be inverted
async check(message: aiogram.types.message.Message) → bool
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

4.5. Dispatcher 165

aiogram Documentation, Release 2.11.2

StateFilter

class aiogram.dispatcher.filters.StateFilter(dispatcher, state)

Bases: aiogram.dispatcher.filters.filters.BoundFilter
Check user state
async check(obj)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

ExceptionsFilter

class aiogram.dispatcher.filters.ExceptionsFilter(exception)
Bases: aiogram.dispatcher.filters.filters.BoundFilter
Filter for exceptions
async check(update, exception)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

IDFilter

class aiogram.dispatcher.filters.builtin.IDFilter(user_id: Op-

tional[Union[Iterable[Union[int,
str]], str, int]] = None, chat_id: Op-
tional[Union[Iterable[Union[int,
str]], str, int]] = None)
Bases: aiogram.dispatcher.filters.filters.Filter
Parameters
• user_id –
• chat_id –
classmethod validate(full_config: Dict[str, Any]) → Optional[Dict[str, Any]]
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config
async check(obj: Union[aiogram.types.message.Message, aiogram.types.callback_query.CallbackQuery,
aiogram.types.inline_query.InlineQuery])
Will be called when filters checks.
This method must be overridden.

166 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Parameters args –
Returns

AdminFilter

class aiogram.dispatcher.filters.AdminFilter(is_chat_admin: Op-

tional[Union[Iterable[Union[int, str]],
str, int, bool]] = None)
Bases: aiogram.dispatcher.filters.filters.Filter
Checks if user is admin in a chat. If is_chat_admin is not set, the filter will check in the current chat (correct
only for messages). is_chat_admin is required for InlineQuery.
classmethod validate(full_config: Dict[str, Any]) → Optional[Dict[str, Any]]
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config
async check(obj: Union[aiogram.types.message.Message, aiogram.types.callback_query.CallbackQuery,
aiogram.types.inline_query.InlineQuery]) → bool
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

IsReplyFilter

class aiogram.dispatcher.filters.IsReplyFilter(is_reply)
Bases: aiogram.dispatcher.filters.filters.BoundFilter
Check if message is replied and send reply message to handler
async check(msg: aiogram.types.message.Message)
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

ForwardedMessageFilter

class aiogram.dispatcher.filters.ForwardedMessageFilter(is_forwarded: bool)

Bases: aiogram.dispatcher.filters.filters.BoundFilter
async check(message: aiogram.types.message.Message)
Will be called when filters checks.
This method must be overridden.
Parameters args –

4.5. Dispatcher 167

aiogram Documentation, Release 2.11.2

Returns

ChatTypeFilter

class aiogram.dispatcher.filters.ChatTypeFilter(chat_type: Con-

tainer[aiogram.types.chat.ChatType])
Bases: aiogram.dispatcher.filters.filters.BoundFilter
async check(obj: Union[aiogram.types.message.Message, aiogram.types.callback_query.CallbackQuery])
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

Making own filters (Custom filters)

Own filter can be:

• any callable object
• any async function
• any anonymous function (Example: lambda msg: msg.text == 'spam')
• Subclass of AbstractFilter, Filter or BoundFilter

AbstractFilter

class aiogram.dispatcher.filters.AbstractFilter
Bases: abc.ABC
Abstract class for custom filters.
abstract classmethod validate(full_config: Dict[str, Any]) → Optional[Dict[str, Any]]
Validate and parse config.
This method will be called by the filters factory when you bind this filter. Must be overridden.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config
abstract async check(*args) → bool
Will be called when filters checks.
This method must be overridden.
Parameters args –
Returns

168 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Filter

class aiogram.dispatcher.filters.Filter
Bases: aiogram.dispatcher.filters.filters.AbstractFilter
You can make subclasses of that class for custom filters.
Method check must be overridden
classmethod validate(full_config: Dict[str, Any]) → Optional[Dict[str, Any]]
Here method validate is optional. If you need to use filter from filters factory you need to override this
method.
Parameters full_config – dict with arguments passed to handler registrar
Returns Current filter config

BoundFilter

class aiogram.dispatcher.filters.BoundFilter
Bases: aiogram.dispatcher.filters.filters.Filter
To easily create your own filters with one parameter, you can inherit from this filter.
You need to implement __init__ method with single argument related with key attribute and check method
where you need to implement filter logic.
key = None
Unique name of the filter argument. You need to override this attribute.
required = False
If True this filter will be added to the all of the registered handlers
default = None
Default value for configure required filters
classmethod validate(full_config: Dict[str, Any]) → Dict[str, Any]
If cls.key is not None and that is in config returns config with that argument.
Parameters full_config –
Returns

class ChatIdFilter(BoundFilter):
key = 'chat_id'

def __init__(self, chat_id: typing.Union[typing.Iterable, int]):

if isinstance(chat_id, int):
chat_id = [chat_id]
self.chat_id = chat_id

def check(self, message: types.Message) -> bool:

return message.chat.id in self.chat_id

dp.filters_factory.bind(ChatIdFilter, event_handlers=[dp.message_handlers])

4.5. Dispatcher 169

aiogram Documentation, Release 2.11.2

4.5.2 Finite state machine

Storage

Coming soon. . .

Available storage’s

Coming soon. . .

Memory storage

class aiogram.contrib.fsm_storage.memory.MemoryStorage
Bases: aiogram.dispatcher.storage.BaseStorage
In-memory based states storage.
This type of storage is not recommended for usage in bots, because you will lost all states after restarting.

Redis storage

class aiogram.contrib.fsm_storage.redis.RedisStorage(host='localhost', port=6379,

db=None, password=None,
ssl=None, loop=None,
**kwargs)
Bases: aiogram.dispatcher.storage.BaseStorage
Simple Redis-base storage for FSM.
Usage:

storage = RedisStorage('localhost', 6379, db=5)

dp = Dispatcher(bot, storage=storage)

And need to close Redis connection when shutdown

await dp.storage.close()
await dp.storage.wait_closed()

Mongo storage

class aiogram.contrib.fsm_storage.mongo.MongoStorage(host='localhost', port=27017,

db_name='aiogram_fsm',
uri=None, username=None,
password=None, index=True,
**kwargs)
Bases: aiogram.dispatcher.storage.BaseStorage
Mongo-based storage for FSM.
Usage:

170 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

storage = MongoStorage(host='localhost', port=27017, db_name='aiogram_fsm')

dp = Dispatcher(bot, storage=storage)

And need to close Mongo client connections when shutdown

await dp.storage.close()
await dp.storage.wait_closed()

Rethink DB storage

class aiogram.contrib.fsm_storage.rethinkdb.RethinkDBStorage(host: str = 'local-

host', port: int =
28015, db: str =
'aiogram', table:
str = 'aiogram',
auth_key: Op-
tional[str] = None,
user: Optional[str]
= None, password:
Optional[str] =
None, timeout:
int = 20, ssl:
Optional[dict] =
None, loop: Op-
tional[asyncio.events.AbstractEventLoop]
= None)
Bases: aiogram.dispatcher.storage.BaseStorage
RethinkDB-based storage for FSM.
Usage:

storage = RethinkDBStorage(db='aiogram', table='aiogram', user='aiogram',

˓→password='aiogram_secret')

dispatcher = Dispatcher(bot, storage=storage)

And need to close connection when shutdown

await storage.close()
await storage.wait_closed()

Making own storage’s

Coming soon. . .

4.5. Dispatcher 171

aiogram Documentation, Release 2.11.2

States

Coming soon. . .

State utils

Coming soon. . .

State

Coming soon. . .

States group

Coming soon. . .

4.5.3 Middleware

Bases

Coming soon. . .

Making own middleware’s

Coming soon. . .

Available middleware’s

Coming soon. . .

4.5.4 Webhook

Coming soon. . .

Bases

Coming soon. . .

172 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Security

Coming soon. . .

Making requests when getting updates

Coming soon. . .

4.5.5 Basics

Coming soon. . .

4.5.6 Available handlers

Coming soon. . .

Handler class

Coming soon. . .

4.5.7 Features

Coming soon. . .

4.5.8 Dispatcher class

class aiogram.Dispatcher(bot, loop=None, storage: Optional[aiogram.dispatcher.storage.BaseStorage]

= None, run_tasks_by_default: bool = False, throttling_rate_limit=0.1,
no_throttle_error=False, filters_factory=None)
Bases: aiogram.utils.mixins.DataMixin, aiogram.utils.mixins.
ContextInstanceMixin
Simple Updates dispatcher
It will process incoming updates: messages, edited messages, channel posts, edited channel posts, inline queries,
chosen inline results, callback queries, shipping queries, pre-checkout queries.
async skip_updates()
You can skip old incoming updates from queue. This method is not recommended to use if you use
payments or you bot has high-load.
Returns None
async process_updates(updates, fast: Optional[bool] = True)
Process list of updates
Parameters
• updates –
• fast –
Returns

4.5. Dispatcher 173

aiogram Documentation, Release 2.11.2

async process_update(update: aiogram.types.update.Update)

Process single update object
Parameters update –
Returns
async reset_webhook(check=True) → bool
Reset webhook
Parameters check – check before deleting
Returns
async start_polling(timeout=20, relax=0.1, limit=None, reset_webhook=None, fast: Op-
tional[bool] = True, error_sleep: int = 5)
Start long-polling
Parameters
• timeout –
• relax –
• limit –
• reset_webhook –
• fast –
Returns
stop_polling()
Break long-polling process.
Returns
async wait_closed()
Wait for the long-polling to close
Returns
is_polling()
Check if polling is enabled
Returns
register_message_handler(callback, *custom_filters, commands=None, regexp=None, con-
tent_types=None, state=None, run_task=None, **kwargs)
Register handler for message

# This handler works only if state is None (by default).

dp.register_message_handler(cmd_start, commands=['start', 'about'])
dp.register_message_handler(entry_point, commands=['setup'])

# This handler works only if current state is "first_step"

dp.register_message_handler(step_handler_1, state="first_step")

# If you want to handle all states by one handler, use `state="*"`.

dp.register_message_handler(cancel_handler, commands=['cancel'], state="*")
dp.register_message_handler(cancel_handler, lambda msg: msg.text.lower() ==
˓→'cancel', state="*")

Parameters

174 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• callback –
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• custom_filters – list of custom filters
• kwargs –
• state –
Returns decorated function

message_handler(*custom_filters, commands=None, regexp=None, content_types=None,

state=None, run_task=None, **kwargs)
Decorator for message handler
Examples:
Simple commands handler:

@dp.message_handler(commands=['start', 'welcome', 'about'])

async def cmd_handler(message: types.Message):

Filter messages by regular expression:

@dp.message_handler(regexp='^[a-z]+-[0-9]+')
async def msg_handler(message: types.Message):

Filter messages by command regular expression:

@dp.message_handler(filters.RegexpCommandsFilter(regexp_commands=['item_([0-
˓→9]*)']))

async def send_welcome(message: types.Message):

Filter by content type:

@dp.message_handler(content_types=ContentType.PHOTO | ContentType.DOCUMENT)
async def audio_handler(message: types.Message):

Filter by custom function:

@dp.message_handler(lambda message: message.text and 'hello' in message.text.

˓→lower())

async def text_handler(message: types.Message):

Use multiple filters:

@dp.message_handler(commands=['command'], content_types=ContentType.TEXT)
async def text_handler(message: types.Message):

Register multiple filters set for one handler:

@dp.message_handler(commands=['command'])
@dp.message_handler(lambda message: demojize(message.text) == ':new_moon_with_
˓→face:')

async def text_handler(message: types.Message):

4.5. Dispatcher 175

aiogram Documentation, Release 2.11.2

This handler will be called if the message starts with ‘/command’ OR is some emoji
By default content_type is ContentType.TEXT
Parameters
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• custom_filters – list of custom filters
• kwargs –
• state –
• run_task – run callback in task (no wait results)
Returns decorated function
register_edited_message_handler(callback, *custom_filters, commands=None, reg-
exp=None, content_types=None, state=None,
run_task=None, **kwargs)
Register handler for edited message
Parameters
• callback –
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• state –
• custom_filters – list of custom filters
• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function
edited_message_handler(*custom_filters, commands=None, regexp=None, content_types=None,
state=None, run_task=None, **kwargs)
Decorator for edited message handler
You can use combination of different handlers

@dp.message_handler()
@dp.edited_message_handler()
async def msg_handler(message: types.Message):

Parameters
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• state –
• custom_filters – list of custom filters

176 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• run_task – run callback in task (no wait results)

• kwargs –
Returns decorated function

register_channel_post_handler(callback, *custom_filters, commands=None, regexp=None,

content_types=None, state=None, run_task=None,
**kwargs)
Register handler for channel post
Parameters
• callback –
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• state –
• custom_filters – list of custom filters
• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function
channel_post_handler(*custom_filters, commands=None, regexp=None, content_types=None,
state=None, run_task=None, **kwargs)
Decorator for channel post handler
Parameters
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• state –
• custom_filters – list of custom filters
• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function
register_edited_channel_post_handler(callback, *custom_filters, commands=None,
regexp=None, content_types=None, state=None,
run_task=None, **kwargs)
Register handler for edited channel post
Parameters
• callback –
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• state –

4.5. Dispatcher 177

aiogram Documentation, Release 2.11.2

• custom_filters – list of custom filters

• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function
edited_channel_post_handler(*custom_filters, commands=None, regexp=None, con-
tent_types=None, state=None, run_task=None, **kwargs)
Decorator for edited channel post handler
Parameters
• commands – list of commands
• regexp – REGEXP
• content_types – List of content types.
• custom_filters – list of custom filters
• state –
• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function
register_inline_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)
Register handler for inline query
Example:

dp.register_inline_handler(some_inline_handler, lambda inline_query: True)

Parameters
• callback –
• custom_filters – list of custom filters
• state –
• run_task – run callback in task (no wait results)
• kwargs –
Returns decorated function

inline_handler(*custom_filters, state=None, run_task=None, **kwargs)

Decorator for inline query handler
Example:

@dp.inline_handler(lambda inline_query: True)

async def some_inline_handler(inline_query: types.InlineQuery)

Parameters
• state –
• custom_filters – list of custom filters
• run_task – run callback in task (no wait results)

178 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• kwargs –
Returns decorated function

register_chosen_inline_handler(callback, *custom_filters, state=None, run_task=None,

**kwargs)
Register handler for chosen inline query
Example:

dp.register_chosen_inline_handler(some_chosen_inline_handler, lambda chosen_

˓→inline_query: True)

Parameters
• callback –
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –
Returns

chosen_inline_handler(*custom_filters, state=None, run_task=None, **kwargs)

Decorator for chosen inline query handler
Example:

@dp.chosen_inline_handler(lambda chosen_inline_query: True)

async def some_chosen_inline_handler(chosen_inline_query: types.
˓→ChosenInlineResult)

Parameters
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –
Returns

register_callback_query_handler(callback, *custom_filters, state=None, run_task=None,

**kwargs)
Register handler for callback query
Example:

dp.register_callback_query_handler(some_callback_handler, lambda callback_

˓→query: True)

Parameters
• callback –
• state –

4.5. Dispatcher 179

aiogram Documentation, Release 2.11.2

• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

callback_query_handler(*custom_filters, state=None, run_task=None, **kwargs)

Decorator for callback query handler
Example:

@dp.callback_query_handler(lambda callback_query: True)

async def some_callback_handler(callback_query: types.CallbackQuery)

Parameters
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

register_shipping_query_handler(callback, *custom_filters, state=None, run_task=None,

**kwargs)
Register handler for shipping query
Example:

dp.register_shipping_query_handler(some_shipping_query_handler, lambda
˓→shipping_query: True)

Parameters
• callback –
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

shipping_query_handler(*custom_filters, state=None, run_task=None, **kwargs)

Decorator for shipping query handler
Example:

@dp.shipping_query_handler(lambda shipping_query: True)

async def some_shipping_query_handler(shipping_query: types.ShippingQuery)

Parameters
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

180 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

register_pre_checkout_query_handler(callback, *custom_filters, state=None,

run_task=None, **kwargs)
Register handler for pre-checkout query
Example:

dp.register_pre_checkout_query_handler(some_pre_checkout_query_handler,
˓→lambda shipping_query: True)

Parameters
• callback –
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

pre_checkout_query_handler(*custom_filters, state=None, run_task=None, **kwargs)

Decorator for pre-checkout query handler
Example:

@dp.pre_checkout_query_handler(lambda shipping_query: True)

async def some_pre_checkout_query_handler(shipping_query: types.ShippingQuery)

Parameters
• state –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

register_poll_handler(callback, *custom_filters, run_task=None, **kwargs)

Register handler for poll
Example:

dp.register_poll_handler(some_poll_handler)

Parameters
• callback –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

poll_handler(*custom_filters, run_task=None, **kwargs)

Decorator for poll handler
Example:

4.5. Dispatcher 181

aiogram Documentation, Release 2.11.2

@dp.poll_handler()
async def some_poll_handler(poll: types.Poll)

Parameters
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

register_poll_answer_handler(callback, *custom_filters, run_task=None, **kwargs)

Register handler for poll_answer
Example:

dp.register_poll_answer_handler(some_poll_answer_handler)

Parameters
• callback –
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

poll_answer_handler(*custom_filters, run_task=None, **kwargs)

Decorator for poll_answer handler
Example:

@dp.poll_answer_handler()
async def some_poll_answer_handler(poll_answer: types.PollAnswer)

Parameters
• custom_filters –
• run_task – run callback in task (no wait results)
• kwargs –

register_errors_handler(callback, *custom_filters, exception=None, run_task=None,

**kwargs)
Register handler for errors
Parameters
• callback –
• exception – you can make handler for specific errors type
• run_task – run callback in task (no wait results)
errors_handler(*custom_filters, exception=None, run_task=None, **kwargs)
Decorator for errors handler
Parameters
• exception – you can make handler for specific errors type

182 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• run_task – run callback in task (no wait results)

Returns
current_state(*, chat: Optional[Union[str, int]] = None, user: Optional[Union[str, int]] = None)
→ aiogram.dispatcher.storage.FSMContext
Get current state for user in chat as context

with dp.current_state(chat=message.chat.id, user=message.user.id) as state:

pass

state = dp.current_state()
state.set_state('my_state')

Parameters
• chat –
• user –
Returns

async throttle(key, *, rate=None, user_id=None, chat_id=None, no_error=None) → bool

Execute throttling manager. Returns True if limit has not exceeded otherwise raises ThrottleError or returns
False
Parameters
• key – key in storage
• rate – limit (by default is equal to default rate limit)
• user_id – user id
• chat_id – chat id
• no_error – return boolean value instead of raising error
Returns bool
async check_key(key, chat_id=None, user_id=None)
Get information about key in bucket
Parameters
• key –
• chat_id –
• user_id –
Returns
async release_key(key, chat_id=None, user_id=None)
Release blocked key
Parameters
• key –
• chat_id –
• user_id –
Returns

4.5. Dispatcher 183

aiogram Documentation, Release 2.11.2

async_task(func)
Execute handler as task and return None. Use this decorator for slow handlers (with timeouts)

@dp.message_handler(commands=['command'])
@dp.async_task
async def cmd_with_timeout(message: types.Message):
await asyncio.sleep(120)
return SendMessage(message.chat.id, 'KABOOM').reply(message)

Parameters func –
Returns

throttled(on_throttled: Optional[Callable] = None, key=None, rate=None, user_id=None,

chat_id=None)
Meta-decorator for throttling. Invokes on_throttled if the handler was throttled.
Example:

async def handler_throttled(message: types.Message, **kwargs):

await message.answer("Throttled!")

@dp.throttled(handler_throttled)
async def some_handler(message: types.Message):
await message.answer("Didn't throttled!")

Parameters
• on_throttled – the callable object that should be either a function or return a coroutine
• key – key in storage
• rate – limit (by default is equal to default rate limit)
• user_id – user id
• chat_id – chat id
Returns decorator

bind_filter(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter],

validator: Optional[Callable] = None, event_handlers: Op-
tional[List[aiogram.dispatcher.handler.Handler]] = None, exclude_event_handlers:
Optional[Iterable[aiogram.dispatcher.handler.Handler]] = None)
Register filter
Parameters
• callback – callable or subclass of AbstractFilter
• validator – custom validator.
• event_handlers – list of instances of Handler
• exclude_event_handlers – list of excluded event handlers (Handler)
unbind_filter(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter])
Unregister filter
Parameters callback – callable of subclass of AbstractFilter
setup_middleware(middleware)
Setup middleware

184 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Parameters middleware –
Returns

4.6 Utils

4.6.1 Auth Widget

Implementation of Telegram site authorization checking mechanism for more information https://core.telegram.org/
widgets/login#checking-authorization
Source: https://gist.github.com/JrooTJunior/887791de7273c9df5277d2b1ecadc839
aiogram.utils.auth_widget.generate_hash(data: dict, token: str) → str
Generate secret hash
Parameters
• data –
• token –
Returns
aiogram.utils.auth_widget.check_token(data: dict, token: str) → bool
Validate auth token
Parameters
• data –
• token –
Returns
aiogram.utils.auth_widget.check_signature(token: str, hash: str, **kwargs) → bool
Generate hexadecimal representation of the HMAC-SHA-256 signature of the data-check-string with the
SHA256 hash of the bot’s token used as a secret key
Parameters
• token –
• hash –
• kwargs – all params received on auth
Returns
aiogram.utils.auth_widget.check_integrity(token: str, data: dict) → bool
Verify the authentication and the integrity of the data received on user’s auth
Parameters
• token – Bot’s token
• data – all data that came on auth
Returns

4.6. Utils 185

aiogram Documentation, Release 2.11.2

4.6.2 Executor

aiogram.utils.executor.start_polling(dispatcher, *, loop=None, skip_updates=False,

reset_webhook=True, on_startup=None,
on_shutdown=None, timeout=20, relax=0.1,
fast=True)
Start bot in long-polling mode
Parameters
• dispatcher –
• loop –
• skip_updates –
• reset_webhook –
• on_startup –
• on_shutdown –
• timeout –
aiogram.utils.executor.set_webhook(dispatcher: aiogram.dispatcher.dispatcher.Dispatcher,
webhook_path: str, *, loop: Op-
tional[asyncio.events.AbstractEventLoop] = None,
skip_updates: bool = None, on_startup: Op-
tional[Callable] = None, on_shutdown: Op-
tional[Callable] = None, check_ip: bool = False,
retry_after: Optional[Union[str, int]] = None,
route_name: str = 'webhook_handler', web_app: Op-
tional[aiohttp.web_app.Application] = None)
Set webhook for bot
Parameters
• dispatcher – Dispatcher
• webhook_path – str
• loop – Optional[asyncio.AbstractEventLoop] (default: None)
• skip_updates – bool (default: None)
• on_startup – Optional[Callable] (default: None)
• on_shutdown – Optional[Callable] (default: None)
• check_ip – bool (default: False)
• retry_after – Optional[Union[str, int]] See https://tools.ietf.org/html/rfc7231#
section-7.1.3 (default: None)
• route_name – str (default: ‘webhook_handler’)
• web_app – Optional[Application] (default: None)
Returns
aiogram.utils.executor.start_webhook(dispatcher, webhook_path, *, loop=None,
skip_updates=None, on_startup=None,
on_shutdown=None, check_ip=False,
retry_after=None, route_name='webhook_handler',
**kwargs)

186 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

Start bot in webhook mode

Parameters
• dispatcher –
• webhook_path –
• loop –
• skip_updates –
• on_startup –
• on_shutdown –
• check_ip –
• route_name –
• kwargs –
Returns
aiogram.utils.executor.start(dispatcher, future, *, loop=None, skip_updates=None,
on_startup=None, on_shutdown=None)
Execute Future.
Parameters
• dispatcher – instance of Dispatcher
• future – future
• loop – instance of AbstractEventLoop
• skip_updates –
• on_startup –
• on_shutdown –
Returns
class aiogram.utils.executor.Executor(dispatcher, skip_updates=None, check_ip=False,
retry_after=None, loop=None)
Main executor class
set_web_app(application: aiohttp.web_app.Application)
Change instance of aiohttp.web.Applicaton
Parameters application –
on_startup(callback: callable, polling=True, webhook=True)
Register a callback for the startup process
Parameters
• callback –
• polling – use with polling
• webhook – use with webhook
on_shutdown(callback: callable, polling=True, webhook=True)
Register a callback for the shutdown process
Parameters
• callback –

4.6. Utils 187

aiogram Documentation, Release 2.11.2

• polling – use with polling

• webhook – use with webhook
set_webhook(webhook_path: Optional[str] = None, request_handler: Any = <class
'aiogram.dispatcher.webhook.WebhookRequestHandler'>, route_name: str = 'web-
hook_handler', web_app: Optional[aiohttp.web_app.Application] = None)
Set webhook for bot
Parameters
• webhook_path – Optional[str] (default: None)
• request_handler – Any (default: WebhookRequestHandler)
• route_name – str Name of webhook handler route (default: ‘webhook_handler’)
• web_app – Optional[Application] (default: None)
Returns
start_webhook(webhook_path=None, request_handler=<class 'aiogram.dispatcher.webhook.WebhookRequestHandler'>,
route_name='webhook_handler', **kwargs)
Start bot in webhook mode
Parameters
• webhook_path –
• request_handler –
• route_name – Name of webhook handler route
• kwargs –
Returns
start_polling(reset_webhook=None, timeout=20, relax=0.1, fast=True)
Start bot in long-polling mode
Parameters
• reset_webhook –
• timeout –
start(future)
Execute Future.
Return the Future’s result, or raise its exception.
Parameters future –
Returns

4.6.3 Exceptions

• TelegramAPIError
– ValidationError
– Throttled
– BadRequest

* MessageError

188 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

· MessageNotModified
· MessageToForwardNotFound
· MessageToDeleteNotFound
· MessageToPinNotFound
· MessageIdentifierNotSpecified
· MessageTextIsEmpty
· MessageCantBeEdited
· MessageCantBeDeleted
· MessageCantBeForwarded
· MessageToEditNotFound
· MessageToReplyNotFound
· ToMuchMessages

* PollError
· PollCantBeStopped
· PollHasAlreadyClosed
· PollsCantBeSentToPrivateChats
· PollSizeError
PollMustHaveMoreOptions
PollCantHaveMoreOptions
PollsOptionsLengthTooLong
PollOptionsMustBeNonEmpty
PollQuestionMustBeNonEmpty
· MessageWithPollNotFound (with MessageError)
· MessageIsNotAPoll (with MessageError)

* ObjectExpectedAsReplyMarkup
* InlineKeyboardExpected
* ChatNotFound
* ChatDescriptionIsNotModified
* InvalidQueryID
* InvalidPeerID
* InvalidHTTPUrlContent
* ButtonURLInvalid
* URLHostIsEmpty
* StartParamInvalid
* ButtonDataInvalid
* FileIsTooBig

4.6. Utils 189

aiogram Documentation, Release 2.11.2

* WrongFileIdentifier
* GroupDeactivated
* BadWebhook
· WebhookRequireHTTPS
· BadWebhookPort
· BadWebhookAddrInfo
· BadWebhookNoAddressAssociatedWithHostname

* NotFound
· MethodNotKnown

* PhotoAsInputFileRequired
* InvalidStickersSet
* NoStickerInRequest
* ChatAdminRequired
* NeedAdministratorRightsInTheChannel
* MethodNotAvailableInPrivateChats
* CantDemoteChatCreator
* CantRestrictSelf
* NotEnoughRightsToRestrict
* PhotoDimensions
* UnavailableMembers
* TypeOfFileMismatch
* WrongRemoteFileIdSpecified
* PaymentProviderInvalid
* CurrencyTotalAmountInvalid
* CantParseUrl
* UnsupportedUrlProtocol
* CantParseEntities
* ResultIdDuplicate
* MethodIsNotAvailable
– ConflictError

* TerminatedByOtherGetUpdates
* CantGetUpdates
– Unauthorized

* BotKicked
* BotBlocked
* UserDeactivated

190 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

* CantInitiateConversation
* CantTalkWithBots
– NetworkError
– RetryAfter
– MigrateToChat
– RestartingTelegram
• AIOGramWarning
– TimeoutWarning
exception aiogram.utils.exceptions.TelegramAPIError(message=None)
exception aiogram.utils.exceptions.AIOGramWarning
exception aiogram.utils.exceptions.TimeoutWarning
exception aiogram.utils.exceptions.FSMStorageWarning
exception aiogram.utils.exceptions.ValidationError(message=None)
exception aiogram.utils.exceptions.BadRequest(message=None)
exception aiogram.utils.exceptions.MessageError(message=None)
exception aiogram.utils.exceptions.MessageNotModified(message=None)
Will be raised when you try to set new text is equals to current text.
exception aiogram.utils.exceptions.MessageToForwardNotFound(message=None)
Will be raised when you try to forward very old or deleted or unknown message.
exception aiogram.utils.exceptions.MessageToDeleteNotFound(message=None)
Will be raised when you try to delete very old or deleted or unknown message.
exception aiogram.utils.exceptions.MessageToPinNotFound(message=None)
Will be raised when you try to pin deleted or unknown message.
exception aiogram.utils.exceptions.MessageToReplyNotFound(message=None)
Will be raised when you try to reply to very old or deleted or unknown message.
exception aiogram.utils.exceptions.MessageIdentifierNotSpecified(message=None)
exception aiogram.utils.exceptions.MessageTextIsEmpty(message=None)
exception aiogram.utils.exceptions.MessageCantBeEdited(message=None)
exception aiogram.utils.exceptions.MessageCantBeDeleted(message=None)
exception aiogram.utils.exceptions.MessageCantBeForwarded(message=None)
exception aiogram.utils.exceptions.MessageToEditNotFound(message=None)
exception aiogram.utils.exceptions.MessageIsTooLong(message=None)
exception aiogram.utils.exceptions.ToMuchMessages(message=None)
Will be raised when you try to send media group with more than 10 items.
exception aiogram.utils.exceptions.ObjectExpectedAsReplyMarkup(message=None)
exception aiogram.utils.exceptions.InlineKeyboardExpected(message=None)
exception aiogram.utils.exceptions.PollError(message=None)
exception aiogram.utils.exceptions.PollCantBeStopped(message=None)

4.6. Utils 191

aiogram Documentation, Release 2.11.2

exception aiogram.utils.exceptions.PollHasAlreadyBeenClosed(message=None)
exception aiogram.utils.exceptions.PollsCantBeSentToPrivateChats(message=None)
exception aiogram.utils.exceptions.PollSizeError(message=None)
exception aiogram.utils.exceptions.PollMustHaveMoreOptions(message=None)
exception aiogram.utils.exceptions.PollCantHaveMoreOptions(message=None)
exception aiogram.utils.exceptions.PollOptionsMustBeNonEmpty(message=None)
exception aiogram.utils.exceptions.PollQuestionMustBeNonEmpty(message=None)
exception aiogram.utils.exceptions.PollOptionsLengthTooLong(message=None)
exception aiogram.utils.exceptions.PollQuestionLengthTooLong(message=None)
exception aiogram.utils.exceptions.PollCanBeRequestedInPrivateChatsOnly(message=None)
exception aiogram.utils.exceptions.MessageWithPollNotFound(message=None)
Will be raised when you try to stop poll with message without poll
exception aiogram.utils.exceptions.MessageIsNotAPoll(message=None)
Will be raised when you try to stop poll with message without poll
exception aiogram.utils.exceptions.ChatNotFound(message=None)
exception aiogram.utils.exceptions.ChatIdIsEmpty(message=None)
exception aiogram.utils.exceptions.InvalidUserId(message=None)
exception aiogram.utils.exceptions.ChatDescriptionIsNotModified(message=None)
exception aiogram.utils.exceptions.InvalidQueryID(message=None)
exception aiogram.utils.exceptions.InvalidPeerID(message=None)
exception aiogram.utils.exceptions.InvalidHTTPUrlContent(message=None)
exception aiogram.utils.exceptions.ButtonURLInvalid(message=None)
exception aiogram.utils.exceptions.URLHostIsEmpty(message=None)
exception aiogram.utils.exceptions.StartParamInvalid(message=None)
exception aiogram.utils.exceptions.ButtonDataInvalid(message=None)
exception aiogram.utils.exceptions.FileIsTooBig(message=None)
exception aiogram.utils.exceptions.WrongFileIdentifier(message=None)
exception aiogram.utils.exceptions.GroupDeactivated(message=None)
exception aiogram.utils.exceptions.PhotoAsInputFileRequired(message=None)
Will be raised when you try to set chat photo from file ID.
exception aiogram.utils.exceptions.InvalidStickersSet(message=None)
exception aiogram.utils.exceptions.NoStickerInRequest(message=None)
exception aiogram.utils.exceptions.ChatAdminRequired(message=None)
exception aiogram.utils.exceptions.NeedAdministratorRightsInTheChannel(message=None)
exception aiogram.utils.exceptions.NotEnoughRightsToPinMessage(message=None)
exception aiogram.utils.exceptions.MethodNotAvailableInPrivateChats(message=None)
exception aiogram.utils.exceptions.CantDemoteChatCreator(message=None)

192 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

exception aiogram.utils.exceptions.CantRestrictSelf(message=None)
exception aiogram.utils.exceptions.NotEnoughRightsToRestrict(message=None)
exception aiogram.utils.exceptions.PhotoDimensions(message=None)
exception aiogram.utils.exceptions.UnavailableMembers(message=None)
exception aiogram.utils.exceptions.TypeOfFileMismatch(message=None)
exception aiogram.utils.exceptions.WrongRemoteFileIdSpecified(message=None)
exception aiogram.utils.exceptions.PaymentProviderInvalid(message=None)
exception aiogram.utils.exceptions.CurrencyTotalAmountInvalid(message=None)
exception aiogram.utils.exceptions.BadWebhook(message=None)
exception aiogram.utils.exceptions.WebhookRequireHTTPS(message=None)
exception aiogram.utils.exceptions.BadWebhookPort(message=None)
exception aiogram.utils.exceptions.BadWebhookAddrInfo(message=None)
exception aiogram.utils.exceptions.BadWebhookNoAddressAssociatedWithHostname(message=None)
exception aiogram.utils.exceptions.CantParseUrl(message=None)
exception aiogram.utils.exceptions.UnsupportedUrlProtocol(message=None)
exception aiogram.utils.exceptions.CantParseEntities(message=None)
exception aiogram.utils.exceptions.ResultIdDuplicate(message=None)
exception aiogram.utils.exceptions.BotDomainInvalid(message=None)
exception aiogram.utils.exceptions.MethodIsNotAvailable(message=None)
exception aiogram.utils.exceptions.NotFound(message=None)
exception aiogram.utils.exceptions.MethodNotKnown(message=None)
exception aiogram.utils.exceptions.ConflictError(message=None)
exception aiogram.utils.exceptions.TerminatedByOtherGetUpdates(message=None)
exception aiogram.utils.exceptions.CantGetUpdates(message=None)
exception aiogram.utils.exceptions.Unauthorized(message=None)
exception aiogram.utils.exceptions.BotKicked(message=None)
exception aiogram.utils.exceptions.BotBlocked(message=None)
exception aiogram.utils.exceptions.UserDeactivated(message=None)
exception aiogram.utils.exceptions.CantInitiateConversation(message=None)
exception aiogram.utils.exceptions.CantTalkWithBots(message=None)
exception aiogram.utils.exceptions.NetworkError(message=None)
exception aiogram.utils.exceptions.RestartingTelegram
exception aiogram.utils.exceptions.RetryAfter(retry_after)
exception aiogram.utils.exceptions.MigrateToChat(chat_id)
exception aiogram.utils.exceptions.Throttled(**kwargs)

4.6. Utils 193

aiogram Documentation, Release 2.11.2

4.6.4 Markdown

aiogram.utils.markdown.quote_html(*content, sep=' ') → str

Quote HTML symbols
All <, >, & and ” symbols that are not a part of a tag or an HTML entity must be replaced with the corresponding
HTML entities (< with &lt; > with &gt; & with &amp and ” with &quot).
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.escape_md(*content, sep=' ') → str
Escape markdown text
E.g. for usernames
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.text(*content, sep=' ')
Join all elements with a separator
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.bold(*content, sep=' ') → str
Make bold text (Markdown)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.hbold(*content, sep=' ') → str
Make bold text (HTML)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.italic(*content, sep=' ') → str
Make italic text (Markdown)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.hitalic(*content, sep=' ') → str
Make italic text (HTML)
Parameters

194 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

• content –
• sep –
Returns
aiogram.utils.markdown.code(*content, sep=' ') → str
Make mono-width text (Markdown)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.hcode(*content, sep=' ') → str
Make mono-width text (HTML)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.pre(*content, sep='\n') → str
Make mono-width text block (Markdown)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.hpre(*content, sep='\n') → str
Make mono-width text block (HTML)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.underline(*content, sep=' ') → str
Make underlined text (Markdown)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.hunderline(*content, sep=' ') → str
Make underlined text (HTML)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.strikethrough(*content, sep=' ') → str
Make strikethrough text (Markdown)
Parameters
• content –

4.6. Utils 195

aiogram Documentation, Release 2.11.2

• sep –
Returns
aiogram.utils.markdown.hstrikethrough(*content, sep=' ') → str
Make strikethrough text (HTML)
Parameters
• content –
• sep –
Returns
aiogram.utils.markdown.link(title: str, url: str) → str
Format URL (Markdown)
Parameters
• title –
• url –
Returns
aiogram.utils.markdown.hlink(title: str, url: str) → str
Format URL (HTML)
Parameters
• title –
• url –
Returns
aiogram.utils.markdown.hide_link(url: str) → str
Hide URL (HTML only) Can be used for adding an image to a text message
Parameters url –
Returns

4.6.5 Helper

Example:

>>> from aiogram.utils.helper import Helper, ListItem, HelperMode, Item

>>> class MyHelper(Helper):
... mode = HelperMode.lowerCamelCase
... FOO_ITEM = ListItem()
... BAR_ITEM = ListItem()
... BAZ_ITEM = ListItem()
... LOREM = Item()
...
>>> print(MyHelper.FOO_ITEM & MyHelper.BAR_ITEM)
<<< ['fooItem', 'barItem']
>>> print(MyHelper.all())
<<< ['barItem', 'bazItem', 'fooItem', 'lorem']

class aiogram.utils.helper.Item(value=None)
Helper item
If a value is not provided, it will be automatically generated based on a variable’s name
class aiogram.utils.helper.ListItem(value=None)
This item is always a list
You can use &, | and + operators for that.

196 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

class aiogram.utils.helper.ItemsList(*seq)
Patch for default list
This class provides +, &, |, +=, &=, |= operators for extending the list

4.6.6 Deprecated

aiogram.utils.deprecated.deprecated(reason, stacklevel=2) → Callable

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted
when the function is used.
Source: https://stackoverflow.com/questions/2536307/decorators-in-the-python-standard-lib-deprecated-specifically
aiogram.utils.deprecated.renamed_argument(old_name: str, new_name: str, until_version:
str, stacklevel: int = 3)
A meta-decorator to mark an argument as deprecated.

@renamed_argument("chat", "chat_id", "3.0") # stacklevel=3 by default

@renamed_argument("user", "user_id", "3.0", stacklevel=4)
def some_function(user_id, chat_id=None):
print(f"user_id={user_id}, chat_id={chat_id}")

some_function(user=123) # prints 'user_id=123, chat_id=None' with warning

some_function(123) # prints 'user_id=123, chat_id=None' without warning
some_function(user_id=123) # prints 'user_id=123, chat_id=None' without warning

Parameters
• old_name –
• new_name –
• until_version – the version in which the argument is scheduled to be removed
• stacklevel – leave it to default if it’s the first decorator used.
Increment with any new decorator used. :return: decorator
class aiogram.utils.deprecated.DeprecatedReadOnlyClassVar(warning_message:
str, new_value_getter:
Callable[[_OwnerCls],
_VT])
DeprecatedReadOnlyClassVar[Owner, ValueType]
Parameters
• warning_message – Warning message when getter gets called
• new_value_getter – Any callable with (owner_class: Type[Owner]) -> Value-
Type signature that will be executed
Usage example:

>>> class MyClass:

... some_attribute: DeprecatedReadOnlyClassVar[MyClass, int] = ...
˓→ DeprecatedReadOnlyClassVar(
... "Warning message.", lambda owner: 15)
...
>>> MyClass.some_attribute # does warning.warn with `Warning message` and
˓→returns 15 in the current case

4.6. Utils 197

aiogram Documentation, Release 2.11.2

4.6.7 Payload

aiogram.utils.payload.generate_payload(exclude=None, **kwargs)
Generate payload
Usage: payload = generate_payload(**locals(), exclude=[‘foo’])
Parameters
• exclude –
• kwargs –
Returns dict
aiogram.utils.payload.prepare_arg(value)
Stringify dicts/lists and convert datetime/timedelta to unix-time
Parameters value –
Returns

4.6.8 Parts

aiogram.utils.parts.split_text(text: str, length: int = 4096) → List[str]

Split long text
Parameters
• text –
• length –
Returns list of parts
Return type typing.List[str]
aiogram.utils.parts.safe_split_text(text: str, length: int = 4096) → List[str]
Split long text
Parameters
• text –
• length –
Returns
aiogram.utils.parts.paginate(data: Iterable, page: int = 0, limit: int = 10) → Iterable
Slice data over pages
Parameters
• data (typing.Iterable) – any iterable object
• page (int) – number of page
• limit (int) – items per page
Returns sliced object
Return type typing.Iterable

198 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

4.6.9 JSON

4.6.10 Emoji

4.6.11 Deep linking

Deep linking
Telegram bots have a deep linking mechanism, that allows for passing additional parameters to the bot on startup. It
could be a command that launches the bot — or an auth token to connect the user’s Telegram account to their account
on some external service.
You can read detailed description in the source: https://core.telegram.org/bots#deep-linking
We have add some utils to get deep links more handy.
Basic link example:

from aiogram.utils.deep_linking import get_start_link

link = await get_start_link('foo') # result: 'https://t.me/MyBot?start=foo'

Encoded link example:

from aiogram.utils.deep_linking import get_start_link, decode_payload

link = await get_start_link('foo', encode=True) # result: 'https://t.me/
˓→MyBot?start=Zm9v'

# and decode it back:

payload = decode_payload('Zm9v') # result: 'foo'

async aiogram.utils.deep_linking.get_start_link(payload: str, encode=False) → str

Use this method to handy get ‘start’ deep link with your payload. If you need to encode payload or pass special
characters - set encode as True
Parameters
• payload – args passed with /start
• encode – encode payload with base64url
Returns link
async aiogram.utils.deep_linking.get_startgroup_link(payload: str, encode=False)
→ str
Use this method to handy get ‘startgroup’ deep link with your payload. If you need to encode payload or pass
special characters - set encode as True
Parameters
• payload – args passed with /start
• encode – encode payload with base64url
Returns link
aiogram.utils.deep_linking.encode_payload(payload: str) → str
Encode payload with URL-safe base64url.
aiogram.utils.deep_linking.decode_payload(payload: str) → str
Decode payload with URL-safe base64url.
aiogram.utils.deep_linking.filter_payload(payload: str) → str
Convert payload to text and search for not allowed symbols.

4.6. Utils 199

 aiogram Documentation, Release 2.11.2

4.7 Examples

4.7.1 Echo bot

Listing 1: echo_bot.py
1 """
2 This is a echo bot.
3 It echoes any incoming text messages.
4 """
5

6 import logging
7

8 from aiogram import Bot, Dispatcher, executor, types

9

10 API_TOKEN = 'BOT TOKEN HERE'

11

12 # Configure logging
13 logging.basicConfig(level=logging.INFO)
14

15 # Initialize bot and dispatcher

16 bot = Bot(token=API_TOKEN)
17 dp = Dispatcher(bot)
18

19

20 @dp.message_handler(commands=['start', 'help'])
21 async def send_welcome(message: types.Message):
22 """
23 This handler will be called when user sends `/start` or `/help` command
24 """
25 await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
26

27

28 @dp.message_handler(regexp='(^cat[s]?$|puss)')
29 async def cats(message: types.Message):
30 with open('data/cats.jpg', 'rb') as photo:
31 '''
32 # Old fashioned way:
33 await bot.send_photo(
34 message.chat.id,
35 photo,
36 caption='Cats are here ',
37 reply_to_message_id=message.message_id,
38 )
39 '''
40

41 await message.reply_photo(photo, caption='Cats are here ')

42

43

44 @dp.message_handler()
45 async def echo(message: types.Message):
46 # old style:
47 # await bot.send_message(message.chat.id, message.text)
48

49 await message.answer(message.text)
50

(continues on next page)

200 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

51

52 if __name__ == '__main__':
53 executor.start_polling(dp, skip_updates=True)

4.7.2 Inline bot

Listing 2: inline_bot.py
1 import hashlib
2 import logging
3

4 from aiogram import Bot, Dispatcher, executor

5 from aiogram.types import InlineQuery, \
6 InputTextMessageContent, InlineQueryResultArticle
7

8 API_TOKEN = 'BOT_TOKEN_HERE'
9

10 logging.basicConfig(level=logging.DEBUG)
11

12 bot = Bot(token=API_TOKEN)
13 dp = Dispatcher(bot)
14

15

16 @dp.inline_handler()
17 async def inline_echo(inline_query: InlineQuery):
18 # id affects both preview and content,
19 # so it has to be unique for each result
20 # (Unique identifier for this result, 1-64 Bytes)
21 # you can set your unique id's
22 # but for example i'll generate it based on text because I know, that
23 # only text will be passed in this example
24 text = inline_query.query or 'echo'
25 input_content = InputTextMessageContent(text)
26 result_id: str = hashlib.md5(text.encode()).hexdigest()
27 item = InlineQueryResultArticle(
28 id=result_id,
29 title=f'Result {text!r}',
30 input_message_content=input_content,
31 )
32 # don't forget to set cache_time=1 for testing (default is 300s or 5m)
33 await bot.answer_inline_query(inline_query.id, results=[item], cache_time=1)
34

35

36 if __name__ == '__main__':
37 executor.start_polling(dp, skip_updates=True)

4.7. Examples 201

 aiogram Documentation, Release 2.11.2

4.7.3 Advanced executor example

Listing 3: advanced_executor_example.py
1 #!/usr/bin/env python3
2 """
3 **This example is outdated**
4 In this example used ArgumentParser for configuring Your bot.
5

6 Provided to start bot with webhook:

7 python advanced_executor_example.py \
8 --token TOKEN_HERE \
9 --host 0.0.0.0 \
10 --port 8084 \
11 --host-name example.com \
12 --webhook-port 443
13

14 Or long polling:
15 python advanced_executor_example.py --token TOKEN_HERE
16

17 So... In this example found small trouble:

18 can't get bot instance in handlers.
19

20

21 If you want to automatic change getting updates method use executor utils (from
˓→aiogram.utils.executor)

22 """
23 # TODO: Move token to environment variables.
24

25 import argparse
26 import logging
27 import ssl
28 import sys
29

30 from aiogram import Bot

31 from aiogram.dispatcher import Dispatcher
32 from aiogram.dispatcher.webhook import *
33 from aiogram.utils.executor import start_polling, start_webhook
34

35 logging.basicConfig(level=logging.INFO)
36

37 # Configure arguments parser.

38 parser = argparse.ArgumentParser(description='Python telegram bot')
39 parser.add_argument('--token', '-t', nargs='?', type=str, default=None, help='Set
˓→working directory')

40 parser.add_argument('--sock', help='UNIX Socket path')

41 parser.add_argument('--host', help='Webserver host')
42 parser.add_argument('--port', type=int, help='Webserver port')
43 parser.add_argument('--cert', help='Path to SSL certificate')
44 parser.add_argument('--pkey', help='Path to SSL private key')
45 parser.add_argument('--host-name', help='Set webhook host name')
46 parser.add_argument('--webhook-port', type=int, help='Port for webhook (default=port)
˓→')

47 parser.add_argument('--webhook-path', default='/webhook', help='Port for webhook

˓→(default=port)')

48

49

(continues on next page)

202 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

50 async def cmd_start(message: types.Message):
51 return SendMessage(message.chat.id, f"Hello, {message.from_user.full_name}!")
52

53

54 def setup_handlers(dispatcher: Dispatcher):

55 # This example has only one messages handler
56 dispatcher.register_message_handler(cmd_start, commands=['start', 'welcome'])
57

58

59 async def on_startup(dispatcher, url=None, cert=None):

60 setup_handlers(dispatcher)
61

62 bot = dispatcher.bot
63

64 # Get current webhook status

65 webhook = await bot.get_webhook_info()
66

67 if url:
68 # If URL is bad
69 if webhook.url != url:
70 # If URL doesnt match with by current remove webhook
71 if not webhook.url:
72 await bot.delete_webhook()
73

74 # Set new URL for webhook

75 if cert:
76 with open(cert, 'rb') as cert_file:
77 await bot.set_webhook(url, certificate=cert_file)
78 else:
79 await bot.set_webhook(url)
80 elif webhook.url:
81 # Otherwise remove webhook.
82 await bot.delete_webhook()
83

84

85 async def on_shutdown(dispatcher):

86 print('Shutdown.')
87

88

89 def main(arguments):
90 args = parser.parse_args(arguments)
91 token = args.token
92 sock = args.sock
93 host = args.host
94 port = args.port
95 cert = args.cert
96 pkey = args.pkey
97 host_name = args.host_name or host
98 webhook_port = args.webhook_port or port
99 webhook_path = args.webhook_path
100

101 # Fi webhook path

102 if not webhook_path.startswith('/'):
103 webhook_path = '/' + webhook_path
104

105 # Generate webhook URL

106 webhook_url = f"https://{host_name}:{webhook_port}{webhook_path}"
(continues on next page)

4.7. Examples 203

 aiogram Documentation, Release 2.11.2

(continued from previous page)

107

108 # Create bot & dispatcher instances.

109 bot = Bot(token)
110 dispatcher = Dispatcher(bot)
111

112 if (sock or host) and host_name:

113 if cert and pkey:
114 ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
115 ssl_context.load_cert_chain(cert, pkey)
116 else:
117 ssl_context = None
118

119 start_webhook(dispatcher, webhook_path,

120 on_startup=functools.partial(on_startup, url=webhook_url,
˓→cert=cert),

121 on_shutdown=on_shutdown,
122 host=host, port=port, path=sock, ssl_context=ssl_context)
123 else:
124 start_polling(dispatcher, on_startup=on_startup, on_shutdown=on_shutdown)
125

126

127 if __name__ == '__main__':

128 argv = sys.argv[1:]
129

130 if not len(argv):

131 parser.print_help()
132 sys.exit(1)
133

134 main(argv)

4.7.4 Proxy and emojize

Listing 4: proxy_and_emojize.py
1 import logging
2

3 import aiohttp
4

5 from aiogram import Bot, types

6 from aiogram.dispatcher import Dispatcher
7 from aiogram.types import ParseMode
8 from aiogram.utils.emoji import emojize
9 from aiogram.utils.executor import start_polling
10 from aiogram.utils.markdown import bold, code, italic, text
11

12 # Configure bot here

13 API_TOKEN = 'BOT_TOKEN_HERE'
14 PROXY_URL = 'http://PROXY_URL' # Or 'socks5://host:port'
15

16 # NOTE: If authentication is required in your proxy then uncomment next line and
˓→change login/password for it

17 # PROXY_AUTH = aiohttp.BasicAuth(login='login', password='password')

18 # And add `proxy_auth=PROXY_AUTH` argument in line 30, like this:
19 # >>> bot = Bot(token=API_TOKEN, proxy=PROXY_URL, proxy_auth=PROXY_AUTH)
20 # Also you can use Socks5 proxy but you need manually install aiohttp_socks package.
(continues on next page)

204 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

21

22 # Get my ip URL
23 GET_IP_URL = 'http://bot.whatismyipaddress.com/'
24

25 logging.basicConfig(level=logging.INFO)
26

27 bot = Bot(token=API_TOKEN, proxy=PROXY_URL)

28

29 # If auth is required:
30 # bot = Bot(token=API_TOKEN, proxy=PROXY_URL, proxy_auth=PROXY_AUTH)
31 dp = Dispatcher(bot)
32

33

34 async def fetch(url, session):

35 async with session.get(url) as response:
36 return await response.text()
37

38

39 @dp.message_handler(commands=['start'])
40 async def cmd_start(message: types.Message):
41 # fetching urls will take some time, so notify user that everything is OK
42 await types.ChatActions.typing()
43

44 content = []
45

46 # Make request (without proxy)

47 async with aiohttp.ClientSession() as session:
48 ip = await fetch(GET_IP_URL, session)
49 content.append(text(':globe_showing_Americas:', bold('IP:'), code(ip)))
50 # This line is formatted to ' *IP:* `YOUR IP`'
51

52 # Make request through bot's proxy

53 ip = await fetch(GET_IP_URL, bot.session)
54 content.append(text(':locked_with_key:', bold('IP:'), code(ip), italic('via proxy
˓→')))

55 # This line is formatted to ' *IP:* `YOUR IP` _via proxy_'

56

57 # Send content
58 await bot.send_message(message.chat.id, emojize(text(*content, sep='\n')), parse_
˓→mode=ParseMode.MARKDOWN)

59

60 # In this example you can see emoji codes: ":globe_showing_Americas:" and

˓→":locked_with_key:"
61 # You can find full emoji cheat sheet at https://www.webpagefx.com/tools/emoji-
˓→cheat-sheet/

62 # For representing emoji codes into real emoji use emoji util (aiogram.utils.
˓→emoji)

63 # (you have to install emoji module)

64

65 # For example emojize('Moon face :new_moon_face:') is transformed to 'Moon face '

66

67

68 if __name__ == '__main__':
69 start_polling(dp, skip_updates=True)

4.7. Examples 205

 aiogram Documentation, Release 2.11.2

4.7.5 Finite state machine example

Listing 5: finite_state_machine_example.py
1 import logging
2

3 import aiogram.utils.markdown as md
4 from aiogram import Bot, Dispatcher, types
5 from aiogram.contrib.fsm_storage.memory import MemoryStorage
6 from aiogram.dispatcher import FSMContext
7 from aiogram.dispatcher.filters import Text
8 from aiogram.dispatcher.filters.state import State, StatesGroup
9 from aiogram.types import ParseMode
10 from aiogram.utils import executor
11

12 logging.basicConfig(level=logging.INFO)
13

14 API_TOKEN = 'BOT TOKEN HERE'

15

16

17 bot = Bot(token=API_TOKEN)
18

19 # For example use simple MemoryStorage for Dispatcher.

20 storage = MemoryStorage()
21 dp = Dispatcher(bot, storage=storage)
22

23

24 # States
25 class Form(StatesGroup):
26 name = State() # Will be represented in storage as 'Form:name'
27 age = State() # Will be represented in storage as 'Form:age'
28 gender = State() # Will be represented in storage as 'Form:gender'
29

30

31 @dp.message_handler(commands='start')
32 async def cmd_start(message: types.Message):
33 """
34 Conversation's entry point
35 """
36 # Set state
37 await Form.name.set()
38

39 await message.reply("Hi there! What's your name?")

40

41

42 # You can use state '*' if you need to handle all states
43 @dp.message_handler(state='*', commands='cancel')
44 @dp.message_handler(Text(equals='cancel', ignore_case=True), state='*')
45 async def cancel_handler(message: types.Message, state: FSMContext):
46 """
47 Allow user to cancel any action
48 """
49 current_state = await state.get_state()
50 if current_state is None:
51 return
52

53 logging.info('Cancelling state %r', current_state)

(continues on next page)

206 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

54 # Cancel state and inform user about it
55 await state.finish()
56 # And remove keyboard (just in case)
57 await message.reply('Cancelled.', reply_markup=types.ReplyKeyboardRemove())
58

59

60 @dp.message_handler(state=Form.name)
61 async def process_name(message: types.Message, state: FSMContext):
62 """
63 Process user name
64 """
65 async with state.proxy() as data:
66 data['name'] = message.text
67

68 await Form.next()
69 await message.reply("How old are you?")
70

71

72 # Check age. Age gotta be digit

73 @dp.message_handler(lambda message: not message.text.isdigit(), state=Form.age)
74 async def process_age_invalid(message: types.Message):
75 """
76 If age is invalid
77 """
78 return await message.reply("Age gotta be a number.\nHow old are you? (digits only)
˓→")

79

80

81 @dp.message_handler(lambda message: message.text.isdigit(), state=Form.age)

82 async def process_age(message: types.Message, state: FSMContext):
83 # Update state and data
84 await Form.next()
85 await state.update_data(age=int(message.text))
86

87 # Configure ReplyKeyboardMarkup
88 markup = types.ReplyKeyboardMarkup(resize_keyboard=True, selective=True)
89 markup.add("Male", "Female")
90 markup.add("Other")
91

92 await message.reply("What is your gender?", reply_markup=markup)

93

94

95 @dp.message_handler(lambda message: message.text not in ["Male", "Female", "Other"],

˓→state=Form.gender)

96 async def process_gender_invalid(message: types.Message):

97 """
98 In this example gender has to be one of: Male, Female, Other.
99 """
100 return await message.reply("Bad gender name. Choose your gender from the keyboard.
˓→")

101

102

103 @dp.message_handler(state=Form.gender)
104 async def process_gender(message: types.Message, state: FSMContext):
105 async with state.proxy() as data:
106 data['gender'] = message.text
107
(continues on next page)

4.7. Examples 207

 aiogram Documentation, Release 2.11.2

(continued from previous page)

108 # Remove keyboard
109 markup = types.ReplyKeyboardRemove()
110

111 # And send message

112 await bot.send_message(
113 message.chat.id,
114 md.text(
115 md.text('Hi! Nice to meet you,', md.bold(data['name'])),
116 md.text('Age:', md.code(data['age'])),
117 md.text('Gender:', data['gender']),
118 sep='\n',
119 ),
120 reply_markup=markup,
121 parse_mode=ParseMode.MARKDOWN,
122 )
123

124 # Finish conversation

125 await state.finish()
126

127

128 if __name__ == '__main__':

129 executor.start_polling(dp, skip_updates=True)

4.7.6 Throttling example

Listing 6: throttling_example.py
1 """
2 Example for throttling manager.
3

4 You can use that for flood controlling.

5 """
6

7 import logging
8

9 from aiogram import Bot, types

10 from aiogram.contrib.fsm_storage.memory import MemoryStorage
11 from aiogram.dispatcher import Dispatcher
12 from aiogram.utils.exceptions import Throttled
13 from aiogram.utils.executor import start_polling
14

15

16 API_TOKEN = 'BOT_TOKEN_HERE'
17

18 logging.basicConfig(level=logging.INFO)
19

20 bot = Bot(token=API_TOKEN)
21

22 # Throttling manager does not work without Leaky Bucket.

23 # You need to use a storage. For example use simple in-memory storage.
24 storage = MemoryStorage()
25 dp = Dispatcher(bot, storage=storage)
26

27

28 @dp.message_handler(commands=['start'])
(continues on next page)

208 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

29 async def send_welcome(message: types.Message):
30 try:
31 # Execute throttling manager with rate-limit equal to 2 seconds for key "start
˓→"

32 await dp.throttle('start', rate=2)

33 except Throttled:
34 # If request is throttled, the `Throttled` exception will be raised
35 await message.reply('Too many requests!')
36 else:
37 # Otherwise do something
38 await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
39

40

41 @dp.message_handler(commands=['hi'])
42 @dp.throttled(lambda msg, loop, *args, **kwargs: loop.create_task(bot.send_
˓→message(msg.from_user.id, "Throttled")),

43 rate=5)
44 # loop is added to the function to run coroutines from it
45 async def say_hi(message: types.Message):
46 await message.answer("Hi")
47

48

49 # the on_throttled object can be either a regular function or coroutine

50 async def hello_throttled(*args, **kwargs):
51 # args will be the same as in the original handler
52 # kwargs will be updated with parameters given to .throttled (rate, key, user_id,
˓→chat_id)

53 print(f"hello_throttled was called with args={args} and kwargs={kwargs}")

54 message = args[0] # as message was the first argument in the original handler
55 await message.answer("Throttled")
56

57

58 @dp.message_handler(commands=['hello'])
59 @dp.throttled(hello_throttled, rate=4)
60 async def say_hello(message: types.Message):
61 await message.answer("Hello!")
62

63

64 @dp.message_handler(commands=['help'])
65 @dp.throttled(rate=5)
66 # nothing will happen if the handler will be throttled
67 async def help_handler(message: types.Message):
68 await message.answer('Help!')
69

70 if __name__ == '__main__':
71 start_polling(dp, skip_updates=True)

4.7. Examples 209

 aiogram Documentation, Release 2.11.2

4.7.7 I18n example

Listing 7: i18n_example.py
1 """
2 Internationalize your bot
3

4 Step 1: extract texts

5 # pybabel extract --input-dirs=. -o locales/mybot.pot
6

7 Some useful options:

8 - Extract texts with pluralization support
9 # -k __:1,2
10 - Add comments for translators, you can use another tag if you want (TR)
11 # --add-comments=NOTE
12 - Disable comments with string location in code
13 # --no-location
14 - Set project name
15 # --project=MySuperBot
16 - Set version
17 # --version=2.2
18

19 Step 2: create *.po files. E.g. create en, ru, uk locales.

20 # pybabel init -i locales/mybot.pot -d locales -D mybot -l en
21 # pybabel init -i locales/mybot.pot -d locales -D mybot -l ru
22 # pybabel init -i locales/mybot.pot -d locales -D mybot -l uk
23

24 Step 3: translate texts located in locales/{language}/LC_MESSAGES/mybot.po

25 To open .po file you can use basic text editor or any PO editor, e.g. https://
˓→poedit.net/

26

27 Step 4: compile translations

28 # pybabel compile -d locales -D mybot
29

30 Step 5: When you change the code of your bot you need to update po & mo files.
31 Step 5.1: regenerate pot file:
32 command from step 1
33 Step 5.2: update po files
34 # pybabel update -d locales -D mybot -i locales/mybot.pot
35 Step 5.3: update your translations
36 location and tools you know from step 3
37 Step 5.4: compile mo files
38 command from step 4
39 """
40

41 from pathlib import Path

42

43 from aiogram import Bot, Dispatcher, executor, types

44 from aiogram.contrib.middlewares.i18n import I18nMiddleware
45

46 TOKEN = 'BOT_TOKEN_HERE'
47 I18N_DOMAIN = 'mybot'
48

49 BASE_DIR = Path(__file__).parent
50 LOCALES_DIR = BASE_DIR / 'locales'
51

52 bot = Bot(TOKEN, parse_mode=types.ParseMode.HTML)

(continues on next page)

210 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

53 dp = Dispatcher(bot)
54

55 # Setup i18n middleware

56 i18n = I18nMiddleware(I18N_DOMAIN, LOCALES_DIR)
57 dp.middleware.setup(i18n)
58

59 # Alias for gettext method

60 _ = i18n.gettext
61

62

63 @dp.message_handler(commands='start')
64 async def cmd_start(message: types.Message):
65 # Simply use `_('message')` instead of `'message'` and never use f-strings for
˓→translatable texts.

66 await message.reply(_('Hello, <b>{user}</b>!').format(user=message.from_user.full_

˓→name))

67

68

69 @dp.message_handler(commands='lang')
70 async def cmd_lang(message: types.Message, locale):
71 # For setting custom lang you have to modify i18n middleware
72 await message.reply(_('Your current language: <i>{language}</i>').
˓→format(language=locale))

73

74 # If you care about pluralization, here's small handler

75 # And also, there's and example of comments for translators. Most translation tools
˓→support them.

76

77 # Alias for gettext method, parser will understand double underscore as plural (aka
˓→ngettext)

78 __ = i18n.gettext
79

80

81 # some likes manager

82 LIKES_STORAGE = {'count': 0}
83

84

85 def get_likes() -> int:

86 return LIKES_STORAGE['count']
87

88

89 def increase_likes() -> int:

90 LIKES_STORAGE['count'] += 1
91 return get_likes()
92

93

94 @dp.message_handler(commands='like')
95 async def cmd_like(message: types.Message, locale):
96 likes = increase_likes()
97

98 # NOTE: This is comment for a translator

99 await message.reply(__('Aiogram has {number} like!', 'Aiogram has {number} likes!
˓→', likes).format(number=likes))

100

101

102 if __name__ == '__main__':

103 executor.start_polling(dp, skip_updates=True)

4.7. Examples 211

 aiogram Documentation, Release 2.11.2

4.7.8 Regexp commands filter example

Listing 8: regexp_commands_filter_example.py
1 from aiogram import Bot, types
2 from aiogram.dispatcher import Dispatcher, filters
3 from aiogram.utils import executor
4

6 bot = Bot(token='BOT_TOKEN_HERE', parse_mode=types.ParseMode.HTML)

7 dp = Dispatcher(bot)
8

10 @dp.message_handler(filters.RegexpCommandsFilter(regexp_commands=['item_([0-9]*)']))
11 async def send_welcome(message: types.Message, regexp_command):
12 await message.reply(f"You have requested an item with id <code>{regexp_command.
˓→group(1)}</code>")

13

14

15 @dp.message_handler(commands='start')
16 async def create_deeplink(message: types.Message):
17 bot_user = await bot.me
18 bot_username = bot_user.username
19 deeplink = f'https://t.me/{bot_username}?start=item_12345'
20 text = (
21 f'Either send a command /item_1234 or follow this link {deeplink} and then
˓→click start\n'

22 'It also can be hidden in a inline button\n\n'

23 'Or just send <code>/start item_123</code>'
24 )
25 await message.reply(text, disable_web_page_preview=True)
26

27

28 if __name__ == '__main__':
29 executor.start_polling(dp, skip_updates=True)

4.7.9 Check user language

Babel is required.

Listing 9: check_user_language.py
1 """
2 Babel is required.
3 """
4

5 import logging
6

7 from aiogram import Bot, Dispatcher, executor, md, types

8

9 API_TOKEN = 'BOT TOKEN HERE'

10

11 logging.basicConfig(level=logging.INFO)
12

13

14 bot = Bot(token=API_TOKEN, parse_mode=types.ParseMode.MARKDOWN)

(continues on next page)

212 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

15 dp = Dispatcher(bot)
16

17

18 @dp.message_handler()
19 async def check_language(message: types.Message):
20 locale = message.from_user.locale
21

22 await message.reply(md.text(
23 md.bold('Info about your language:'),
24 md.text('', md.bold('Code:'), md.code(locale.language)),
25 md.text('', md.bold('Territory:'), md.code(locale.territory or 'Unknown')),
26 md.text('', md.bold('Language name:'), md.code(locale.language_name)),
27 md.text('', md.bold('English language name:'), md.code(locale.english_name)),
28 sep='\n',
29 ))
30

31

32 if __name__ == '__main__':
33 executor.start_polling(dp, skip_updates=True)

4.7.10 Middleware and antiflood

Listing 10: middleware_and_antiflood.py

1 import asyncio
2

3 from aiogram import Bot, Dispatcher, executor, types

4 from aiogram.contrib.fsm_storage.redis import RedisStorage2
5 from aiogram.dispatcher import DEFAULT_RATE_LIMIT
6 from aiogram.dispatcher.handler import CancelHandler, current_handler
7 from aiogram.dispatcher.middlewares import BaseMiddleware
8 from aiogram.utils.exceptions import Throttled
9

10 TOKEN = 'BOT_TOKEN_HERE'
11

12 # In this example Redis storage is used

13 storage = RedisStorage2(db=5)
14

15 bot = Bot(token=TOKEN)
16 dp = Dispatcher(bot, storage=storage)
17

18

19 def rate_limit(limit: int, key=None):

20 """
21 Decorator for configuring rate limit and key in different functions.
22

23 :param limit:
24 :param key:
25 :return:
26 """
27

28 def decorator(func):
29 setattr(func, 'throttling_rate_limit', limit)
30 if key:
31 setattr(func, 'throttling_key', key)
(continues on next page)

4.7. Examples 213

 aiogram Documentation, Release 2.11.2

(continued from previous page)

32 return func
33

34 return decorator
35

36

37 class ThrottlingMiddleware(BaseMiddleware):
38 """
39 Simple middleware
40 """
41

42 def __init__(self, limit=DEFAULT_RATE_LIMIT, key_prefix='antiflood_'):

43 self.rate_limit = limit
44 self.prefix = key_prefix
45 super(ThrottlingMiddleware, self).__init__()
46

47 async def on_process_message(self, message: types.Message, data: dict):

48 """
49 This handler is called when dispatcher receives a message
50

51 :param message:
52 """
53 # Get current handler
54 handler = current_handler.get()
55

56 # Get dispatcher from context

57 dispatcher = Dispatcher.get_current()
58 # If handler was configured, get rate limit and key from handler
59 if handler:
60 limit = getattr(handler, 'throttling_rate_limit', self.rate_limit)
61 key = getattr(handler, 'throttling_key', f"{self.prefix}_{handler.__name__
˓→}")
62 else:
63 limit = self.rate_limit
64 key = f"{self.prefix}_message"
65

66 # Use Dispatcher.throttle method.

67 try:
68 await dispatcher.throttle(key, rate=limit)
69 except Throttled as t:
70 # Execute action
71 await self.message_throttled(message, t)
72

73 # Cancel current handler

74 raise CancelHandler()
75

76 async def message_throttled(self, message: types.Message, throttled: Throttled):

77 """
78 Notify user only on first exceed and notify about unlocking only on last
˓→exceed

79

80 :param message:
81 :param throttled:
82 """
83 handler = current_handler.get()
84 dispatcher = Dispatcher.get_current()
85 if handler:
86 key = getattr(handler, 'throttling_key', f"{self.prefix}_{handler.__name__
˓→ }") (continues on next page)

214 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

87 else:
88 key = f"{self.prefix}_message"
89

90 # Calculate how many time is left till the block ends

91 delta = throttled.rate - throttled.delta
92

93 # Prevent flooding
94 if throttled.exceeded_count <= 2:
95 await message.reply('Too many requests! ')
96

97 # Sleep.
98 await asyncio.sleep(delta)
99

100 # Check lock status

101 thr = await dispatcher.check_key(key)
102

103 # If current message is not last with current key - do not send message
104 if thr.exceeded_count == throttled.exceeded_count:
105 await message.reply('Unlocked.')
106

107

108 @dp.message_handler(commands=['start'])
109 @rate_limit(5, 'start') # this is not required but you can configure throttling
˓→manager for current handler using it

110 async def cmd_test(message: types.Message):

111 # You can use this command every 5 seconds
112 await message.reply('Test passed! You can use this command every 5 seconds.')
113

114

115 if __name__ == '__main__':

116 # Setup middleware
117 dp.middleware.setup(ThrottlingMiddleware())
118

119 # Start long-polling

120 executor.start_polling(dp)

4.7.11 Webhook example

Listing 11: webhook_example.py

1 import logging
2

3 from aiogram import Bot, types

4 from aiogram.contrib.middlewares.logging import LoggingMiddleware
5 from aiogram.dispatcher import Dispatcher
6 from aiogram.dispatcher.webhook import SendMessage
7 from aiogram.utils.executor import start_webhook
8

10 API_TOKEN = 'BOT_TOKEN_HERE'
11

12 # webhook settings
13 WEBHOOK_HOST = 'https://your.domain'
14 WEBHOOK_PATH = '/path/to/api'
15 WEBHOOK_URL = f"{WEBHOOK_HOST}{WEBHOOK_PATH}"
(continues on next page)

4.7. Examples 215

 aiogram Documentation, Release 2.11.2

(continued from previous page)

16

17 # webserver settings
18 WEBAPP_HOST = 'localhost' # or ip
19 WEBAPP_PORT = 3001
20

21 logging.basicConfig(level=logging.INFO)
22

23 bot = Bot(token=API_TOKEN)
24 dp = Dispatcher(bot)
25 dp.middleware.setup(LoggingMiddleware())
26

27

28 @dp.message_handler()
29 async def echo(message: types.Message):
30 # Regular request
31 # await bot.send_message(message.chat.id, message.text)
32

33 # or reply INTO webhook

34 return SendMessage(message.chat.id, message.text)
35

36

37 async def on_startup(dp):

38 await bot.set_webhook(WEBHOOK_URL)
39 # insert code here to run it after start
40

41

42 async def on_shutdown(dp):

43 logging.warning('Shutting down..')
44

45 # insert code here to run it before shutdown

46

47 # Remove webhook (not acceptable in some cases)

48 await bot.delete_webhook()
49

50 # Close DB connection (if used)

51 await dp.storage.close()
52 await dp.storage.wait_closed()
53

54 logging.warning('Bye!')
55

56

57 if __name__ == '__main__':
58 start_webhook(
59 dispatcher=dp,
60 webhook_path=WEBHOOK_PATH,
61 on_startup=on_startup,
62 on_shutdown=on_shutdown,
63 skip_updates=True,
64 host=WEBAPP_HOST,
65 port=WEBAPP_PORT,
66 )

216 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

4.7.12 Webhook example old

Listing 12: webhook_example_2.py

1 """
2 Example outdated
3 """
4

5 import asyncio
6 import ssl
7 import sys
8

9 from aiohttp import web

10

11 import aiogram
12 from aiogram import Bot, types
13 from aiogram.contrib.fsm_storage.memory import MemoryStorage
14 from aiogram.dispatcher import Dispatcher
15 from aiogram.dispatcher.webhook import get_new_configured_app, SendMessage
16 from aiogram.types import ChatType, ParseMode, ContentTypes
17 from aiogram.utils.markdown import hbold, bold, text, link
18

19 TOKEN = 'BOT TOKEN HERE'

20

21 WEBHOOK_HOST = 'example.com' # Domain name or IP addres which your bot is located.

22 WEBHOOK_PORT = 443 # Telegram Bot API allows only for usage next ports: 443, 80, 88
˓→or 8443

23 WEBHOOK_URL_PATH = '/webhook' # Part of URL

24

25 # This options needed if you use self-signed SSL certificate

26 # Instructions: https://core.telegram.org/bots/self-signed
27 WEBHOOK_SSL_CERT = './webhook_cert.pem' # Path to the ssl certificate
28 WEBHOOK_SSL_PRIV = './webhook_pkey.pem' # Path to the ssl private key
29

30 WEBHOOK_URL = f"https://{WEBHOOK_HOST}:{WEBHOOK_PORT}{WEBHOOK_URL_PATH}"
31

32 # Web app settings:

33 # Use LAN address to listen webhooks
34 # User any available port in range from 1024 to 49151 if you're using proxy, or
˓→WEBHOOK_PORT if you're using direct webhook handling

35 WEBAPP_HOST = 'localhost'
36 WEBAPP_PORT = 3001
37

38 BAD_CONTENT = ContentTypes.PHOTO & ContentTypes.DOCUMENT & ContentTypes.STICKER &

˓→ContentTypes.AUDIO

39

40 bot = Bot(TOKEN)
41 storage = MemoryStorage()
42 dp = Dispatcher(bot, storage=storage)
43

44

45 async def cmd_start(message: types.Message):

46 # Yep. aiogram allows to respond into webhook.
47 # https://core.telegram.org/bots/api#making-requests-when-getting-updates
48 return SendMessage(chat_id=message.chat.id, text='Hi from webhook!',
49 reply_to_message_id=message.message_id)
50

(continues on next page)

4.7. Examples 217

 aiogram Documentation, Release 2.11.2

(continued from previous page)

51

52 async def cmd_about(message: types.Message):

53 # In this function markdown utils are userd for formatting message text
54 return SendMessage(message.chat.id, text(
55 bold('Hi! I\'m just a simple telegram bot.'),
56 '',
57 text('I\'m powered by', bold('Python', Version(*sys.version_info[:]))),
58 text('With', link(text('aiogram', aiogram.VERSION), 'https://github.com/
˓→aiogram/aiogram')),

59 sep='\n'
60 ), parse_mode=ParseMode.MARKDOWN)
61

62

63 async def cancel(message: types.Message):

64 # Get current state context
65 state = dp.current_state(chat=message.chat.id, user=message.from_user.id)
66

67 # If current user in any state - cancel it.

68 if await state.get_state() is not None:
69 await state.set_state(state=None)
70 return SendMessage(message.chat.id, 'Current action is canceled.')
71 # Otherwise do nothing
72

73

74 async def unknown(message: types.Message):

75 """
76 Handler for unknown messages.
77 """
78 return SendMessage(message.chat.id,
79 f"I don\'t know what to do with content type `{message.content_
˓→type()}`. Sorry :c")

80

81

82 async def cmd_id(message: types.Message):

83 """
84 Return info about user.
85 """
86 if message.reply_to_message:
87 target = message.reply_to_message.from_user
88 chat = message.chat
89 elif message.forward_from and message.chat.type == ChatType.PRIVATE:
90 target = message.forward_from
91 chat = message.forward_from or message.chat
92 else:
93 target = message.from_user
94 chat = message.chat
95

96 result_msg = [hbold('Info about user:'),

97 f"First name: {target.first_name}"]
98 if target.last_name:
99 result_msg.append(f"Last name: {target.last_name}")
100 if target.username:
101 result_msg.append(f"Username: {target.mention}")
102 result_msg.append(f"User ID: {target.id}")
103

104 result_msg.extend([hbold('Chat:'),
105 f"Type: {chat.type}",
(continues on next page)

218 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

106 f"Chat ID: {chat.id}"])
107 if chat.type != ChatType.PRIVATE:
108 result_msg.append(f"Title: {chat.title}")
109 else:
110 result_msg.append(f"Title: {chat.full_name}")
111 return SendMessage(message.chat.id, '\n'.join(result_msg), reply_to_message_
˓→id=message.message_id,

112 parse_mode=ParseMode.HTML)
113

114

115 async def on_startup(app):

116 # Demonstrate one of the available methods for registering handlers
117 # This command available only in main state (state=None)
118 dp.register_message_handler(cmd_start, commands=['start'])
119

120 # This handler is available in all states at any time.

121 dp.register_message_handler(cmd_about, commands=['help', 'about'], state='*')
122 dp.register_message_handler(unknown, content_types=BAD_CONTENT,
123 func=lambda message: message.chat.type == ChatType.
˓→PRIVATE)

124

125 # You are able to register one function handler for multiple conditions
126 dp.register_message_handler(cancel, commands=['cancel'], state='*')
127 dp.register_message_handler(cancel, func=lambda message: message.text.lower().
˓→strip() in ['cancel'], state='*')

128

129 dp.register_message_handler(cmd_id, commands=['id'], state='*')

130 dp.register_message_handler(cmd_id, func=lambda message: message.forward_from or
131 message.reply_to_message
˓→and

132 message.chat.type ==
˓→ChatType.PRIVATE, state='*')

133

134 # Get current webhook status

135 webhook = await bot.get_webhook_info()
136

137 # If URL is bad

138 if webhook.url != WEBHOOK_URL:
139 # If URL doesnt match current - remove webhook
140 if not webhook.url:
141 await bot.delete_webhook()
142

143 # Set new URL for webhook

144 await bot.set_webhook(WEBHOOK_URL, certificate=open(WEBHOOK_SSL_CERT, 'rb'))
145 # If you want to use free certificate signed by LetsEncrypt you need to set
˓→only URL without sending certificate.

146

147

148 async def on_shutdown(app):

149 """
150 Graceful shutdown. This method is recommended by aiohttp docs.
151 """
152 # Remove webhook.
153 await bot.delete_webhook()
154

155 # Close Redis connection.

156 await dp.storage.close()
(continues on next page)

4.7. Examples 219

 aiogram Documentation, Release 2.11.2

(continued from previous page)

157 await dp.storage.wait_closed()
158

159

160 if __name__ == '__main__':

161 # Get instance of :class:`aiohttp.web.Application` with configured router.
162 app = get_new_configured_app(dispatcher=dp, path=WEBHOOK_URL_PATH)
163

164 # Setup event handlers.

165 app.on_startup.append(on_startup)
166 app.on_shutdown.append(on_shutdown)
167

168 # Generate SSL context

169 context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
170 context.load_cert_chain(WEBHOOK_SSL_CERT, WEBHOOK_SSL_PRIV)
171

172 # Start web-application.

173 web.run_app(app, host=WEBAPP_HOST, port=WEBAPP_PORT, ssl_context=context)
174 # Note:
175 # If you start your bot using nginx or Apache web server, SSL context is not
˓→required.

176 # Otherwise you need to set `ssl_context` parameter.

4.7.13 Payments

Listing 13: payments.py

1 from aiogram import Bot
2 from aiogram import types
3 from aiogram.dispatcher import Dispatcher
4 from aiogram.types.message import ContentTypes
5 from aiogram.utils import executor
6

8 BOT_TOKEN = 'BOT_TOKEN_HERE'
9 PAYMENTS_PROVIDER_TOKEN = '123456789:TEST:1422'
10

11 bot = Bot(BOT_TOKEN)
12 dp = Dispatcher(bot)
13

14 # Setup prices
15 prices = [
16 types.LabeledPrice(label='Working Time Machine', amount=5750),
17 types.LabeledPrice(label='Gift wrapping', amount=500),
18 ]
19

20 # Setup shipping options

21 shipping_options = [
22 types.ShippingOption(id='instant', title='WorldWide Teleporter').add(types.
˓→LabeledPrice('Teleporter', 1000)),

23 types.ShippingOption(id='pickup', title='Local pickup').add(types.LabeledPrice(

˓→'Pickup', 300)),

24 ]
25

26

27 @dp.message_handler(commands=['start'])
(continues on next page)

220 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

28 async def cmd_start(message: types.Message):
29 await bot.send_message(message.chat.id,
30 "Hello, I'm the demo merchant bot."
31 " I can sell you a Time Machine."
32 " Use /buy to order one, /terms for Terms and Conditions")
33

34

35 @dp.message_handler(commands=['terms'])
36 async def cmd_terms(message: types.Message):
37 await bot.send_message(message.chat.id,
38 'Thank you for shopping with our demo bot. We hope you
˓→like your new time machine!\n'

39 '1. If your time machine was not delivered on time, please

˓→rethink your concept of time'

40 ' and try again.\n'

41 '2. If you find that your time machine is not working,
˓→kindly contact our future service'

42 ' workshops on Trappist-1e. They will be accessible

˓→anywhere between'

43 ' May 2075 and November 4000 C.E.\n'

44 '3. If you would like a refund, kindly apply for one
˓→yesterday and we will have sent it'

45 ' to you immediately.')

46

47

48 @dp.message_handler(commands=['buy'])
49 async def cmd_buy(message: types.Message):
50 await bot.send_message(message.chat.id,
51 "Real cards won't work with me, no money will be debited
˓→from your account."

52 " Use this test card number to pay for your Time Machine:
˓→`4242 4242 4242 4242`"

53 "\n\nThis is your demo invoice:", parse_mode='Markdown')

54 await bot.send_invoice(message.chat.id, title='Working Time Machine',
55 description='Want to visit your great-great-great-
˓→grandparents?'

56 ' Make a fortune at the races?'

57 ' Shake hands with Hammurabi and take a stroll
˓→in the Hanging Gardens?'

58 ' Order our Working Time Machine today!',

59 provider_token=PAYMENTS_PROVIDER_TOKEN,
60 currency='usd',
61 photo_url='https://telegra.ph/file/d08ff863531f10bf2ea4b.
˓→jpg',

62 photo_height=512, # !=0/None or picture won't be shown

63 photo_width=512,
64 photo_size=512,
65 is_flexible=True, # True If you need to set up Shipping
˓→Fee

66 prices=prices,
67 start_parameter='time-machine-example',
68 payload='HAPPY FRIDAYS COUPON')
69

70

71 @dp.shipping_query_handler(lambda query: True)

72 async def shipping(shipping_query: types.ShippingQuery):
73 await bot.answer_shipping_query(shipping_query.id, ok=True, shipping_
˓→options=shipping_options, (continues on next page)

4.7. Examples 221

 aiogram Documentation, Release 2.11.2

(continued from previous page)

74 error_message='Oh, seems like our Dog couriers
˓→ are having a lunch right now.'
75 ' Try again later!')
76

77

78 @dp.pre_checkout_query_handler(lambda query: True)

79 async def checkout(pre_checkout_query: types.PreCheckoutQuery):
80 await bot.answer_pre_checkout_query(pre_checkout_query.id, ok=True,
81 error_message="Aliens tried to steal your card
˓→'s CVV,"

82 " but we successfully protected

˓→your credentials,"

83 " try to pay again in a few

˓→minutes, we need a small rest.")

84

85

86 @dp.message_handler(content_types=ContentTypes.SUCCESSFUL_PAYMENT)
87 async def got_payment(message: types.Message):
88 await bot.send_message(message.chat.id,
89 'Hoooooray! Thanks for payment! We will proceed your order
˓→for `{} {}`'

90 ' as fast as possible! Stay in touch.'

91 '\n\nUse /buy again to get a Time Machine for your friend!
˓→'.format(

92 message.successful_payment.total_amount / 100, message.

˓→successful_payment.currency),

93 parse_mode='Markdown')
94

95

96 if __name__ == '__main__':
97 executor.start_polling(dp, skip_updates=True)

4.7.14 Broadcast example

Listing 14: broadcast_example.py

1 import asyncio
2 import logging
3

4 from aiogram import Bot, Dispatcher, types

5 from aiogram.utils import exceptions, executor
6

7 API_TOKEN = 'BOT TOKEN HERE'

8

9 logging.basicConfig(level=logging.INFO)
10 log = logging.getLogger('broadcast')
11

12 bot = Bot(token=API_TOKEN, parse_mode=types.ParseMode.HTML)

13 dp = Dispatcher(bot)
14

15

16 def get_users():
17 """
18 Return users list
19
(continues on next page)

222 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

(continued from previous page)

20 In this example returns some random ID's
21 """
22 yield from (61043901, 78238238, 78378343, 98765431, 12345678)
23

24

25 async def send_message(user_id: int, text: str, disable_notification: bool = False) ->
˓→ bool:

26 """
27 Safe messages sender
28

29 :param user_id:
30 :param text:
31 :param disable_notification:
32 :return:
33 """
34 try:
35 await bot.send_message(user_id, text, disable_notification=disable_
˓→notification)

36 except exceptions.BotBlocked:
37 log.error(f"Target [ID:{user_id}]: blocked by user")
38 except exceptions.ChatNotFound:
39 log.error(f"Target [ID:{user_id}]: invalid user ID")
40 except exceptions.RetryAfter as e:
41 log.error(f"Target [ID:{user_id}]: Flood limit is exceeded. Sleep {e.timeout}
˓→seconds.")

42 await asyncio.sleep(e.timeout)
43 return await send_message(user_id, text) # Recursive call
44 except exceptions.UserDeactivated:
45 log.error(f"Target [ID:{user_id}]: user is deactivated")
46 except exceptions.TelegramAPIError:
47 log.exception(f"Target [ID:{user_id}]: failed")
48 else:
49 log.info(f"Target [ID:{user_id}]: success")
50 return True
51 return False
52

53

54 async def broadcaster() -> int:

55 """
56 Simple broadcaster
57

58 :return: Count of messages

59 """
60 count = 0
61 try:
62 for user_id in get_users():
63 if await send_message(user_id, '<b>Hello!</b>'):
64 count += 1
65 await asyncio.sleep(.05) # 20 messages per second (Limit: 30 messages
˓→per second)

66 finally:
67 log.info(f"{count} messages successful sent.")
68

69 return count
70

71

72 if __name__ == '__main__':
(continues on next page)

4.7. Examples 223

 aiogram Documentation, Release 2.11.2

(continued from previous page)

73 # Execute broadcaster
74 executor.start(dp, broadcaster())

4.7.15 Media group

Listing 15: media_group.py

1 import asyncio
2

3 from aiogram import Bot, Dispatcher, executor, filters, types

4

6 API_TOKEN = 'BOT_TOKEN_HERE'
7

8 bot = Bot(token=API_TOKEN)
9 dp = Dispatcher(bot)
10

11

12 @dp.message_handler(filters.CommandStart())
13 async def send_welcome(message: types.Message):
14 # So... At first I want to send something like this:
15 await message.reply("Do you want to see many pussies? Are you ready?")
16

17 # Wait a little...
18 await asyncio.sleep(1)
19

20 # Good bots should send chat actions...

21 await types.ChatActions.upload_photo()
22

23 # Create media group

24 media = types.MediaGroup()
25

26 # Attach local file

27 media.attach_photo(types.InputFile('data/cat.jpg'), 'Cat!')
28 # More local files and more cats!
29 media.attach_photo(types.InputFile('data/cats.jpg'), 'More cats!')
30

31 # You can also use URL's

32 # For example: get random puss:
33 media.attach_photo('http://lorempixel.com/400/200/cats/', 'Random cat.')
34

35 # And you can also use file ID:

36 # media.attach_photo('<file_id>', 'cat-cat-cat.')
37

38 # Done! Send media group

39 await message.reply_media_group(media=media)
40

41

42 if __name__ == '__main__':
43 executor.start_polling(dp, skip_updates=True)

224 Chapter 4. Contents

 aiogram Documentation, Release 2.11.2

4.7.16 Local server

Listing 16: local_server.py

1 import logging
2

3 from aiogram import Bot, Dispatcher, executor, types

4 from aiogram.bot.api import TelegramAPIServer
5 from aiogram.types import ContentType
6

7 API_TOKEN = 'BOT TOKEN HERE'

8

9 # Configure logging
10 logging.basicConfig(level=logging.INFO)
11

12 # Create private Bot API server endpoints wrapper

13 local_server = TelegramAPIServer.from_base('http://localhost')
14

15 # Initialize bot with using local server

16 bot = Bot(token=API_TOKEN, server=local_server)
17 # ... and dispatcher
18 dp = Dispatcher(bot)
19

20

21 @dp.message_handler(content_types=ContentType.ANY)
22 async def echo(message: types.Message):
23 await message.copy_to(message.chat.id)
24

25

26 if __name__ == '__main__':
27 executor.start_polling(dp, skip_updates=True)

4.8 Contribution

TODO

4.9 Links

TODO

4.8. Contribution 225

aiogram Documentation, Release 2.11.2

226 Chapter 4. Contents

 CHAPTER

FIVE

INDICES AND TABLES

• genindex
• modindex
• search

227
aiogram Documentation, Release 2.11.2

228 Chapter 5. Indices and tables

 PYTHON MODULE INDEX

a
aiogram.bot.api, 57
aiogram.utils.auth_widget, 185
aiogram.utils.deep_linking, 199
aiogram.utils.deprecated, 197
aiogram.utils.emoji, 199
aiogram.utils.exceptions, 188
aiogram.utils.executor, 186
aiogram.utils.helper, 196
aiogram.utils.json, 199
aiogram.utils.markdown, 194
aiogram.utils.parts, 198
aiogram.utils.payload, 198

229
aiogram Documentation, Release 2.11.2

230 Python Module Index

 INDEX

A answer() (aiogram.types.inline_query.InlineQuery
AbstractFilter (class in aiogram.dispatcher.filters), method), 88
168 answer() (aiogram.types.message.Message method),
add() (aiogram.types.inline_keyboard.InlineKeyboardMarkup 126
method), 68 answer_animation()
add() (aiogram.types.reply_keyboard.ReplyKeyboardMarkup (aiogram.types.message.Message method),
method), 72 129
add() (aiogram.types.shipping_option.ShippingOption answer_audio() (aiogram.types.message.Message
method), 124 method), 128
add_sticker_to_set() (aiogram.bot.bot.Bot answer_callback_query() (aiogram.bot.bot.Bot
method), 51 method), 45
AdminFilter (class in aiogram.dispatcher.filters), 167 answer_contact() (aiogram.types.message.Message
aiogram.bot.api method), 136
module, 57 answer_dice() (aiogram.types.message.Message
aiogram.utils.auth_widget method), 138
module, 185 answer_document()
aiogram.utils.deep_linking (aiogram.types.message.Message method),
module, 199 130
aiogram.utils.deprecated answer_inline_query() (aiogram.bot.bot.Bot
module, 197 method), 52
aiogram.utils.emoji answer_location()
module, 199 (aiogram.types.message.Message method),
aiogram.utils.exceptions 134
module, 188 answer_media_group()
aiogram.utils.executor (aiogram.types.message.Message method),
module, 186 134
aiogram.utils.helper answer_photo() (aiogram.types.message.Message
module, 196 method), 127
aiogram.utils.json answer_poll() (aiogram.types.message.Message
module, 199 method), 137
aiogram.utils.markdown answer_pre_checkout_query()
module, 194 (aiogram.bot.bot.Bot method), 55
aiogram.utils.parts answer_shipping_query() (aiogram.bot.bot.Bot
module, 198 method), 54
aiogram.utils.payload answer_sticker() (aiogram.types.message.Message
module, 198 method), 136
AIOGramWarning, 191 answer_venue() (aiogram.types.message.Message
AllowedUpdates (class in aiogram.types.update), method), 135
121 answer_video() (aiogram.types.message.Message
Animation (class in aiogram.types.animation), 89 method), 131
answer() (aiogram.types.callback_query.CallbackQuery answer_video_note()
method), 65 (aiogram.types.message.Message method),

231
aiogram Documentation, Release 2.11.2

133 CantInitiateConversation, 193

answer_voice() (aiogram.types.message.Message CantParseEntities, 193
method), 132 CantParseUrl, 193
api_url() (aiogram.bot.api.TelegramAPIServer CantRestrictSelf, 192
method), 57 CantTalkWithBots, 193
args (aiogram.dispatcher.filters.Command.CommandObj channel_post_handler() (aiogram.Dispatcher
attribute), 160 method), 177
as_json() (aiogram.types.base.TelegramObject Chat (class in aiogram.types.chat), 73
method), 59 ChatActions (class in aiogram.types.chat), 80
async_task() (aiogram.Dispatcher method), 183 ChatAdminRequired, 192
attach() (aiogram.types.input_media.MediaGroup ChatDescriptionIsNotModified, 192
method), 92 ChatIdIsEmpty, 192
attach_many() (aiogram.types.input_media.MediaGroup ChatMember (class in aiogram.types.chat_member),
method), 92 123
attach_photo() (aiogram.types.input_media.MediaGroup ChatMemberStatus (class in
method), 92 aiogram.types.chat_member), 124
attach_video() (aiogram.types.input_media.MediaGroup ChatNotFound, 192
method), 92 ChatPhoto (class in aiogram.types.chat_photo), 124
Audio (class in aiogram.types.audio), 82 ChatType (class in aiogram.types.chat), 79
AuthWidgetData (class in ChatTypeFilter (class in aiogram.dispatcher.filters),
aiogram.types.auth_widget_data), 158 168
check() (aiogram.dispatcher.filters.AbstractFilter
B method), 168
BadRequest, 191 check() (aiogram.dispatcher.filters.AdminFilter
BadWebhook, 193 method), 167
BadWebhookAddrInfo, 193 check() (aiogram.dispatcher.filters.builtin.IDFilter
BadWebhookNoAddressAssociatedWithHostname, method), 166
193 check() (aiogram.dispatcher.filters.ChatTypeFilter
BadWebhookPort, 193 method), 168
BaseBot (class in aiogram.bot.base), 17 check() (aiogram.dispatcher.filters.Command
BaseField (class in aiogram.types.fields), 60 method), 160
bind() (aiogram.dispatcher.filters.FiltersFactory check() (aiogram.dispatcher.filters.CommandStart
method), 158 method), 161
bind_filter() (aiogram.Dispatcher method), 184 check() (aiogram.dispatcher.filters.ContentTypeFilter
bold() (in module aiogram.utils.markdown), 194 method), 165
Bot (class in aiogram.bot.bot), 19 check() (aiogram.dispatcher.filters.ExceptionsFilter
BotBlocked, 193 method), 166
BotDomainInvalid, 193 check() (aiogram.dispatcher.filters.ForwardedMessageFilter
BotKicked, 193 method), 167
BoundFilter (class in aiogram.dispatcher.filters), 169 check() (aiogram.dispatcher.filters.HashTag method),
ButtonDataInvalid, 192 164
ButtonURLInvalid, 192 check() (aiogram.dispatcher.filters.IsReplyFilter
method), 167
C check() (aiogram.dispatcher.filters.IsSenderContact
calc_timeout() (aiogram.types.chat.ChatActions method), 165
class method), 80 check() (aiogram.dispatcher.filters.Regexp method),
callback_query_handler() (aiogram.Dispatcher 164
method), 180 check() (aiogram.dispatcher.filters.RegexpCommandsFilter
CallbackGame (class in method), 165
aiogram.types.callback_game), 71 check() (aiogram.dispatcher.filters.StateFilter
CallbackQuery (class in method), 166
aiogram.types.callback_query), 65 check() (aiogram.dispatcher.filters.Text method), 164
CantDemoteChatCreator, 192 check_integrity() (in module
CantGetUpdates, 193 aiogram.utils.auth_widget), 185

232 Index
 aiogram Documentation, Release 2.11.2

check_key() (aiogram.Dispatcher method), 183 delete_chat_sticker_set()

check_result() (in module aiogram.bot.api), 58 (aiogram.bot.bot.Bot method), 45
check_signature() (in module delete_from_set() (aiogram.types.sticker.Sticker
aiogram.utils.auth_widget), 185 method), 88
check_token() (in module aiogram.bot.api), 58 delete_message() (aiogram.bot.bot.Bot method),
check_token() (in module 49
aiogram.utils.auth_widget), 185 delete_photo() (aiogram.types.chat.Chat method),
chosen_inline_handler() (aiogram.Dispatcher 74
method), 179 delete_reply_markup()
ChosenInlineResult (class in (aiogram.types.message.Message method),
aiogram.types.chosen_inline_result), 122 153
clean() (aiogram.types.base.TelegramObject method), delete_sticker_from_set()
59 (aiogram.bot.bot.Bot method), 52
close() (aiogram.bot.base.BaseBot method), 18 delete_sticker_set() (aiogram.types.chat.Chat
close_bot() (aiogram.bot.bot.Bot method), 21 method), 78
code() (in module aiogram.utils.markdown), 195 delete_webhook() (aiogram.bot.bot.Bot method),
command (aiogram.dispatcher.filters.Command.CommandObj 21
attribute), 160 deprecated() (in module aiogram.utils.deprecated),
Command (class in aiogram.dispatcher.filters), 159 197
Command.CommandObj (class in DeprecatedReadOnlyClassVar (class in
aiogram.dispatcher.filters), 160 aiogram.utils.deprecated), 197
CommandHelp (class in aiogram.dispatcher.filters), 161 deserialize() (aiogram.types.fields.BaseField
CommandPrivacy (class in aiogram.dispatcher.filters), method), 60
162 deserialize() (aiogram.types.fields.DateTimeField
CommandSettings (class in method), 63
aiogram.dispatcher.filters), 162 deserialize() (aiogram.types.fields.Field method),
CommandStart (class in aiogram.dispatcher.filters), 61
161 deserialize() (aiogram.types.fields.ListField
compose_data() (in module aiogram.bot.api), 58 method), 62
ConflictError, 193 deserialize() (aiogram.types.fields.ListOfLists
Contact (class in aiogram.types.contact), 125 method), 62
ContentType (class in aiogram.types.message), 155 deserialize() (aiogram.types.fields.TextField
ContentTypeFilter (class in method), 63
aiogram.dispatcher.filters), 165 Dispatcher (class in aiogram), 173
ContentTypes (class in aiogram.types.message), 156 do() (aiogram.types.chat.Chat method), 79
copy_message() (aiogram.bot.bot.Bot method), 23 Document (class in aiogram.types.document), 82
create() (aiogram.types.force_reply.ForceReply class download() (aiogram.types.mixins.Downloadable
method), 82 method), 63
create_new_sticker_set() (aiogram.bot.bot.Bot download_big() (aiogram.types.chat_photo.ChatPhoto
method), 50 method), 125
CurrencyTotalAmountInvalid, 193 download_file() (aiogram.bot.base.BaseBot
current_state() (aiogram.Dispatcher method), method), 18
183 download_file_by_id() (aiogram.bot.bot.Bot
method), 19
D download_small() (aiogram.types.chat_photo.ChatPhoto
DateTimeField (class in aiogram.types.fields), 62 method), 124
decode_payload() (in module Downloadable (class in aiogram.types.mixins), 63
aiogram.utils.deep_linking), 199
default (aiogram.dispatcher.filters.BoundFilter E
attribute), 169 edit_caption() (aiogram.types.message.Message
delete() (aiogram.types.message.Message method), method), 152
154 edit_live_location()
delete_chat_photo() (aiogram.bot.bot.Bot (aiogram.types.message.Message method),
method), 42 153

Index 233
aiogram Documentation, Release 2.11.2

edit_media() (aiogram.types.message.Message ForceReply (class in aiogram.types.force_reply), 82

method), 152 forward() (aiogram.types.message.Message method),
edit_message_caption() (aiogram.bot.bot.Bot 151
method), 47 forward_message() (aiogram.bot.bot.Bot method),
edit_message_live_location() 22
(aiogram.bot.bot.Bot method), 32 ForwardedMessageFilter (class in
edit_message_media() (aiogram.bot.bot.Bot aiogram.dispatcher.filters), 167
method), 47 from_url() (aiogram.types.input_file.InputFile class
edit_message_reply_markup() method), 115
(aiogram.bot.bot.Bot method), 48 FSMStorageWarning, 191
edit_message_text() (aiogram.bot.bot.Bot full_name() (aiogram.types.user.User property), 69
method), 46
edit_reply_markup() G
(aiogram.types.message.Message method), Game (class in aiogram.types.game), 70
153 GameHighScore (class in
edit_text() (aiogram.types.message.Message aiogram.types.game_high_score), 87
method), 152 generate_hash() (in module
edited_channel_post_handler() aiogram.utils.auth_widget), 185
(aiogram.Dispatcher method), 178 generate_payload() (in module
edited_message_handler() (aiogram.Dispatcher aiogram.utils.payload), 198
method), 176 get_administrators() (aiogram.types.chat.Chat
encode_payload() (in module method), 78
aiogram.utils.deep_linking), 199 get_args() (aiogram.types.message.Message
EncryptedCredentials (class in method), 126
aiogram.types.encrypted_credentials), 64 get_chat() (aiogram.bot.bot.Bot method), 44
EncryptedPassportElement (class in get_chat_administrators()
aiogram.types.encrypted_passport_element), (aiogram.bot.bot.Bot method), 44
70 get_chat_member() (aiogram.bot.bot.Bot method),
errors_handler() (aiogram.Dispatcher method), 44
182 get_chat_members_count() (aiogram.bot.bot.Bot
escape_md() (in module aiogram.utils.markdown), method), 44
194 get_command() (aiogram.types.message.Message
ExceptionsFilter (class in method), 126
aiogram.dispatcher.filters), 166 get_file() (aiogram.bot.bot.Bot method), 38
Executor (class in aiogram.utils.executor), 187 get_file() (aiogram.types.input_file.InputFile
export() (aiogram.types.fields.BaseField method), 61 method), 115
export_chat_invite_link() get_file() (aiogram.types.mixins.Downloadable
(aiogram.bot.bot.Bot method), 41 method), 63
export_invite_link() (aiogram.types.chat.Chat get_filename() (aiogram.types.input_file.InputFile
method), 79 method), 115
get_full_command()
F (aiogram.types.message.Message method),
Field (class in aiogram.types.fields), 61 126
File (class in aiogram.types.file), 71 get_game_high_scores() (aiogram.bot.bot.Bot
file_url() (aiogram.bot.api.TelegramAPIServer method), 57
method), 58 get_me() (aiogram.bot.bot.Bot method), 21
FileIsTooBig, 192 get_member() (aiogram.types.chat.Chat method), 78
Filter (class in aiogram.dispatcher.filters), 169 get_members_count() (aiogram.types.chat.Chat
filter_payload() (in module method), 78
aiogram.utils.deep_linking), 199 get_my_commands() (aiogram.bot.bot.Bot method),
FiltersFactory (class in aiogram.dispatcher.filters), 46
158 get_start_link() (in module
find_location() (aiogram.types.chat.ChatActions aiogram.utils.deep_linking), 199
class method), 81

234 Index
 aiogram Documentation, Release 2.11.2

get_startgroup_link() (in module InlineQueryResultCachedAudio (class in

aiogram.utils.deep_linking), 199 aiogram.types.inline_query_result), 114
get_sticker_set() (aiogram.bot.bot.Bot method), InlineQueryResultCachedDocument (class in
50 aiogram.types.inline_query_result), 111
get_text() (aiogram.types.message_entity.MessageEntity InlineQueryResultCachedGif (class in
method), 66 aiogram.types.inline_query_result), 108
get_updates() (aiogram.bot.bot.Bot method), 20 InlineQueryResultCachedMpeg4Gif (class in
get_url() (aiogram.types.chat.Chat method), 73 aiogram.types.inline_query_result), 109
get_url() (aiogram.types.mixins.Downloadable InlineQueryResultCachedPhoto (class in
method), 64 aiogram.types.inline_query_result), 107
get_user_profile_photos() InlineQueryResultCachedSticker (class in
(aiogram.bot.bot.Bot method), 38 aiogram.types.inline_query_result), 110
get_value() (aiogram.types.fields.BaseField InlineQueryResultCachedVideo (class in
method), 60 aiogram.types.inline_query_result), 112
get_webhook_info() (aiogram.bot.bot.Bot InlineQueryResultCachedVoice (class in
method), 21 aiogram.types.inline_query_result), 113
GroupDeactivated, 192 InlineQueryResultContact (class in
guess_filename() (in module aiogram.bot.api), 58 aiogram.types.inline_query_result), 105
InlineQueryResultDocument (class in
H aiogram.types.inline_query_result), 101
HashTag (class in aiogram.dispatcher.filters), 164 InlineQueryResultGame (class in
hbold() (in module aiogram.utils.markdown), 194 aiogram.types.inline_query_result), 106
hcode() (in module aiogram.utils.markdown), 195 InlineQueryResultGif (class in
hide_link() (in module aiogram.utils.markdown), aiogram.types.inline_query_result), 96
196 InlineQueryResultLocation (class in
hitalic() (in module aiogram.utils.markdown), 194 aiogram.types.inline_query_result), 103
hlink() (in module aiogram.utils.markdown), 196 InlineQueryResultMpeg4Gif (class in
hpre() (in module aiogram.utils.markdown), 195 aiogram.types.inline_query_result), 97
hstrikethrough() (in module InlineQueryResultPhoto (class in
aiogram.utils.markdown), 196 aiogram.types.inline_query_result), 95
html_text() (aiogram.types.message.Message prop- InlineQueryResultVenue (class in
erty), 126 aiogram.types.inline_query_result), 104
hunderline() (in module aiogram.utils.markdown), InlineQueryResultVideo (class in
195 aiogram.types.inline_query_result), 98
InlineQueryResultVoice (class in
I aiogram.types.inline_query_result), 100
IDFilter (class in aiogram.dispatcher.filters.builtin), InputContactMessageContent (class in
166 aiogram.types.input_message_content), 117
inline_handler() (aiogram.Dispatcher method), InputFile (class in aiogram.types.input_file), 115
178 InputLocationMessageContent (class in
InlineKeyboardButton (class in aiogram.types.input_message_content), 118
aiogram.types.inline_keyboard), 69 InputMedia (class in aiogram.types.input_media), 89
InlineKeyboardExpected, 191 InputMediaAnimation (class in
InlineKeyboardMarkup (class in aiogram.types.input_media), 90
aiogram.types.inline_keyboard), 68 InputMediaAudio (class in
InlineQuery (class in aiogram.types.inline_query), aiogram.types.input_media), 91
88 InputMediaDocument (class in
InlineQueryResult (class in aiogram.types.input_media), 90
aiogram.types.inline_query_result), 93 InputMediaPhoto (class in
InlineQueryResultArticle (class in aiogram.types.input_media), 91
aiogram.types.inline_query_result), 94 InputMediaVideo (class in
InlineQueryResultAudio (class in aiogram.types.input_media), 92
aiogram.types.inline_query_result), 99 InputMessageContent (class in
aiogram.types.input_message_content), 117

Index 235
aiogram Documentation, Release 2.11.2

InputTextMessageContent (class in leave() (aiogram.types.chat.Chat method), 78

aiogram.types.input_message_content), 119 leave_chat() (aiogram.bot.bot.Bot method), 43
InputVenueMessageContent (class in link() (aiogram.types.message.Message method), 126
aiogram.types.input_message_content), 120 link() (in module aiogram.utils.markdown), 196
insert() (aiogram.types.inline_keyboard.InlineKeyboardMarkup
ListField (class in aiogram.types.fields), 61
method), 68 ListItem (class in aiogram.utils.helper), 196
insert() (aiogram.types.reply_keyboard.ReplyKeyboardMarkup
ListOfLists (class in aiogram.types.fields), 62
method), 72 locale() (aiogram.types.user.User property), 69
InvalidHTTPUrlContent, 192 Location (class in aiogram.types.location), 89
InvalidPeerID, 192 log_out() (aiogram.bot.bot.Bot method), 21
InvalidQueryID, 192
InvalidStickersSet, 192 M
InvalidUserId, 192 MaskPosition (class in
Invoice (class in aiogram.types.invoice), 157 aiogram.types.mask_position), 157
is_channel() (aiogram.types.chat.ChatType class md_text() (aiogram.types.message.Message prop-
method), 80 erty), 126
is_command() (aiogram.types.message.Message me() (aiogram.bot.bot.Bot property), 19
method), 125 MediaGroup (class in aiogram.types.input_media), 92
is_forward() (aiogram.types.message.Message MemoryStorage (class in
method), 125 aiogram.contrib.fsm_storage.memory), 170
is_group() (aiogram.types.chat.ChatType class mention (aiogram.dispatcher.filters.Command.CommandObj
method), 79 attribute), 160
is_group_or_super_group() mention() (aiogram.types.chat.Chat property), 73
(aiogram.types.chat.ChatType class method), mention() (aiogram.types.user.User property), 69
80 mentioned() (aiogram.dispatcher.filters.Command.CommandObj
is_polling() (aiogram.Dispatcher method), 174 property), 160
is_private() (aiogram.types.chat.ChatType class Message (class in aiogram.types.message), 125
method), 79 message_handler() (aiogram.Dispatcher method),
is_super_group() (aiogram.types.chat.ChatType 175
class method), 80 MessageCantBeDeleted, 191
IsReplyFilter (class in aiogram.dispatcher.filters), MessageCantBeEdited, 191
167 MessageCantBeForwarded, 191
IsSenderContact (class in MessageEntity (class in
aiogram.dispatcher.filters), 165 aiogram.types.message_entity), 66
italic() (in module aiogram.utils.markdown), 194 MessageEntityType (class in
Item (class in aiogram.utils.helper), 196 aiogram.types.message_entity), 67
ItemsList (class in aiogram.utils.helper), 196 MessageError, 191
iter_keys() (aiogram.types.base.TelegramObject MessageIdentifierNotSpecified, 191
method), 60 MessageIsNotAPoll, 192
iter_values() (aiogram.types.base.TelegramObject MessageIsTooLong, 191
method), 60 MessageNotModified, 191
MessageTextIsEmpty, 191
K MessageToDeleteNotFound, 191
key (aiogram.dispatcher.filters.BoundFilter attribute), MessageToEditNotFound, 191
169 MessageToForwardNotFound, 191
KeyboardButton (class in MessageToPinNotFound, 191
aiogram.types.reply_keyboard), 72 MessageToReplyNotFound, 191
kick() (aiogram.types.chat.Chat method), 74 MessageWithPollNotFound, 192
kick_chat_member() (aiogram.bot.bot.Bot MetaTelegramObject (class in aiogram.types.base),
method), 38 59
MethodIsNotAvailable, 193
L MethodNotAvailableInPrivateChats, 192
LabeledPrice (class in aiogram.types.labeled_price), MethodNotKnown, 193
71 Methods (class in aiogram.bot.api), 58

236 Index
 aiogram Documentation, Release 2.11.2

MigrateToChat, 193 PassportElementErrorFiles (class in

module aiogram.types.passport_element_error),
aiogram.bot.api, 57 84
aiogram.utils.auth_widget, 185 PassportElementErrorFrontSide (class in
aiogram.utils.deep_linking, 199 aiogram.types.passport_element_error), 85
aiogram.utils.deprecated, 197 PassportElementErrorReverseSide (class in
aiogram.utils.emoji, 199 aiogram.types.passport_element_error), 85
aiogram.utils.exceptions, 188 PassportElementErrorSelfie (class in
aiogram.utils.executor, 186 aiogram.types.passport_element_error),
aiogram.utils.helper, 196 86
aiogram.utils.json, 199 PassportFile (class in aiogram.types.passport_file),
aiogram.utils.markdown, 194 123
aiogram.utils.parts, 198 PaymentProviderInvalid, 193
aiogram.utils.payload, 198 PhotoAsInputFileRequired, 192
MongoStorage (class in PhotoDimensions, 193
aiogram.contrib.fsm_storage.mongo), 170 PhotoSize (class in aiogram.types.photo_size), 121
pin() (aiogram.types.message.Message method), 154
N pin_chat_message() (aiogram.bot.bot.Bot
NeedAdministratorRightsInTheChannel, 192 method), 43
NetworkError, 193 pin_message() (aiogram.types.chat.Chat method),
NoStickerInRequest, 192 77
NotEnoughRightsToPinMessage, 192 poll_answer_handler() (aiogram.Dispatcher
NotEnoughRightsToRestrict, 193 method), 182
NotFound, 193 poll_handler() (aiogram.Dispatcher method), 181
PollCanBeRequestedInPrivateChatsOnly,
O 192
ObjectExpectedAsReplyMarkup, 191 PollCantBeStopped, 191
on_shutdown() (aiogram.utils.executor.Executor PollCantHaveMoreOptions, 192
method), 187 PollError, 191
on_startup() (aiogram.utils.executor.Executor PollHasAlreadyBeenClosed, 191
method), 187 PollMustHaveMoreOptions, 192
OrderInfo (class in aiogram.types.order_info), 87 PollOptionsLengthTooLong, 192
PollOptionsMustBeNonEmpty, 192
P PollQuestionLengthTooLong, 192
PollQuestionMustBeNonEmpty, 192
paginate() (in module aiogram.utils.parts), 198
PollsCantBeSentToPrivateChats, 192
parse() (aiogram.types.auth_widget_data.AuthWidgetData
PollSizeError, 192
class method), 158
pre() (in module aiogram.utils.markdown), 195
parse() (aiogram.types.message_entity.MessageEntity
pre_checkout_query_handler()
method), 66
(aiogram.Dispatcher method), 181
parse_entities() (aiogram.types.message.Message
PreCheckoutQuery (class in
method), 126
aiogram.types.pre_checkout_query), 116
ParseMode (class in aiogram.types.message), 156
prefix (aiogram.dispatcher.filters.Command.CommandObj
PassportData (class in
attribute), 160
aiogram.types.passport_data), 68
prepare_arg() (in module aiogram.utils.payload),
PassportElementError (class in
198
aiogram.types.passport_element_error),
process_update() (aiogram.Dispatcher method),
83
173
PassportElementErrorDataField (class in
process_updates() (aiogram.Dispatcher method),
aiogram.types.passport_element_error), 83
173
PassportElementErrorFile (class in
promote() (aiogram.types.chat.Chat method), 76
aiogram.types.passport_element_error),
promote_chat_member() (aiogram.bot.bot.Bot
84
method), 40
props() (aiogram.types.base.TelegramObject prop-

Index 237
aiogram Documentation, Release 2.11.2

erty), 59 reply_audio() (aiogram.types.message.Message

props_aliases() (aiogram.types.base.TelegramObject method), 140
property), 59 reply_contact() (aiogram.types.message.Message
method), 148
Q reply_dice() (aiogram.types.message.Message
quote_html() (in module aiogram.utils.markdown), method), 151
194 reply_document() (aiogram.types.message.Message
method), 143
R reply_location() (aiogram.types.message.Message
record_audio() (aiogram.types.chat.ChatActions method), 147
class method), 81 reply_media_group()
record_video() (aiogram.types.chat.ChatActions (aiogram.types.message.Message method),
class method), 81 146
record_video_note() reply_photo() (aiogram.types.message.Message
(aiogram.types.chat.ChatActions class method), 139
method), 81 reply_poll() (aiogram.types.message.Message
RedisStorage (class in method), 149
aiogram.contrib.fsm_storage.redis), 170 reply_sticker() (aiogram.types.message.Message
Regexp (class in aiogram.dispatcher.filters), 164 method), 150
RegexpCommandsFilter (class in reply_venue() (aiogram.types.message.Message
aiogram.dispatcher.filters), 165 method), 147
register_callback_query_handler() reply_video() (aiogram.types.message.Message
(aiogram.Dispatcher method), 179 method), 144
register_channel_post_handler() reply_video_note()
(aiogram.Dispatcher method), 177 (aiogram.types.message.Message method),
register_chosen_inline_handler() 146
(aiogram.Dispatcher method), 179 reply_voice() (aiogram.types.message.Message
register_edited_channel_post_handler() method), 145
(aiogram.Dispatcher method), 177 ReplyKeyboardMarkup (class in
register_edited_message_handler() aiogram.types.reply_keyboard), 72
(aiogram.Dispatcher method), 176 ReplyKeyboardRemove (class in
register_errors_handler() aiogram.types.reply_keyboard), 73
(aiogram.Dispatcher method), 182 request() (aiogram.bot.base.BaseBot method), 18
register_inline_handler() request_timeout() (aiogram.bot.base.BaseBot
(aiogram.Dispatcher method), 178 method), 17
register_message_handler() required (aiogram.dispatcher.filters.BoundFilter at-
(aiogram.Dispatcher method), 174 tribute), 169
register_poll_answer_handler() reset_webhook() (aiogram.Dispatcher method),
(aiogram.Dispatcher method), 182 174
register_poll_handler() (aiogram.Dispatcher resolve() (aiogram.dispatcher.filters.FiltersFactory
method), 181 method), 158
register_pre_checkout_query_handler() ResponseParameters (class in
(aiogram.Dispatcher method), 180 aiogram.types.response_parameters), 86
register_shipping_query_handler() RestartingTelegram, 193
(aiogram.Dispatcher method), 180 restrict() (aiogram.types.chat.Chat method), 75
release_key() (aiogram.Dispatcher method), 183 restrict_chat_member() (aiogram.bot.bot.Bot
renamed_argument() (in module method), 39
aiogram.utils.deprecated), 197 ResultIdDuplicate, 193
reply() (aiogram.types.message.Message method), RethinkDBStorage (class in
139 aiogram.contrib.fsm_storage.rethinkdb),
reply_animation() 171
(aiogram.types.message.Message method), RetryAfter, 193
141 row() (aiogram.types.inline_keyboard.InlineKeyboardMarkup
method), 68

238 Index
 aiogram Documentation, Release 2.11.2

row() (aiogram.types.reply_keyboard.ReplyKeyboardMarkup set_chat_sticker_set() (aiogram.bot.bot.Bot

method), 72 method), 45
set_chat_title() (aiogram.bot.bot.Bot method),
S 42
safe_split_text() (in module set_description() (aiogram.types.chat.Chat
aiogram.utils.parts), 198 method), 74
save() (aiogram.types.input_file.InputFile method), set_game_score() (aiogram.bot.bot.Bot method),
115 56
send_animation() (aiogram.bot.bot.Bot method), set_my_commands() (aiogram.bot.bot.Bot method),
28 46
send_audio() (aiogram.bot.bot.Bot method), 25 set_passport_data_errors()
send_chat_action() (aiogram.bot.bot.Bot (aiogram.bot.bot.Bot method), 55
method), 38 set_permissions() (aiogram.types.chat.Chat
send_contact() (aiogram.bot.bot.Bot method), 35 method), 77
send_copy() (aiogram.types.message.Message set_photo() (aiogram.types.chat.Chat method), 74
method), 154 set_position_in_set()
send_dice() (aiogram.bot.bot.Bot method), 37 (aiogram.types.sticker.Sticker method), 87
send_document() (aiogram.bot.bot.Bot method), 26 set_sticker_position_in_set()
send_file() (aiogram.bot.base.BaseBot method), 18 (aiogram.bot.bot.Bot method), 51
send_game() (aiogram.bot.bot.Bot method), 56 set_sticker_set() (aiogram.types.chat.Chat
send_invoice() (aiogram.bot.bot.Bot method), 53 method), 78
send_location() (aiogram.bot.bot.Bot method), 31 set_sticker_set_thumb() (aiogram.bot.bot.Bot
send_media_group() (aiogram.bot.bot.Bot method), 52
method), 31 set_title() (aiogram.types.chat.Chat method), 74
send_message() (aiogram.bot.bot.Bot method), 22 set_value() (aiogram.types.fields.BaseField
send_photo() (aiogram.bot.bot.Bot method), 24 method), 60
send_poll() (aiogram.bot.bot.Bot method), 35 set_web_app() (aiogram.utils.executor.Executor
send_sticker() (aiogram.bot.bot.Bot method), 49 method), 187
send_venue() (aiogram.bot.bot.Bot method), 34 set_webhook() (aiogram.bot.bot.Bot method), 20
send_video() (aiogram.bot.bot.Bot method), 27 set_webhook() (aiogram.utils.executor.Executor
send_video_note() (aiogram.bot.bot.Bot method), method), 188
30 set_webhook() (in module aiogram.utils.executor),
send_voice() (aiogram.bot.bot.Bot method), 29 186
serialize() (aiogram.types.fields.BaseField setup_middleware() (aiogram.Dispatcher
method), 60 method), 184
serialize() (aiogram.types.fields.DateTimeField shifted_id() (aiogram.types.chat.Chat property), 73
method), 62 shipping_query_handler() (aiogram.Dispatcher
serialize() (aiogram.types.fields.Field method), 61 method), 180
serialize() (aiogram.types.fields.ListField method), ShippingAddress (class in
61 aiogram.types.shipping_address), 86
serialize() (aiogram.types.fields.ListOfLists ShippingOption (class in
method), 62 aiogram.types.shipping_option), 124
serialize() (aiogram.types.fields.TextField method), ShippingQuery (class in
63 aiogram.types.shipping_query), 67
set_administrator_custom_title() skip_updates() (aiogram.Dispatcher method), 173
(aiogram.types.chat.Chat method), 77 split_text() (in module aiogram.utils.parts), 198
set_chat_administrator_custom_title() start() (aiogram.utils.executor.Executor method), 188
(aiogram.bot.bot.Bot method), 41 start() (in module aiogram.utils.executor), 187
set_chat_description() (aiogram.bot.bot.Bot start_polling() (aiogram.Dispatcher method),
method), 42 174
set_chat_permissions() (aiogram.bot.bot.Bot start_polling() (aiogram.utils.executor.Executor
method), 41 method), 188
set_chat_photo() (aiogram.bot.bot.Bot method), start_polling() (in module
41 aiogram.utils.executor), 186

Index 239
aiogram Documentation, Release 2.11.2

start_webhook() (aiogram.utils.executor.Executor unban_chat_member() (aiogram.bot.bot.Bot

method), 188 method), 39
start_webhook() (in module unbind() (aiogram.dispatcher.filters.FiltersFactory
aiogram.utils.executor), 186 method), 158
StartParamInvalid, 192 unbind_filter() (aiogram.Dispatcher method),
StateFilter (class in aiogram.dispatcher.filters), 166 184
Sticker (class in aiogram.types.sticker), 87 underline() (in module aiogram.utils.markdown),
StickerSet (class in aiogram.types.sticker_set), 64 195
stop_live_location() unpin() (aiogram.types.message.Message method),
(aiogram.types.message.Message method), 154
153 unpin_all_chat_messages()
stop_message_live_location() (aiogram.bot.bot.Bot method), 43
(aiogram.bot.bot.Bot method), 33 unpin_all_messages() (aiogram.types.chat.Chat
stop_poll() (aiogram.bot.bot.Bot method), 48 method), 77
stop_polling() (aiogram.Dispatcher method), 174 unpin_chat_message() (aiogram.bot.bot.Bot
strikethrough() (in module method), 43
aiogram.utils.markdown), 195 unpin_message() (aiogram.types.chat.Chat
SuccessfulPayment (class in method), 77
aiogram.types.successful_payment), 66 UnsupportedUrlProtocol, 193
Update (class in aiogram.types.update), 121
T update_chat() (aiogram.types.chat.Chat method),
TelegramAPIError, 191 73
TelegramAPIServer (class in aiogram.bot.api), 57 upload_audio() (aiogram.types.chat.ChatActions
TelegramObject (class in aiogram.types.base), 59 class method), 81
TerminatedByOtherGetUpdates, 193 upload_document()
Text (class in aiogram.dispatcher.filters), 163 (aiogram.types.chat.ChatActions class
text() (aiogram.dispatcher.filters.Command.CommandObj method), 81
property), 160 upload_photo() (aiogram.types.chat.ChatActions
text() (in module aiogram.utils.markdown), 194 class method), 81
TextField (class in aiogram.types.fields), 63 upload_sticker_file() (aiogram.bot.bot.Bot
throttle() (aiogram.Dispatcher method), 183 method), 50
Throttled, 193 upload_video() (aiogram.types.chat.ChatActions
throttled() (aiogram.Dispatcher method), 184 class method), 81
TimeoutWarning, 191 upload_video_note()
to_object() (aiogram.types.base.TelegramObject (aiogram.types.chat.ChatActions class
class method), 59 method), 81
to_object() (aiogram.types.input_file.InputFile class url() (aiogram.types.message.Message property), 126
method), 116 URLHostIsEmpty, 192
to_python() (aiogram.types.base.TelegramObject User (class in aiogram.types.user), 69
method), 59 UserDeactivated, 193
to_python() (aiogram.types.input_file.InputFile UserProfilePhotos (class in
method), 115 aiogram.types.user_profile_photos), 157
to_python() (aiogram.types.input_media.MediaGroup
method), 93 V
ToMuchMessages, 191 validate() (aiogram.dispatcher.filters.AbstractFilter
TypeOfFileMismatch, 193 class method), 168
typing() (aiogram.types.chat.ChatActions class validate() (aiogram.dispatcher.filters.AdminFilter
method), 80 class method), 167
validate() (aiogram.dispatcher.filters.BoundFilter
U class method), 169
Unauthorized, 193 validate() (aiogram.dispatcher.filters.builtin.IDFilter
UnavailableMembers, 193 class method), 166
unban() (aiogram.types.chat.Chat method), 75 validate() (aiogram.dispatcher.filters.Command
class method), 160

240 Index
 aiogram Documentation, Release 2.11.2

validate() (aiogram.dispatcher.filters.Filter class

method), 169
validate() (aiogram.dispatcher.filters.HashTag class
method), 164
validate() (aiogram.dispatcher.filters.Regexp class
method), 164
validate() (aiogram.dispatcher.filters.Text class
method), 163
ValidationError, 191
values() (aiogram.types.base.TelegramObject prop-
erty), 59
Venue (class in aiogram.types.venue), 122
Video (class in aiogram.types.video), 70
VideoNote (class in aiogram.types.video_note), 122
Voice (class in aiogram.types.voice), 116

W
wait_closed() (aiogram.Dispatcher method), 174
WebhookInfo (class in aiogram.types.webhook_info),
123
WebhookRequireHTTPS, 193
WrongFileIdentifier, 192
WrongRemoteFileIdSpecified, 193

Index 241