python-telegram-bot Documentation, Release 22.

Raises
telegram.error.TelegramError –
async reopenForumTopic(chat_id, message_thread_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for reopen_forum_topic()
async reopenGeneralForumTopic(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for reopen_general_forum_topic()
async reopen_forum_topic(chat_id, message_thread_id, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights, unless it is the
creator of the topic.

 Shortcuts

• telegram.Chat.reopen_forum_topic()
• telegram.ChatFullInfo.reopen_forum_topic()
• telegram.Message.reopen_forum_topic()

Added in version 20.0.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• message_thread_id (int) – Unique identifier for the target message thread of the
forum topic.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async reopen_general_forum_topic(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)

90 Chapter 6. License
 python-telegram-bot Documentation, Release 22.0

Use this method to reopen a closed ‘General’ topic in a forum supergroup chat. The bot must be an
administrator in the chat for this to work and must have can_manage_topics administrator rights.
The topic will be automatically unhidden if it was hidden.

 Shortcuts

• telegram.Chat.reopen_general_forum_topic()
• telegram.ChatFullInfo.reopen_general_forum_topic()

Added in version 20.0.

Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async replaceStickerInSet(user_id, name, old_sticker, sticker, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for replace_sticker_in_set()
async replace_sticker_in_set(user_id, name, old_sticker, sticker, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to replace an existing sticker in a sticker set with a new one. The method
is equivalent to calling delete_sticker_from_set(), then add_sticker_to_set(), then
set_sticker_position_in_set().
Added in version 21.1.
Parameters
• user_id (int) – User identifier of the sticker set owner.
• name (str) – Sticker set name.
• old_sticker (str | Sticker) – File identifier of the replaced sticker or the sticker
object itself.

6.1. telegram package 91

python-telegram-bot Documentation, Release 22.0

Changed in version 21.10: Accepts also telegram.Sticker instances.

• sticker (telegram.InputSticker) – An object with information about the added
sticker. If exactly the same sticker had already been added to the set, then the set
remains unchanged.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
property request
The BaseRequest object used by this bot.

 Warning

Requests to the Bot API are made by the various methods of this class. This attribute should not
be used manually.

async restrictChatMember(chat_id, user_id, permissions, until_date=None,

use_independent_chat_permissions=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for restrict_chat_member()
async restrict_chat_member(chat_id, user_id, permissions, until_date=None,
use_independent_chat_permissions=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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.

 See also

telegram.ChatPermissions.all_permissions()

 Shortcuts

92 Chapter 6. License
 python-telegram-bot Documentation, Release 22.0

• telegram.Chat.restrict_member()
• telegram.ChatFullInfo.restrict_member()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• user_id (int) – Unique identifier of the target user.
• until_date (int | datetime.datetime, optional) – Date when restrictions will be
lifted for the user, unix time. If user is restricted for more than 366 days or less than
30 seconds from the current time, they are considered to be restricted forever. For
timezone naive datetime.datetime objects, the default timezone of the bot will be
used, which is UTC unless telegram.ext.Defaults.tzinfo is used.
• permissions (telegram.ChatPermissions) – An object for new user permissions.
• use_independent_chat_permissions (bool, optional) – Pass True if chat
permissions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos,
can_send_videos, can_send_video_notes, and can_send_voice_notes
permissions; the can_send_polls permission will imply the can_send_messages
permission.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async revokeChatInviteLink(chat_id, invite_link, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for revoke_chat_invite_link()
async revoke_chat_invite_link(chat_id, invite_link, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to revoke an invite link created by the bot. If the primary link is revoked, a new link
is automatically generated. The bot must be an administrator in the chat for this to work and must have
the appropriate admin rights.

6.1. telegram package 93

python-telegram-bot Documentation, Release 22.0

 Shortcuts

• telegram.Chat.revoke_invite_link()
• telegram.ChatFullInfo.revoke_invite_link()

Added in version 13.4.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• invite_link (str | telegram.ChatInviteLink) – The invite link to revoke.
Changed in version 20.0: Now also accepts telegram.ChatInviteLink instances.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
telegram.ChatInviteLink
Raises
telegram.error.TelegramError –
async savePreparedInlineMessage(user_id, result, allow_user_chats=None,
allow_bot_chats=None, allow_group_chats=None,
allow_channel_chats=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for save_prepared_inline_message()
async save_prepared_inline_message(user_id, result, allow_user_chats=None,
allow_bot_chats=None, allow_group_chats=None,
allow_channel_chats=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Stores a message that can be sent by a user of a Mini App.
Added in version 21.8.
Parameters
• user_id (int) – Unique identifier of the target user that can use the prepared message.
• result (telegram.InlineQueryResult) – The result to store.
• allow_user_chats (bool, optional) – Pass True if the message can be sent to private
chats with users
• allow_bot_chats (bool, optional) – Pass True if the message can be sent to private
chats with bots

94 Chapter 6. License
 python-telegram-bot Documentation, Release 22.0

• allow_group_chats (bool, optional) – Pass True if the message can be sent to group
and supergroup chats
• allow_channel_chats (bool, optional) – Pass True if the message can be sent to
channels
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the prepared message is returned.
Return type
telegram.PreparedInlineMessage
Raises
telegram.error.TelegramError –
async sendAnimation(chat_id, animation, duration=None, width=None, height=None, caption=None,
parse_mode=None, disable_notification=None, reply_markup=None,
caption_entities=None, protect_content=None, message_thread_id=None,
has_spoiler=None, thumbnail=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, show_caption_above_media=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
filename=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_animation()
async sendAudio(chat_id, audio, duration=None, performer=None, title=None, caption=None,
disable_notification=None, reply_markup=None, parse_mode=None,
caption_entities=None, protect_content=None, message_thread_id=None,
thumbnail=None, reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None, filename=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for send_audio()
async sendChatAction(chat_id, action, message_thread_id=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for send_chat_action()

6.1. telegram package 95

python-telegram-bot Documentation, Release 22.0

async sendContact(chat_id, phone_number=None, first_name=None, last_name=None,

disable_notification=None, reply_markup=None, vcard=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, contact=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for send_contact()
async sendDice(chat_id, disable_notification=None, reply_markup=None, emoji=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_dice()
async sendDocument(chat_id, document, caption=None, disable_notification=None,
reply_markup=None, parse_mode=None, disable_content_type_detection=None,
caption_entities=None, protect_content=None, message_thread_id=None,
thumbnail=None, reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
filename=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_document()
async sendGame(chat_id, game_short_name, disable_notification=None, reply_markup=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_game()
async sendGift(gift_id, text=None, text_parse_mode=None, text_entities=None,
pay_for_upgrade=None, chat_id=None, user_id=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for send_gift()
async sendInvoice(chat_id, title, description, payload, currency, prices, provider_token=None,
start_parameter=None, photo_url=None, photo_size=None, photo_width=None,
photo_height=None, need_name=None, need_phone_number=None,
need_email=None, need_shipping_address=None, is_flexible=None,
disable_notification=None, reply_markup=None, provider_data=None,
send_phone_number_to_provider=None, send_email_to_provider=None,
max_tip_amount=None, suggested_tip_amounts=None, protect_content=None,
message_thread_id=None, reply_parameters=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_invoice()

96 Chapter 6. License
 python-telegram-bot Documentation, Release 22.0

async sendLocation(chat_id, latitude=None, longitude=None, disable_notification=None,

reply_markup=None, live_period=None, horizontal_accuracy=None,
heading=None, proximity_alert_radius=None, protect_content=None,
message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, location=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for send_location()
async sendMediaGroup(chat_id, media, disable_notification=None, protect_content=None,
message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None,
caption=None, parse_mode=None, caption_entities=None)
Alias for send_media_group()
async sendMessage(chat_id, text, parse_mode=None, entities=None, disable_notification=None,
protect_content=None, reply_markup=None, message_thread_id=None,
link_preview_options=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, disable_web_page_preview=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for send_message()
async sendPaidMedia(chat_id, star_count, media, caption=None, parse_mode=None,
caption_entities=None, show_caption_above_media=None,
disable_notification=None, protect_content=None, reply_parameters=None,
reply_markup=None, business_connection_id=None, payload=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_paid_media()
async sendPhoto(chat_id, photo, caption=None, disable_notification=None, reply_markup=None,
parse_mode=None, caption_entities=None, protect_content=None,
message_thread_id=None, has_spoiler=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, show_caption_above_media=None, *,
allow_sending_without_reply=None, reply_to_message_id=None, filename=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for send_photo()
async sendPoll(chat_id, question, options, is_anonymous=None, type=None,
allows_multiple_answers=None, correct_option_id=None, is_closed=None,
disable_notification=None, reply_markup=None, explanation=None,
explanation_parse_mode=None, open_period=None, close_date=None,
explanation_entities=None, protect_content=None, message_thread_id=None,
reply_parameters=None, business_connection_id=None, question_parse_mode=None,
question_entities=None, message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)

6.1. telegram package 97

python-telegram-bot Documentation, Release 22.0

Alias for send_poll()

async sendSticker(chat_id, sticker, disable_notification=None, reply_markup=None,
protect_content=None, message_thread_id=None, emoji=None,
reply_parameters=None, business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_sticker()
async sendVenue(chat_id, latitude=None, longitude=None, title=None, address=None,
foursquare_id=None, disable_notification=None, reply_markup=None,
foursquare_type=None, google_place_id=None, google_place_type=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, venue=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_venue()
async sendVideo(chat_id, video, duration=None, caption=None, disable_notification=None,
reply_markup=None, width=None, height=None, parse_mode=None,
supports_streaming=None, caption_entities=None, protect_content=None,
message_thread_id=None, has_spoiler=None, thumbnail=None,
reply_parameters=None, business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, show_caption_above_media=None, cover=None,
start_timestamp=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for send_video()
async sendVideoNote(chat_id, video_note, duration=None, length=None, disable_notification=None,
reply_markup=None, protect_content=None, message_thread_id=None,
thumbnail=None, reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
filename=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for send_video_note()
async sendVoice(chat_id, voice, duration=None, caption=None, disable_notification=None,
reply_markup=None, parse_mode=None, caption_entities=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for send_voice()

98 Chapter 6. License
 python-telegram-bot Documentation, Release 22.0

async send_animation(chat_id, animation, duration=None, width=None, height=None,

caption=None, parse_mode=None, disable_notification=None,
reply_markup=None, caption_entities=None, protect_content=None,
message_thread_id=None, has_spoiler=None, thumbnail=None,
reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None,
show_caption_above_media=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). Bots can
currently send animation files of up to 50 MB in size, this limit may be changed in the future.

 Note

thumbnail will be ignored for small files, for which Telegram can easily generate thumbnails.
However, this behaviour is undocumented and might be changed by Telegram.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_animation()
• telegram.ChatFullInfo.send_animation()
• telegram.Message.reply_animation()
• telegram.User.send_animation()

Changed in version 20.5: Removed deprecated argument thumb. Use thumbnail instead.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• animation (str | file object | InputFile | bytes | pathlib.Path | telegram.
Animation) – Animation to send. Pass a file_id as String to send a file that exists
on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram
to get a file from the Internet, or upload a new one. To upload a file, you can either pass
a file object (e.g. open("filename", "rb")), the file contents as bytes or the path
of the file (as string or pathlib.Path object). In the latter case, the file contents will
either be read as bytes or the file path will be passed to Telegram, depending on the
local_mode setting. Lastly you can pass an existing telegram.Animation object
to send.
Changed in version 13.2: Accept bytes as input.
• duration (int | datetime.timedelta, optional) – Duration of sent animation in
seconds.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• width (int, optional) – Animation width.

6.1. telegram package 99

python-telegram-bot Documentation, Release 22.0

• height (int, optional) – Animation height.

• caption (str, optional) – Animation caption (may also be used when resending ani-
mations by file_id), 0-1024 characters after entities parsing.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• has_spoiler (bool, optional) – Pass True if the animation needs to be covered with
a spoiler animation.
Added in version 20.0.
• thumbnail (file object | bytes | pathlib.Path | str, optional) – Thumbnail of the
file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumb-
nail’s width and height should not exceed 320. Ignored if the file is not uploaded
using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a
new file. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")), the file contents as bytes or the path of the file (as string or pathlib.Path
object). In the latter case, the file contents will either be read as bytes or the file path
will be passed to Telegram, depending on the local_mode setting.
Added in version 20.2.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.

100 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Added in version 21.7.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be
shown above the message media.
Added in version 21.3.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the animation, when uploading a
new file. Convenience parameter, useful e.g. when sending files generated by the
tempfile module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

6.1. telegram package 101

python-telegram-bot Documentation, Release 22.0

async send_audio(chat_id, audio, duration=None, performer=None, title=None, caption=None,

disable_notification=None, reply_markup=None, parse_mode=None,
caption_entities=None, protect_content=None, message_thread_id=None,
thumbnail=None, reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None, filename=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
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 or .m4a format.
Bots can currently send audio files of up to 50 MB in size, this limit may be changed in the future.
For sending voice messages, use the send_voice() method instead.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_audio()
• telegram.ChatFullInfo.send_audio()
• telegram.Message.reply_audio()
• telegram.User.send_audio()

Changed in version 20.5: Removed deprecated argument thumb. Use thumbnail instead.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• audio (str | file object | InputFile | bytes | pathlib.Path | telegram.Audio) –
Audio file to send. Pass a file_id as String to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get a file from
the Internet, or upload a new one. To upload a file, you can either pass a file object
(e.g. open("filename", "rb")), the file contents as bytes or the path of the file (as
string or pathlib.Path object). In the latter case, the file contents will either be read
as bytes or the file path will be passed to Telegram, depending on the local_mode
setting. Lastly you can pass an existing telegram.Audio object to send.
Changed in version 13.2: Accept bytes as input.
Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• caption (str, optional) – Audio caption, 0-1024 characters after entities parsing.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.

102 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• duration (int | datetime.timedelta, optional) – Duration of sent audio in sec-

onds.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• performer (str, optional) – Performer.
• title (str, optional) – Track name.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• thumbnail (file object | bytes | pathlib.Path | str, optional) – Thumbnail of the
file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumb-
nail’s width and height should not exceed 320. Ignored if the file is not uploaded
using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a
new file. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")), the file contents as bytes or the path of the file (as string or pathlib.Path
object). In the latter case, the file contents will either be read as bytes or the file path
will be passed to Telegram, depending on the local_mode setting.
Added in version 20.2.
• reply_parameters (ReplyParameters, optional) – Description of the message to
reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for

6.1. telegram package 103

python-telegram-bot Documentation, Release 22.0

Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the audio, when uploading a new
file. Convenience parameter, useful e.g. when sending files generated by the tempfile
module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –
async send_chat_action(chat_id, action, message_thread_id=None, business_connection_id=None,
*, read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
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). Telegram only recommends using this method when a response from the bot will take
a noticeable amount of time to arrive.

 Shortcuts

• telegram.Chat.send_action()
• telegram.Chat.send_chat_action()
• telegram.ChatFullInfo.send_action()
• telegram.ChatFullInfo.send_chat_action()

104 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• telegram.Message.reply_chat_action()
• telegram.User.send_action()
• telegram.User.send_chat_action()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• action (str) – Type of action to broadcast. Choose one, depending on what the user
is about to receive. For convenience look at the constants in telegram.constants.
ChatAction.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async send_contact(chat_id, phone_number=None, first_name=None, last_name=None,

disable_notification=None, reply_markup=None, vcard=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, contact=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to send phone contacts.

 Note

6.1. telegram package 105

python-telegram-bot Documentation, Release 22.0

You can either supply contact or phone_number and first_name with optionally last_name
and optionally vcard.

 Shortcuts

• telegram.Chat.send_contact()
• telegram.ChatFullInfo.send_contact()
• telegram.Message.reply_contact()
• telegram.User.send_contact()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• phone_number (str, optional) – Contact’s phone number.
• first_name (str, optional) – Contact’s first name.
• last_name (str, optional) – Contact’s last name.
• vcard (str, optional) – Additional data about the contact in the form of a vCard,
0-2048 bytes.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.

106 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• contact (telegram.Contact, optional) – The contact to send.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_dice(chat_id, disable_notification=None, reply_markup=None, emoji=None,

protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to send an animated emoji that will display a random value.

 Shortcuts

• telegram.Chat.send_dice()
• telegram.ChatFullInfo.send_dice()
• telegram.Message.reply_dice()
• telegram.User.send_dice()

6.1. telegram package 107

python-telegram-bot Documentation, Release 22.0

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user
• emoji (str, optional) – Emoji on which the dice throw animation is based. Currently,
must be one of telegram.constants.DiceEmoji. Dice can have values 1-6 for '',
'' and '', values 1-5 for '' and '', and values 1- 64 for ''. Defaults to ''.
Changed in version 13.4: Added the '' emoji.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.

108 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Changed in version 21.0: This argument is now a keyword-only argument.

• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_document(chat_id, document, caption=None, disable_notification=None,

reply_markup=None, parse_mode=None,
disable_content_type_detection=None, caption_entities=None,
protect_content=None, message_thread_id=None, thumbnail=None,
reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
filename=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to send general files.
Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_document()
• telegram.ChatFullInfo.send_document()
• telegram.Message.reply_document()
• telegram.User.send_document()

Changed in version 20.5: Removed deprecated argument thumb. Use thumbnail instead.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• document (str | file object | InputFile | bytes | pathlib.Path | telegram.
Document) – File to send. Pass a file_id as String to send a file that exists on the

6.1. telegram package 109

python-telegram-bot Documentation, Release 22.0

Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get
a file from the Internet, or upload a new one. To upload a file, you can either pass a
file object (e.g. open("filename", "rb")), the file contents as bytes or the path of
the file (as string or pathlib.Path object). In the latter case, the file contents will
either be read as bytes or the file path will be passed to Telegram, depending on the
local_mode setting. Lastly you can pass an existing telegram.Document object to
send.

 Note

Sending by URL will currently only work GIF, PDF & ZIP files.

Changed in version 13.2: Accept bytes as input.

Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• caption (str, optional) – Document caption (may also be used when resending doc-
uments by file_id), 0-1024 characters after entities parsing.
• disable_content_type_detection (bool, optional) – Disables automatic server-
side content type detection for files uploaded using multipart/form-data.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• thumbnail (file object | bytes | pathlib.Path | str, optional) – Thumbnail of the
file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumb-
nail’s width and height should not exceed 320. Ignored if the file is not uploaded
using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a
new file. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")), the file contents as bytes or the path of the file (as string or pathlib.Path
object). In the latter case, the file contents will either be read as bytes or the file path
will be passed to Telegram, depending on the local_mode setting.
Added in version 20.2.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.

110 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Added in version 20.8.

• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the document, when uploading a
new file. Convenience parameter, useful e.g. when sending files generated by the
tempfile module.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

6.1. telegram package 111

python-telegram-bot Documentation, Release 22.0

async send_game(chat_id, game_short_name, disable_notification=None, reply_markup=None,

protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to send a game.

 Shortcuts

• telegram.Chat.send_game()
• telegram.ChatFullInfo.send_game()
• telegram.Message.reply_game()
• telegram.User.send_game()

Parameters
• chat_id (int) – Unique identifier for the target chat.
• game_short_name (str) – Short name of the game, serves as the unique identifier for
the game. Set up your games via @BotFather.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (telegram.InlineKeyboardMarkup, optional) – An object for a
new inline keyboard. If empty, one “Play game_title” button will be shown. If not
empty, the first button must launch the game.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments

112 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• allow_sending_without_reply (bool, optional) – Pass True, if the message

should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_gift(gift_id, text=None, text_parse_mode=None, text_entities=None,

pay_for_upgrade=None, chat_id=None, user_id=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Sends a gift to the given user or channel chat. The gift can’t be converted to Telegram Stars by the
receiver.

 Shortcuts

• telegram.Chat.send_gift()
• telegram.ChatFullInfo.send_gift()
• telegram.User.send_gift()

Added in version 21.8.

Changed in version NEXT.VERSION: Bot API 8.3 made user_id optional. In version
NEXT.VERSION, the methods signature was changed accordingly.
Parameters

6.1. telegram package 113

python-telegram-bot Documentation, Release 22.0

• gift_id (str | Gift) – Identifier of the gift or a Gift object

• user_id (int, optional) – Required if chat_id is not specified. Unique identifier of
the target user that will receive the gift.
Changed in version 21.11: Now optional.
• chat_id (int | str, optional) – Required if user_id is not specified. Unique
identifier for the target chat or username of the target channel (in the format
@channelusername). It will receive the gift.
Added in version 21.11.
• text (str, optional) – Text that will be shown along with the gift; 0- 128 characters
• text_parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details. Entities other than
BOLD, ITALIC, UNDERLINE, STRIKETHROUGH, SPOILER, and CUSTOM_EMOJI are ig-
nored.
• text_entities (Sequence[telegram.MessageEntity], optional) – A list
of special entities that appear in the gift text. It can be specified instead
of text_parse_mode. Entities other than BOLD, ITALIC, UNDERLINE,
STRIKETHROUGH, SPOILER, and CUSTOM_EMOJI are ignored.
• pay_for_upgrade (bool, optional) – Pass True to pay for the gift upgrade from the
bot’s balance, thereby making the upgrade free for the receiver.
Added in version 21.10.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async send_invoice(chat_id, title, description, payload, currency, prices, provider_token=None,
start_parameter=None, photo_url=None, photo_size=None, photo_width=None,
photo_height=None, need_name=None, need_phone_number=None,
need_email=None, need_shipping_address=None, is_flexible=None,
disable_notification=None, reply_markup=None, provider_data=None,
send_phone_number_to_provider=None, send_email_to_provider=None,
max_tip_amount=None, suggested_tip_amounts=None, protect_content=None,
message_thread_id=None, reply_parameters=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)

114 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Use this method to send invoices.

 Warning

As of API 5.2 start_parameter is an optional argument and therefore the order of the arguments
had to be changed. Use keyword arguments to make sure that the arguments are passed correctly.

 Shortcuts

• telegram.Chat.send_invoice()
• telegram.ChatFullInfo.send_invoice()
• telegram.Message.reply_invoice()
• telegram.User.send_invoice()

Changed in version 13.5: As of Bot API 5.2, the parameter start_parameter is optional.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• title (str) – Product name. 1- 32 characters.
• description (str) – Product description. 1- 255 characters.
• payload (str) – Bot-defined invoice payload. 1- 128 bytes. This will not be displayed
to the user, use it for your internal processes.
• provider_token (str, optional) – Payments provider token, obtained via @BotFa-
ther. Pass an empty string for payments in Telegram Stars.
Changed in version 21.11: Bot API 7.4 made this parameter is optional and this is now
reflected in the function signature.
• currency (str) – Three-letter ISO 4217 currency code, see more on currencies. Pass
XTR for payment in Telegram Stars.
• prices (Sequence[telegram.LabeledPrice]) – Price breakdown, a sequence of
components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.).
Must contain exactly one item for payment in Telegram Stars.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• max_tip_amount (int, optional) – The maximum accepted amount for tips in the
smallest units of the currency (integer, not float/double). For example, for a maximum
tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in curren-
cies.json, it shows the number of digits past the decimal point for each currency (2 for
the majority of currencies). Defaults to 0. Not supported for payment in Telegram
Stars.
Added in version 13.5.
• suggested_tip_amounts (Sequence[int], optional) – An array of suggested
amounts of tips in the smallest units of the currency (integer, not float/double). At
most 4 suggested tip amounts can be specified. The suggested tip amounts must be
positive, passed in a strictly increased order and must not exceed max_tip_amount.
Added in version 13.5.

6.1. telegram package 115

python-telegram-bot Documentation, Release 22.0

Changed in version 20.0: Accepts any collections.abc.Sequence as input instead

of just a list.
• start_parameter (str, optional) – Unique deep-linking parameter. If left empty,
forwarded copies of the sent message will have a Pay button, allowing multiple users
to pay directly from the forwarded message, using the same invoice. If non-empty,
forwarded copies of the sent message will have a URL button with a deep link to the
bot (instead of a Pay button), with the value used as the start parameter.
Changed in version 13.5: As of Bot API 5.2, this parameter is optional.
• provider_data (str | object, optional) – data about the invoice, which will be
shared with the payment provider. A detailed description of required fields should be
provided by the payment provider. When an object is passed, it will be encoded as
JSON.
• photo_url (str, optional) – URL of the product photo for the invoice. Can be a photo
of the goods or a marketing image for a service. People like it better when they see
what they are paying for.
• photo_size (str, optional) – Photo size.
• photo_width (int, optional) – Photo width.
• photo_height (int, optional) – Photo height.
• need_name (bool, optional) – Pass True, if you require the user’s full name to com-
plete the order. Ignored for payments in Telegram Stars.
• need_phone_number (bool, optional) – Pass True, if you require the user’s phone
number to complete the order. Ignored for payments in Telegram Stars.
• need_email (bool, optional) – Pass True, if you require the user’s email to complete
the order. Ignored for payments in Telegram Stars.
• need_shipping_address (bool, optional) – Pass True, if you require the user’s
shipping address to complete the order. Ignored for payments in Telegram Stars.
• send_phone_number_to_provider (bool, optional) – Pass True, if user’s phone
number should be sent to provider. Ignored for payments in Telegram Stars.
• send_email_to_provider (bool, optional) – Pass True, if user’s email address
should be sent to provider. Ignored for payments in Telegram Stars.
• is_flexible (bool, optional) – Pass True, if the final price depends on the shipping
method. Ignored for payments in Telegram Stars.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (telegram.InlineKeyboardMarkup, optional) – An 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.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.

116 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• message_effect_id (str, optional) – Unique identifier of the message effect to be

added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –
async send_location(chat_id, latitude=None, longitude=None, disable_notification=None,
reply_markup=None, live_period=None, horizontal_accuracy=None,
heading=None, proximity_alert_radius=None, protect_content=None,
message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, location=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to send point on the map.

6.1. telegram package 117

python-telegram-bot Documentation, Release 22.0

 Note

You can either supply a latitude and longitude or a location.

 Shortcuts

• telegram.Chat.send_location()
• telegram.ChatFullInfo.send_location()
• telegram.Message.reply_location()
• telegram.User.send_location()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• latitude (float, optional) – Latitude of location.
• longitude (float, optional) – Longitude of location.
• horizontal_accuracy (int, optional) – The radius of uncertainty for the location,
measured in meters; 0-1500.
• live_period (int | datetime.timedelta, optional) – Period in seconds for which
the location will be updated, should be between 60 and 86400, or 2147483647 for
live locations that can be edited indefinitely.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• heading (int, optional) – For live locations, a direction in which the user is moving,
in degrees. Must be between 1 and 360 if specified.
• proximity_alert_radius (int, optional) – For live locations, a maximum distance
for proximity alerts about approaching another chat member, in meters. Must be be-
tween 1 and 100000 if specified.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.

118 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Added in version 21.1.

• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• location (telegram.Location, optional) – The location to send.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_media_group(chat_id, media, disable_notification=None, protect_content=None,

message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None,
caption=None, parse_mode=None, caption_entities=None)

6.1. telegram package 119

python-telegram-bot Documentation, Release 22.0

Use this method to send a group of photos, videos, documents or audios as an album. Documents and
audio files can be only grouped in an album with messages of the same type.

 Note

If you supply a caption (along with either parse_mode or caption_entities), then items in
media must have no captions, and vice versa.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_media_group()
• telegram.ChatFullInfo.send_media_group()
• telegram.Message.reply_media_group()
• telegram.User.send_media_group()

Changed in version 20.0: Returns a tuple instead of a list.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• media (Sequence[telegram.InputMediaAudio, telegram.
InputMediaDocument, telegram.InputMediaPhoto, telegram.
InputMediaVideo]) – An array describing messages to be sent, must include
2- 10 items.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.

120 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• message_effect_id (str, optional) – Unique identifier of the message effect to be

added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• caption (str, optional) – Caption that will be added to the first element of media,
so that it will be used as caption for the whole media group. Defaults to None.
Added in version 20.0.
• parse_mode (str | None, optional) – Parse mode for caption. See the constants in
telegram.constants.ParseMode for the available modes.
Added in version 20.0.
• caption_entities (Sequence[telegram.MessageEntity], optional) – List of
special entities for caption, which can be specified instead of parse_mode. Defaults
to None.
Added in version 20.0.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
An array of the sent Messages.

6.1. telegram package 121

python-telegram-bot Documentation, Release 22.0

Return type
tuple[telegram.Message]
Raises
telegram.error.TelegramError –
async send_message(chat_id, text, parse_mode=None, entities=None, disable_notification=None,
protect_content=None, reply_markup=None, message_thread_id=None,
link_preview_options=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, disable_web_page_preview=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to send text messages.

 Shortcuts

• telegram.Chat.send_message()
• telegram.ChatFullInfo.send_message()
• telegram.Message.reply_html()
• telegram.Message.reply_markdown_v2()
• telegram.Message.reply_markdown()
• telegram.Message.reply_text()
• telegram.User.send_message()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• text (str) – Text of the message to be sent. Max 4096 characters after entities pars-
ing.
• parse_mode (str) – Mode for parsing entities. See telegram.constants.
ParseMode and formatting options for more details.
• entities (Sequence[telegram.MessageEntity], optional) – Sequence of special
entities that appear in message text, which can be specified instead of parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• link_preview_options (LinkPreviewOptions, optional) – Link preview genera-
tion options for the message. Mutually exclusive with disable_web_page_preview.
Added in version 20.8.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.

122 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• disable_web_page_preview (bool, optional) – Disables link previews for links in
this message. Convenience parameter for setting link_preview_options. Mutually
exclusive with link_preview_options.
Changed in version 20.8: Bot API 7.0 introduced link_preview_options replac-
ing this argument. PTB will automatically convert this argument to that one, but for
advanced options, please use link_preview_options directly.
Changed in version 21.0: This argument is now a keyword-only argument.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 123

python-telegram-bot Documentation, Release 22.0

• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-

gram API. See do_api_request() for limitations.
Returns
On success, the sent message is returned.
Return type
telegram.Message
Raises
• ValueError – If both disable_web_page_preview and link_preview_options
are passed.
• telegram.error.TelegramError – For other errors.

async send_paid_media(chat_id, star_count, media, caption=None, parse_mode=None,

caption_entities=None, show_caption_above_media=None,
disable_notification=None, protect_content=None, reply_parameters=None,
reply_markup=None, business_connection_id=None, payload=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to send paid media.

 Shortcuts

• telegram.Chat.send_paid_media()
• telegram.ChatFullInfo.send_paid_media()
• telegram.Message.reply_paid_media()

Added in version 21.4.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername). If the chat is a channel, all Telegram Star
proceeds from this media will be credited to the chat’s balance. Otherwise, they will
be credited to the bot’s balance.
• star_count (int) – The number of Telegram Stars that must be paid to buy access
to the media; 1 - 2500.
• media (Sequence[telegram.InputPaidMedia]) – A list describing the media to be
sent; up to 10 items.
• payload (str, optional) – Bot-defined paid media payload, 0-128 bytes. This will
not be displayed to the user, use it for your internal processes.
Added in version 21.6.
• caption (str, optional) – Caption of the media to be sent, 0-1024 characters.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
• show_caption_above_media (bool, optional) – Pass True, if the caption must be
shown above the message media.

124 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• disable_notification (bool, optional) – Sends the message silently. Users will

receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.5.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –
async send_photo(chat_id, photo, caption=None, disable_notification=None, reply_markup=None,
parse_mode=None, caption_entities=None, protect_content=None,
message_thread_id=None, has_spoiler=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, show_caption_above_media=None, *,
allow_sending_without_reply=None, reply_to_message_id=None, filename=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)

6.1. telegram package 125

python-telegram-bot Documentation, Release 22.0

Use this method to send photos.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_photo()
• telegram.ChatFullInfo.send_photo()
• telegram.Message.reply_photo()
• telegram.User.send_photo()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• photo (str | file object | InputFile | bytes | pathlib.Path | telegram.
PhotoSize) – Photo to send. Pass a file_id as String to send a file that exists on
the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to
get a file from the Internet, or upload a new one. To upload a file, you can either pass
a file object (e.g. open("filename", "rb")), the file contents as bytes or the path
of the file (as string or pathlib.Path object). In the latter case, the file contents will
either be read as bytes or the file path will be passed to Telegram, depending on the
local_mode setting. Lastly you can pass an existing telegram.PhotoSize object
to send.

 Caution

– The photo must be at most 10MB in size.

– The photo’s width and height must not exceed 10000 in total.
– Width and height ratio must be at most 20.

Changed in version 13.2: Accept bytes as input.

Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• caption (str, optional) – Photo caption (may also be used when resending photos
by file_id), 0-1024 characters after entities parsing.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.

126 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• has_spoiler (bool, optional) – Pass True if the photo needs to be covered with a
spoiler animation.
Added in version 20.0.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
• show_caption_above_media (bool, optional) – Pass True, if the caption must be
shown above the message media.
Added in version 21.3.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.

6.1. telegram package 127

python-telegram-bot Documentation, Release 22.0

• filename (str, optional) – Custom file name for the photo, when uploading a new
file. Convenience parameter, useful e.g. when sending files generated by the tempfile
module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_poll(chat_id, question, options, is_anonymous=None, type=None,

allows_multiple_answers=None, correct_option_id=None, is_closed=None,
disable_notification=None, reply_markup=None, explanation=None,
explanation_parse_mode=None, open_period=None, close_date=None,
explanation_entities=None, protect_content=None, message_thread_id=None,
reply_parameters=None, business_connection_id=None,
question_parse_mode=None, question_entities=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to send a native poll.

 Shortcuts

• telegram.Chat.send_poll()
• telegram.ChatFullInfo.send_poll()
• telegram.Message.reply_poll()
• telegram.User.send_poll()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• question (str) – Poll question, 1- 300 characters.
• options (Sequence[str | telegram.InputPollOption]) – Sequence of 2- 10 an-
swer options. Each option may either be a string with 1- 100 characters or an

128 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

InputPollOption object. Strings are converted to InputPollOption objects au-

tomatically.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
Changed in version 21.2: Bot API 7.3 adds support for InputPollOption objects.
• is_anonymous (bool, optional) – True, if the poll needs to be anonymous, defaults
to True.
• type (str, optional) – Poll type, 'quiz' or 'regular', defaults to 'regular'.
• allows_multiple_answers (bool, optional) – True, if the poll allows multiple an-
swers, ignored for polls in quiz mode, defaults to False.
• correct_option_id (int, optional) – 0-based identifier of the correct answer op-
tion, required for polls in quiz mode.
• explanation (str, optional) – 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 (str, optional) – Mode for parsing entities in the ex-
planation. See the constants in telegram.constants.ParseMode for the available
modes.
• explanation_entities (Sequence[telegram.MessageEntity], optional) – Se-
quence of special entities that appear in message text, which can be specified instead
of explanation_parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• open_period (int | datetime.timedelta, optional) – Amount of time in seconds
the poll will be active after creation, 5- 600. Can’t be used together with close_date.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• close_date (int | datetime.datetime, optional) – 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. For timezone naive
datetime.datetime objects, the default timezone of the bot will be used, which is
UTC unless telegram.ext.Defaults.tzinfo is used.
• is_closed (bool, optional) – Pass True, if the poll needs to be immediately closed.
This can be useful for poll preview.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.

6.1. telegram package 129

python-telegram-bot Documentation, Release 22.0

• reply_parameters (telegram.ReplyParameters, optional) – Description of the

message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• question_parse_mode (str, optional) – Mode for parsing entities in the question.
See the constants in telegram.constants.ParseMode for the available modes. Cur-
rently, only custom emoji entities are allowed.
Added in version 21.2.
• question_entities (Sequence[telegram.Message], optional) – Special en-
tities that appear in the poll question. It can be specified instead of
question_parse_mode.
Added in version 21.2.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.

130 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_sticker(chat_id, sticker, disable_notification=None, reply_markup=None,

protect_content=None, message_thread_id=None, emoji=None,
reply_parameters=None, business_connection_id=None,
message_effect_id=None, allow_paid_broadcast=None, *,
allow_sending_without_reply=None, reply_to_message_id=None,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to send static .WEBP, animated .TGS, or video .WEBM stickers.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_sticker()
• telegram.ChatFullInfo.send_sticker()
• telegram.Message.reply_sticker()
• telegram.User.send_sticker()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• sticker (str | file object | InputFile | bytes | pathlib.Path | telegram.
Sticker) – Sticker to send. Pass a file_id as String to send a file that exists on
the Telegram servers (recommended), pass an HTTP URL as a String for Telegram
to get a file from the Internet, or upload a new one. To upload a file, you can either
pass a file object (e.g. open("filename", "rb")), the file contents as bytes or the
path of the file (as string or pathlib.Path object). In the latter case, the file contents
will either be read as bytes or the file path will be passed to Telegram, depending on
the local_mode setting. Video stickers can only be sent by a file_id. Video and
animated stickers can’t be sent via an HTTP URL.
Lastly you can pass an existing telegram.Sticker object to send.
Changed in version 13.2: Accept bytes as input.
Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• emoji (str, optional) – Emoji associated with the sticker; only for just uploaded stick-
ers
Added in version 20.2.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.

6.1. telegram package 131

python-telegram-bot Documentation, Release 22.0

• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.

132 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• pool_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_venue(chat_id, latitude=None, longitude=None, title=None, address=None,

foursquare_id=None, disable_notification=None, reply_markup=None,
foursquare_type=None, google_place_id=None, google_place_type=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, venue=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to send information about a venue.

 Note

• You can either supply venue, or latitude, longitude, title and address and op-
tionally foursquare_id and foursquare_type or optionally google_place_id and
google_place_type.
• Foursquare details and Google Place details are mutually exclusive. However, this behaviour
is undocumented and might be changed by Telegram.

 Shortcuts

• telegram.Chat.send_venue()
• telegram.ChatFullInfo.send_venue()
• telegram.Message.reply_venue()
• telegram.User.send_venue()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• latitude (float, optional) – Latitude of venue.
• longitude (float, optional) – Longitude of venue.
• title (str, optional) – Name of the venue.
• address (str, optional) – Address of the venue.
• foursquare_id (str, optional) – Foursquare identifier of the venue.

6.1. telegram package 133

python-telegram-bot Documentation, Release 22.0

• foursquare_type (str, optional) – Foursquare type of the venue, if known.

(For example, “arts_entertainment/default”, “arts_entertainment/aquarium” or
“food/icecream”.)
• google_place_id (str, optional) – Google Places identifier of the venue.
• google_place_type (str, optional) – Google Places type of the venue. (See sup-
ported types.)
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.

134 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• venue (telegram.Venue, optional) – The venue to send.

• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async send_video(chat_id, video, duration=None, caption=None, disable_notification=None,

reply_markup=None, width=None, height=None, parse_mode=None,
supports_streaming=None, caption_entities=None, protect_content=None,
message_thread_id=None, has_spoiler=None, thumbnail=None,
reply_parameters=None, business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, show_caption_above_media=None, cover=None,
start_timestamp=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent
as Document).
Bots can currently send video files of up to 50 MB in size, this limit may be changed in the future.

 Note

thumbnail will be ignored for small video files, for which Telegram can easily generate thumb-
nails. However, this behaviour is undocumented and might be changed by Telegram.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_video()
• telegram.ChatFullInfo.send_video()
• telegram.Message.reply_video()
• telegram.User.send_video()

6.1. telegram package 135

python-telegram-bot Documentation, Release 22.0

Changed in version 20.5: Removed deprecated argument thumb. Use thumbnail instead.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• video (str | file object | InputFile | bytes | pathlib.Path | telegram.Video) –
Video file to send. Pass a file_id as String to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get a file from
the Internet, or upload a new one. To upload a file, you can either pass a file object
(e.g. open("filename", "rb")), the file contents as bytes or the path of the file (as
string or pathlib.Path object). In the latter case, the file contents will either be read
as bytes or the file path will be passed to Telegram, depending on the local_mode
setting. Lastly you can pass an existing telegram.Video object to send.
Changed in version 13.2: Accept bytes as input.
Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• duration (int | datetime.timedelta, optional) – Duration of sent video in sec-
onds.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• width (int, optional) – Video width.
• height (int, optional) – Video height.
• cover (file object | bytes | pathlib.Path | str, optional) – Cover for the video
in the message. Pass a file_id as String to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get a file from
the Internet, or upload a new one. To upload a file, you can either pass a file object
(e.g. open("filename", "rb")) or the file contents as bytes. If the bot is running
in local_mode, passing the path of the file (as string or pathlib.Path object) is
supported as well.
Added in version 21.11.
• start_timestamp (int, optional) – Start timestamp for the video in the message.
Added in version 21.11.
• caption (str, optional) – Video caption (may also be used when resending videos
by file_id), 0-1024 characters after entities parsing.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• supports_streaming (bool, optional) – Pass True, if the uploaded video is suitable
for streaming.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.

136 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• has_spoiler (bool, optional) – Pass True if the video needs to be covered with a
spoiler animation.
Added in version 20.0.
• thumbnail (file object | bytes | pathlib.Path | str, optional) – Thumbnail of the
file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumb-
nail’s width and height should not exceed 320. Ignored if the file is not uploaded
using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a
new file. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")), the file contents as bytes or the path of the file (as string or pathlib.Path
object). In the latter case, the file contents will either be read as bytes or the file path
will be passed to Telegram, depending on the local_mode setting.
Added in version 20.2.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
• show_caption_above_media (bool, optional) – Pass True, if the caption must be
shown above the message media.
Added in version 21.3.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for

6.1. telegram package 137

python-telegram-bot Documentation, Release 22.0

Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the video, when uploading a new
file. Convenience parameter, useful e.g. when sending files generated by the tempfile
module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –
async send_video_note(chat_id, video_note, duration=None, length=None,
disable_notification=None, reply_markup=None, protect_content=None,
message_thread_id=None, thumbnail=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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.

 Note

thumbnail will be ignored for small video files, for which Telegram can easily generate thumb-
nails. However, this behaviour is undocumented and might be changed by Telegram.

 See also

Working with Files and Media

138 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

 Shortcuts

• telegram.Chat.send_video_note()
• telegram.ChatFullInfo.send_video_note()
• telegram.Message.reply_video_note()
• telegram.User.send_video_note()

Changed in version 20.5: Removed deprecated argument thumb. Use thumbnail instead.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• video_note (str | file object | InputFile | bytes | pathlib.Path | telegram.
VideoNote) – Video note to send. Pass a file_id as String to send a video note
that exists on the Telegram servers (recommended) or upload a new video us-
ing multipart/form-data. To upload a file, you can either pass a file object (e.g.
open("filename", "rb")), the file contents as bytes or the path of the file (as string
or pathlib.Path object). In the latter case, the file contents will either be read as
bytes or the file path will be passed to Telegram, depending on the local_mode set-
ting. Lastly you can pass an existing telegram.VideoNote object to send. Sending
video notes by a URL is currently unsupported.
Changed in version 13.2: Accept bytes as input.
Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• duration (int | datetime.timedelta, optional) – Duration of sent video in sec-
onds.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• length (int, optional) – Video width and height, i.e. diameter of the video message.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• thumbnail (file object | bytes | pathlib.Path | str, optional) – Thumbnail of the
file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumb-
nail’s width and height should not exceed 320. Ignored if the file is not uploaded
using multipart/form-data. Thumbnails can’t be reused and can be only uploaded as a
new file. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")), the file contents as bytes or the path of the file (as string or pathlib.Path

6.1. telegram package 139

python-telegram-bot Documentation, Release 22.0

object). In the latter case, the file contents will either be read as bytes or the file path
will be passed to Telegram, depending on the local_mode setting.
Added in version 20.2.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the video note, when uploading
a new file. Convenience parameter, useful e.g. when sending files generated by the
tempfile module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

140 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-

gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –
async send_voice(chat_id, voice, duration=None, caption=None, disable_notification=None,
reply_markup=None, parse_mode=None, caption_entities=None,
protect_content=None, message_thread_id=None, reply_parameters=None,
business_connection_id=None, message_effect_id=None,
allow_paid_broadcast=None, *, allow_sending_without_reply=None,
reply_to_message_id=None, filename=None, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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 , or in .MP3 format,
or in .M4A format (other formats may be sent as Audio or Document). Bots can currently send voice
messages of up to 50 MB in size, this limit may be changed in the future.

 Note

To use this method, the file must have the type audio/ogg and be no more than 1 MB in size. 1
MB- 20 MB voice notes will be sent as files.

 See also

Working with Files and Media

 Shortcuts

• telegram.Chat.send_voice()
• telegram.ChatFullInfo.send_voice()
• telegram.Message.reply_voice()
• telegram.User.send_voice()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• voice (str | file object | InputFile | bytes | pathlib.Path | telegram.Voice) –
Voice file to send. Pass a file_id as String to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get a file from
the Internet, or upload a new one. To upload a file, you can either pass a file object
(e.g. open("filename", "rb")), the file contents as bytes or the path of the file (as
string or pathlib.Path object). In the latter case, the file contents will either be read
as bytes or the file path will be passed to Telegram, depending on the local_mode
setting. Lastly you can pass an existing telegram.Voice object to send.

6.1. telegram package 141

python-telegram-bot Documentation, Release 22.0

Changed in version 13.2: Accept bytes as input.

Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
• caption (str, optional) – Voice message caption, 0-1024 characters after entities
parsing.
• parse_mode (str, optional) – Mode for parsing entities. See telegram.
constants.ParseMode and formatting options for more details.
• caption_entities (Sequence[telegram.MessageEntity], optional) – Sequence
of special entities that appear in the caption, which can be specified instead of
parse_mode.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• duration (int | datetime.timedelta, optional) – Duration of the voice message
in seconds.
Changed in version 21.11: datetime.timedelta objects are accepted in addition to
plain int values.
• disable_notification (bool, optional) – Sends the message silently. Users will
receive a notification with no sound.
• protect_content (bool, optional) – Protects the contents of the sent message from
forwarding and saving.
Added in version 13.10.
• message_thread_id (int, optional) – Unique identifier for the target message thread
(topic) of the forum; for forum supergroups only.
Added in version 20.0.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply, optional) – Additional interface op-
tions. An object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• reply_parameters (telegram.ReplyParameters, optional) – Description of the
message to reply to.
Added in version 20.8.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be sent.
Added in version 21.1.
• message_effect_id (str, optional) – Unique identifier of the message effect to be
added to the message; for private chats only.
Added in version 21.3.
• allow_paid_broadcast (bool, optional) – Pass True to allow up to 1000 messages
per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message.
The relevant Stars will be withdrawn from the bot’s balance.
Added in version 21.7.
Keyword Arguments
• allow_sending_without_reply (bool, optional) – Pass True, if the message
should be sent even if the specified replied-to message is not found. Mutually exclusive
with reply_parameters, which this is a convenience parameter for

142 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• reply_to_message_id (int, optional) – If the message is a reply, ID of the original
message. Mutually exclusive with reply_parameters, which this is a convenience
parameter for
Changed in version 20.8: Bot API 7.0 introduced reply_parameters replacing this
argument. PTB will automatically convert this argument to that one, but you should
update your code to use the new argument.
Changed in version 21.0: This argument is now a keyword-only argument.
• filename (str, optional) – Custom file name for the voice, when uploading a new file.
Convenience parameter, useful e.g. when sending files generated by the tempfile
module.
Added in version 13.1.
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the sent Message is returned.
Return type
telegram.Message
Raises
telegram.error.TelegramError –

async setChatAdministratorCustomTitle(chat_id, user_id, custom_title, *, read_timeout=None,

write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for set_chat_administrator_custom_title()
async setChatDescription(chat_id, description=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_chat_description()
async setChatMenuButton(chat_id=None, menu_button=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_chat_menu_button()
async setChatPermissions(chat_id, permissions, use_independent_chat_permissions=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)

6.1. telegram package 143

python-telegram-bot Documentation, Release 22.0

Alias for set_chat_permissions()

async setChatPhoto(chat_id, photo, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_chat_photo()
async setChatStickerSet(chat_id, sticker_set_name, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_chat_sticker_set()
async setChatTitle(chat_id, title, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_chat_title()
async setCustomEmojiStickerSetThumbnail(name, custom_emoji_id=None, *,
read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_custom_emoji_sticker_set_thumbnail()
async setGameScore(user_id, score, chat_id=None, message_id=None, inline_message_id=None,
force=None, disable_edit_message=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_game_score()
async setMessageReaction(chat_id, message_id, reaction=None, is_big=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for set_message_reaction()
async setMyCommands(commands, scope=None, language_code=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_my_commands()
async setMyDefaultAdministratorRights(rights=None, for_channels=None, *,
read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_my_default_administrator_rights()
async setMyDescription(description=None, language_code=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_my_description()
async setMyName(name=None, language_code=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_my_name()
async setMyShortDescription(short_description=None, language_code=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for set_my_short_description()
async setPassportDataErrors(user_id, errors, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_passport_data_errors()

144 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

async setStickerEmojiList(sticker, emoji_list, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_sticker_emoji_list()
async setStickerKeywords(sticker, keywords=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_sticker_keywords()
async setStickerMaskPosition(sticker, mask_position=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_sticker_mask_position()
async setStickerPositionInSet(sticker, position, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_sticker_position_in_set()
async setStickerSetThumbnail(name, user_id, format, thumbnail=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_sticker_set_thumbnail()
async setStickerSetTitle(name, title, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for set_sticker_set_title()
async setUserEmojiStatus(user_id, emoji_status_custom_emoji_id=None,
emoji_status_expiration_date=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for set_user_emoji_status()
async setWebhook(url, certificate=None, max_connections=None, allowed_updates=None,
ip_address=None, drop_pending_updates=None, secret_token=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for set_webhook()
async set_chat_administrator_custom_title(chat_id, user_id, custom_title, *,
read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to set a custom title for administrators promoted by the bot in a supergroup. The bot
must be an administrator for this to work.

 Shortcuts

• telegram.Chat.set_administrator_custom_title()
• telegram.ChatFullInfo.set_administrator_custom_title()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• user_id (int) – Unique identifier of the target administrator.
• custom_title (str) – New custom title for the administrator; 0-16 characters, emoji
are not allowed.

6.1. telegram package 145

python-telegram-bot Documentation, Release 22.0

Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async set_chat_description(chat_id, description=None, *, read_timeout=None,

write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to change the description of a group, 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.

 Shortcuts

• telegram.Chat.set_description()
• telegram.ChatFullInfo.set_description()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• description (str, optional) – New chat description, 0-255 characters.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.

146 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Return type
bool
Raises
telegram.error.TelegramError –

async set_chat_menu_button(chat_id=None, menu_button=None, *, read_timeout=None,

write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to change the bot’s menu button in a private chat, or the default menu button.

 See also

get_chat_menu_button(), telegram.Chat.get_menu_button() telegram.User.

get_menu_button()

 Shortcuts

• telegram.Chat.set_menu_button()
• telegram.ChatFullInfo.set_menu_button()
• telegram.User.set_menu_button()

Added in version 20.0.

Parameters
• chat_id (int, optional) – Unique identifier for the target private chat. If not specified,
default bot’s menu button will be changed
• menu_button (telegram.MenuButton, optional) – An object for the new bot’s menu
button. Defaults to telegram.MenuButtonDefault.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
async set_chat_permissions(chat_id, permissions, use_independent_chat_permissions=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to set default chat permissions for all members. The bot must be an administrator in the

6.1. telegram package 147

python-telegram-bot Documentation, Release 22.0

group or a supergroup for this to work and must have the telegram.ChatMemberAdministrator.
can_restrict_members admin rights.

 Shortcuts

• telegram.Chat.set_permissions()
• telegram.ChatFullInfo.set_permissions()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• permissions (telegram.ChatPermissions) – New default chat permissions.
• use_independent_chat_permissions (bool, optional) – Pass True if chat
permissions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos,
can_send_videos, can_send_video_notes, and can_send_voice_notes
permissions; the can_send_polls permission will imply the can_send_messages
permission.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async set_chat_photo(chat_id, photo, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
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.

 Shortcuts

• telegram.Chat.set_photo()
• telegram.ChatFullInfo.set_photo()

148 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• photo (file object | bytes | pathlib.Path) – New chat photo. To upload a file, you
can either pass a file object (e.g. open("filename", "rb")), the file contents as
bytes or the path of the file (as string or pathlib.Path object). In the latter case, the
file contents will either be read as bytes or the file path will be passed to Telegram,
depending on the local_mode setting.
Changed in version 13.2: Accept bytes as input.
Changed in version 20.0: File paths as input is also accepted for bots not running in
local_mode.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async set_chat_sticker_set(chat_id, sticker_set_name, *, read_timeout=None,

write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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 telegram.
ChatFullInfo.can_set_sticker_set optionally returned in get_chat() requests to check if the
bot can use this method.
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• sticker_set_name (str) – Name of the sticker set to be set as the group sticker set.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 149

python-telegram-bot Documentation, Release 22.0

• connect_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
async set_chat_title(chat_id, title, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
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.

 Shortcuts

• telegram.Chat.set_title()
• telegram.ChatFullInfo.set_title()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• title (str) – New chat title, 1- 128 characters.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async set_custom_emoji_sticker_set_thumbnail(name, custom_emoji_id=None, *,

read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)

150 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Use this method to set the thumbnail of a custom emoji sticker set.
Added in version 20.2.
Parameters
• name (str) – Sticker set name.
• custom_emoji_id (str, optional) – Custom emoji identifier of a sticker from the
sticker set; pass an empty string to drop the thumbnail and use the first sticker as the
thumbnail.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_game_score(user_id, score, chat_id=None, message_id=None, inline_message_id=None,
force=None, disable_edit_message=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to set the score of the specified user in a game message.

 See also

telegram.Game.text

 Shortcuts

• telegram.CallbackQuery.set_game_score()
• telegram.Message.set_game_score()

Parameters
• user_id (int) – User identifier.
• score (int) – New score, must be non-negative.
• force (bool, optional) – Pass True, if the high score is allowed to decrease. This can
be useful when fixing mistakes or banning cheaters.

6.1. telegram package 151

python-telegram-bot Documentation, Release 22.0

• disable_edit_message (bool, optional) – Pass True, if the game message should

not be automatically edited to include the current scoreboard.
• chat_id (int, optional) – Required if inline_message_id is not specified. Unique
identifier for the target chat.
• message_id (int, optional) – Required if inline_message_id is not specified.
Identifier of the sent message.
• inline_message_id (str, optional) – Required if chat_id and message_id are
not specified. Identifier of the inline message.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
The edited message. If the message is not an inline message , True.
Return type
telegram.Message
Raises
telegram.error.TelegramError – If the new score is not greater than the user’s cur-
rent score in the chat and force is False.

async set_message_reaction(chat_id, message_id, reaction=None, is_big=None, *,

read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to change the chosen reactions on a message. Service messages of some types can’t
be reacted to. Automatically forwarded messages from a channel to its discussion group have the same
available reactions as messages in the channel. Bots can’t use paid reactions.

 Shortcuts

• telegram.Chat.set_message_reaction()
• telegram.ChatFullInfo.set_message_reaction()
• telegram.Message.set_reaction()

Added in version 20.8.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• message_id (int) – Identifier of the target message. If the message belongs to a
media group, the reaction is set to the first non-deleted message in the group instead.

152 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• reaction (Sequence[telegram.ReactionType | str] | telegram.ReactionType

| str, optional) – A list of reaction types to set on the message. Currently, as non-
premium users, bots can set up to one reaction per message. A custom emoji reaction
can be used if it is either already present on the message or explicitly allowed by chat
administrators. Paid reactions can’t be used by bots.

 Tip

Passed str values will be converted to either telegram.ReactionTypeEmoji or

telegram.ReactionTypeCustomEmoji depending on whether they are listed in
ReactionEmoji.

• is_big (bool, optional) – Pass True to set the reaction with a big animation.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
bool On success, True is returned.
Raises
telegram.error.TelegramError –
async set_my_commands(commands, scope=None, language_code=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to change the list of the bot’s commands. See the Telegram docs for more details about
bot commands.

 See also

get_my_commands(), delete_my_commands()

Parameters
• commands (Sequence[BotCommand | (str, str)]) – A sequence of bot commands to
be set as the list of the bot’s commands. At most 100 commands can be specified.

 Note

If you pass in a sequence of tuple, the order of elements in each tuple must
correspond to the order of positional arguments to create a BotCommand instance.

Changed in version 20.0: Accepts any collections.abc.Sequence as input instead

of just a list.

6.1. telegram package 153

python-telegram-bot Documentation, Release 22.0

• scope (telegram.BotCommandScope, optional) – An object, describing scope

of users for which the commands are relevant. Defaults to telegram.
BotCommandScopeDefault.
Added in version 13.7.
• language_code (str, optional) – A two-letter ISO 639-1 language code. If empty,
commands will be applied to all users from the given scope, for whose language there
are no dedicated commands.
Added in version 13.7.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async set_my_default_administrator_rights(rights=None, for_channels=None, *,

read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to change the default administrator rights requested by the bot when it’s added as an
administrator to groups or channels. These rights will be suggested to users, but they are free to modify
the list before adding the bot.

 See also

get_my_default_administrator_rights()

Added in version 20.0.

Parameters
• rights (telegram.ChatAdministratorRights, optional) – A telegram.
ChatAdministratorRights object describing new default administrator rights. If
not specified, the default administrator rights will be cleared.
• for_channels (bool, optional) – Pass True to change the default administrator rights
of the bot in channels. Otherwise, the default administrator rights of the bot for groups
and supergroups will be changed.
Keyword Arguments

154 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• read_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
Returns True on success.
Return type
bool
Raises
telegram.error.TelegramError –
async set_my_description(description=None, language_code=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to change the bot’s description, which is shown in the chat with the bot if the chat is
empty.
Added in version 20.2.
Parameters
• description (str, optional) – New bot description; 0-512 characters. Pass an empty
string to remove the dedicated description for the given language.
• language_code (str, optional) – A two-letter ISO 639-1 language code. If empty,
the description will be applied to all users for whose language there is no dedicated
description.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

6.1. telegram package 155

python-telegram-bot Documentation, Release 22.0

async set_my_name(name=None, language_code=None, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to change the bot’s name.
Added in version 20.3.
Parameters
• name (str, optional) – New bot name; 0-64 characters. Pass an empty string to remove
the dedicated name for the given language.

 Caution

If language_code is not specified, a name must be specified.

• language_code (str, optional) – A two-letter ISO 639-1 language code. If empty,

the name will be applied to all users for whose language there is no dedicated name.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_my_short_description(short_description=None, language_code=None, *,
read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to change the bot’s short description, which is shown on the bot’s profile page and is
sent together with the link when users share the bot.
Added in version 20.2.
Parameters
• short_description (str, optional) – New short description for the bot; 0-120 char-
acters. Pass an empty string to remove the dedicated description for the given language.
• language_code (str, optional) – A two-letter ISO 639-1 language code. If empty,
the description will be applied to all users for whose language there is no dedicated
description.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.

156 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• write_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_passport_data_errors(user_id, errors, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
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).
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.
Parameters
• user_id (int) – User identifier
• errors (Sequence[PassportElementError]) – A Sequence describing the errors.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

6.1. telegram package 157

python-telegram-bot Documentation, Release 22.0

async set_sticker_emoji_list(sticker, emoji_list, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to change the list of emoji assigned to a regular or custom emoji sticker. The sticker
must belong to a sticker set created by the bot.
Added in version 20.2.
Parameters
• sticker (str | Sticker) – File identifier of the sticker or the sticker object.
Changed in version 21.10: Accepts also telegram.Sticker instances.
• emoji_list (Sequence[str]) – A sequence of 1- 20 emoji associated with the sticker.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_sticker_keywords(sticker, keywords=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to change search keywords assigned to a regular or custom emoji sticker. The sticker
must belong to a sticker set created by the bot.
Added in version 20.2.
Parameters
• sticker (str | Sticker) – File identifier of the sticker or the sticker object.
Changed in version 21.10: Accepts also telegram.Sticker instances.
• keywords (Sequence[str]) – A sequence of 0-20 search keywords for the sticker with
total length up to 64 characters.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

158 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-

gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_sticker_mask_position(sticker, mask_position=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to change the mask position of a mask sticker. The sticker must belong to a sticker set
that was created by the bot.
Added in version 20.2.
Parameters
• sticker (str | Sticker) – File identifier of the sticker or the sticker object.
Changed in version 21.10: Accepts also telegram.Sticker instances.
• mask_position (telegram.MaskPosition, optional) – A object with the position
where the mask should be placed on faces. Omit the parameter to remove the mask
position.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_sticker_position_in_set(sticker, position, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to move a sticker in a set created by the bot to a specific position.
Parameters
• sticker (str | Sticker) – File identifier of the sticker or the sticker object.
Changed in version 21.10: Accepts also telegram.Sticker instances.
• position (int) – New sticker position in the set, zero-based.

6.1. telegram package 159

python-telegram-bot Documentation, Release 22.0

Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_sticker_set_thumbnail(name, user_id, format, thumbnail=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to set the thumbnail of a regular or mask sticker set. The format of the thumbnail file
must match the format of the stickers in the set.
Added in version 20.2.
Changed in version 21.1: As per Bot API 7.2, the new argument format will be required, and thus the
order of the arguments had to be changed.
Parameters
• name (str) – Sticker set name
• user_id (int) – User identifier of created sticker set owner.
• format (str) – Format of the added sticker, must be one of 'static' for a .WEBP or
.PNG image, 'animated' for a .TGS animation, 'video' for a .WEBM video.
Added in version 21.1.
• thumbnail (str | file object | InputFile | bytes | pathlib.Path, optional) – A
.WEBP or .PNG image with the thumbnail, must be up to 128 kilobytes in size and
have width and height of exactly 100 px, or a .TGS animation with the thumbnail up
to 32 kilobytes in size; see the docs for animated sticker technical requirements, or a
.WEBM video with the thumbnail up to 32 kilobytes in size; see this for video sticker
technical requirements.
Pass a file_id as String to send a file that exists on the Telegram servers (recom-
mended), pass an HTTP URL as a String for Telegram to get a file from the Inter-
net, or upload a new one. To upload a file, you can either pass a file object (e.g.
open("filename", "rb")), the file contents as bytes or the path of the file (as string
or pathlib.Path object). In the latter case, the file contents will either be read as
bytes or the file path will be passed to Telegram, depending on the local_mode set-
ting.
Animated and video sticker set thumbnails can’t be uploaded via HTTP URL. If omit-
ted, then the thumbnail is dropped and the first sticker is used as the thumbnail.
Keyword Arguments

160 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• read_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_sticker_set_title(name, title, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Use this method to set the title of a created sticker set.
Added in version 20.2.
Parameters
• name (str) – Sticker set name.
• title (str) – Sticker set title, 1- 64 characters.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_user_emoji_status(user_id, emoji_status_custom_emoji_id=None,
emoji_status_expiration_date=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Changes the emoji status for a given user that previously allowed the bot to manage their emoji status
via the Mini App method requestEmojiStatusAccess .

6.1. telegram package 161

python-telegram-bot Documentation, Release 22.0

Added in version 21.8.

Parameters
• user_id (int) – Unique identifier of the target user
• emoji_status_custom_emoji_id (str, optional) – Custom emoji identifier of the
emoji status to set. Pass an empty string to remove the status.
• emoji_status_expiration_date (Union[int, datetime.datetime], optional) –
Expiration date of the emoji status, if any, as unix timestamp or datetime.datetime
object. For timezone naive datetime.datetime objects, the default timezone of the
bot will be used, which is UTC unless telegram.ext.Defaults.tzinfo is used.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async set_webhook(url, certificate=None, max_connections=None, allowed_updates=None,
ip_address=None, drop_pending_updates=None, secret_token=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever
there is an update for the bot, Telegram will send an HTTPS POST request to the specified url, con-
taining An Update. In case of an unsuccessful request (a request with response HTTP status code
<https://en.wikipedia.org/wiki/List_of_HTTP_status_codes>`_different from ``2XY`), Telegram will
repeat the request and give up after a reasonable amount of attempts.
If you’d like to make sure that the Webhook was set by you, you can specify secret
data in the parameter secret_token. If specified, the request will contain a header
X-Telegram-Bot-Api-Secret-Token with the secret token as content.

 Note

1. You will not be able to receive updates using get_updates() for long as an outgoing web-
hook is set up.
2. To use a self-signed certificate, you need to upload your public key certificate using
certificate parameter. Please upload as InputFile, sending a String will not work.
3. Ports currently supported for Webhooks: telegram.constants.
SUPPORTED_WEBHOOK_PORTS.

162 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

If you’re having any trouble setting up webhooks, please check out this guide to Webhooks.

 See also

telegram.ext.Application.run_webhook(), telegram.ext.Updater.
start_webhook()

 Examples

Custom Webhook Bot

Parameters
• url (str) – HTTPS url to send updates to. Use an empty string to remove webhook
integration.
• certificate (file object | bytes | pathlib.Path | str) – Upload your public key
certificate so that the root certificate in use can be checked. See our self-signed guide
for details. To upload a file, you can either pass a file object (e.g. open("filename",
"rb")) or the file contents as bytes. If the bot is running in local_mode, passing the
path of the file (as string or pathlib.Path object) is supported as well.
• ip_address (str, optional) – The fixed IP address which will be used to send web-
hook requests instead of the IP address resolved through DNS.
• max_connections (int, optional) – 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.
• allowed_updates (Sequence[str], optional) – A sequence of the types of
updates you want your bot to receive. For example, specify [“message”,
“edited_channel_post”, “callback_query”] to only receive updates of these types. See
telegram.Update for a complete list of available update types. Specify an empty se-
quence to receive all updates except telegram.Update.chat_member, telegram.
Update.message_reaction and telegram.Update.message_reaction_count
(default). If not specified, the previous setting will be used. Please note that this pa-
rameter doesn’t affect updates created before the call to the set_webhook, so unwanted
update may be received for a short period of time.
Changed in version 20.0: Accepts any collections.abc.Sequence as input instead
of just a list.
• drop_pending_updates (bool, optional) – Pass True to drop all pending updates.
• secret_token (str, optional) – A secret token to be sent in a header
X-Telegram-Bot-Api-Secret-Token in every webhook request, 1- 256 characters.
Only characters A-Z, a-z, 0-9, _ and - are allowed. The header is useful to ensure
that the request comes from a webhook set by you.
Added in version 20.0.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 163

python-telegram-bot Documentation, Release 22.0

• connect_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
bool On success, True is returned.
Raises
telegram.error.TelegramError –

async shutdown()
Stop & clear resources used by this class. Currently just calls telegram.request.BaseRequest.
shutdown() for the request objects used by this bot.

 See also

initialize()

Added in version 20.0.

async stopMessageLiveLocation(chat_id=None, message_id=None, inline_message_id=None,
reply_markup=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for stop_message_live_location()
async stopPoll(chat_id, message_id, reply_markup=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for stop_poll()
async stop_message_live_location(chat_id=None, message_id=None, inline_message_id=None,
reply_markup=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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.

 Shortcuts

• telegram.CallbackQuery.stop_message_live_location()
• telegram.Message.stop_live_location()

Parameters
• chat_id (int | str, optional) – Required if inline_message_id is not specified.
Unique identifier for the target chat or username of the target channel (in the format
@channelusername).
• message_id (int, optional) – Required if inline_message_id is not specified.
Identifier of the sent message with live location to stop.

164 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• inline_message_id (str, optional) – Required if chat_id and message_id are

not specified. Identifier of the inline message.
• reply_markup (telegram.InlineKeyboardMarkup, optional) – An object for a
new inline keyboard.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message to be edited was sent
Added in version 21.4.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, if edited message is not an inline message, the edited message is returned,
otherwise True is returned.
Return type
telegram.Message

async stop_poll(chat_id, message_id, reply_markup=None, business_connection_id=None, *,

read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to stop a poll which was sent by the bot.

 Shortcuts

telegram.Message.stop_poll()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• message_id (int) – Identifier of the original message with the poll.
• reply_markup (telegram.InlineKeyboardMarkup, optional) – An object for a
new message inline keyboard.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message to be edited was sent
Added in version 21.4.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 165

python-telegram-bot Documentation, Release 22.0

• connect_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the stopped Poll is returned.
Return type
telegram.Poll
Raises
telegram.error.TelegramError –

property supports_inline_queries
Bot’s telegram.User.supports_inline_queries attribute. Shortcut for the corresponding at-
tribute of bot.
Type
bool
to_dict(recursive=True)
See telegram.TelegramObject.to_dict().
property token
Bot’s unique authentication token.
Added in version 20.0.
Type
str
async unbanChatMember(chat_id, user_id, only_if_banned=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for unban_chat_member()
async unbanChatSenderChat(chat_id, sender_chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for unban_chat_sender_chat()
async unban_chat_member(chat_id, user_id, only_if_banned=None, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
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.

 Shortcuts

• telegram.Chat.unban_member()
• telegram.ChatFullInfo.unban_member()

Parameters

166 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• user_id (int) – Unique identifier of the target user.
• only_if_banned (bool, optional) – Do nothing if the user is not banned.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async unban_chat_sender_chat(chat_id, sender_chat_id, *, read_timeout=None,

write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to unban a previously banned channel in a supergroup or channel. The bot must be an
administrator for this to work and must have the appropriate administrator rights.

 Shortcuts

• telegram.Chat.unban_chat()
• telegram.Chat.unban_sender_chat()
• telegram.ChatFullInfo.unban_chat()
• telegram.ChatFullInfo.unban_sender_chat()

Added in version 13.9.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• sender_chat_id (int) – Unique identifier of the target sender chat.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 167

python-telegram-bot Documentation, Release 22.0

• connect_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async unhideGeneralForumTopic(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for unhide_general_forum_topic()
async unhide_general_forum_topic(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to unhide the ‘General’ topic in a forum supergroup chat. The bot must be an admin-
istrator in the chat for this to work and must have can_manage_topics administrator rights.

 Shortcuts

• telegram.Chat.unhide_general_forum_topic()
• telegram.ChatFullInfo.unhide_general_forum_topic()

Added in version 20.0.

Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

168 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

async unpinAllChatMessages(chat_id, *, read_timeout=None, write_timeout=None,

connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for unpin_all_chat_messages()
async unpinAllForumTopicMessages(chat_id, message_thread_id, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for unpin_all_forum_topic_messages()
async unpinAllGeneralForumTopicMessages(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for unpin_all_general_forum_topic_messages()
async unpinChatMessage(chat_id, message_id=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Alias for unpin_chat_message()
async unpin_all_chat_messages(chat_id, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
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.

 Shortcuts

• telegram.Chat.unpin_all_messages()
• telegram.ChatFullInfo.unpin_all_messages()
• telegram.User.unpin_all_messages()

Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

6.1. telegram package 169

python-telegram-bot Documentation, Release 22.0

async unpin_all_forum_topic_messages(chat_id, message_thread_id, *, read_timeout=None,

write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to clear the list of pinned messages in a forum topic. The bot must be an administrator
in the chat for this to work and must have can_pin_messages administrator rights in the supergroup.

 Shortcuts

• telegram.Chat.unpin_all_forum_topic_messages()
• telegram.ChatFullInfo.unpin_all_forum_topic_messages()
• telegram.Message.unpin_all_forum_topic_messages()

Added in version 20.0.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• message_thread_id (int) – Unique identifier for the target message thread of the
forum topic.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async unpin_all_general_forum_topic_messages(chat_id, *, read_timeout=None,
write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Use this method to clear the list of pinned messages in a General forum topic. The bot must be an
administrator in the chat for this to work and must have can_pin_messages administrator rights in
the supergroup.

 Shortcuts

• telegram.Chat.unpin_all_general_forum_topic_messages()
• telegram.ChatFullInfo.unpin_all_general_forum_topic_messages()

170 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

Added in version 20.5.

Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async unpin_chat_message(chat_id, message_id=None, business_connection_id=None, *,
read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
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.

 Shortcuts

• telegram.Chat.unpin_message()
• telegram.ChatFullInfo.unpin_message()
• telegram.Message.unpin()
• telegram.User.unpin_message()

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• message_id (int, optional) – Identifier of the message to unpin. Required if
business_connection_id is specified. If not specified, the most recent pinned mes-
sage (by sending date) will be unpinned.
• business_connection_id (str, optional) – Unique identifier of the business con-
nection on behalf of which the message will be unpinned.
Added in version 21.5.
Keyword Arguments

6.1. telegram package 171

python-telegram-bot Documentation, Release 22.0

• read_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

async uploadStickerFile(user_id, sticker, sticker_format, *, read_timeout=None,

write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Alias for upload_sticker_file()
async upload_sticker_file(user_id, sticker, sticker_format, *, read_timeout=None,
write_timeout=None, connect_timeout=None, pool_timeout=None,
api_kwargs=None)
Use this method to upload a file with a sticker for later use in the create_new_sticker_set() and
add_sticker_to_set() methods (can be used multiple times).
Changed in version 20.5: Removed deprecated parameter png_sticker.
Parameters
• user_id (int) – User identifier of sticker file owner.
• sticker (str | file object | InputFile | bytes | pathlib.Path) – A file with
the sticker in the ".WEBP", ".PNG", ".TGS" or ".WEBM" format. See here for
technical requirements . To upload a file, you can either pass a file object (e.g.
open("filename", "rb")), the file contents as bytes or the path of the file (as string
or pathlib.Path object). In the latter case, the file contents will either be read as
bytes or the file path will be passed to Telegram, depending on the local_mode set-
ting.
Added in version 20.2.
• sticker_format (str) – Format of the sticker. Must be one of telegram.
constants.StickerFormat.STATIC, telegram.constants.StickerFormat.
ANIMATED, telegram.constants.StickerFormat.VIDEO.
Added in version 20.2.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. By default, 20 seconds are used as write time-
out.
Changed in version 22.0: The default value changed to DEFAULT_NONE.

172 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

• connect_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, the uploaded File is returned.
Return type
telegram.File
Raises
telegram.error.TelegramError –
property username
Bot’s username. Shortcut for the corresponding attribute of bot.
Type
str
async verifyChat(chat_id, custom_description=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for verify_chat()
async verifyUser(user_id, custom_description=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Alias for verify_user()
async verify_chat(chat_id, custom_description=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Verifies a chat on behalf of the organization which is represented by the bot.

 Shortcuts

• telegram.Chat.verify()
• telegram.ChatFullInfo.verify()

Added in version 21.10.

Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername).
• custom_description (str, optional) – Custom description for the verification; 0-
70 characters. Must be empty if the organization isn’t allowed to provide a custom
verification description.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.

6.1. telegram package 173

python-telegram-bot Documentation, Release 22.0

• pool_timeout (float | None, optional) – Value to pass to telegram.request.

BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –
async verify_user(user_id, custom_description=None, *, read_timeout=None, write_timeout=None,
connect_timeout=None, pool_timeout=None, api_kwargs=None)
Verifies a user on behalf of the organization which is represented by the bot.

 Shortcuts

telegram.User.verify()

Added in version 21.10.

Parameters
• user_id (int) – Unique identifier of the target user.
• custom_description (str, optional) – Custom description for the verification; 0-
70 characters. Must be empty if the organization isn’t allowed to provide a custom
verification description.
Keyword Arguments
• read_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.
• write_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.
• connect_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.
• pool_timeout (float | None, optional) – Value to pass to telegram.request.
BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.
• api_kwargs (dict, optional) – Arbitrary keyword arguments to be passed to the Tele-
gram API. See do_api_request() for limitations.
Returns
On success, True is returned.
Return type
bool
Raises
telegram.error.TelegramError –

Available Types
Animation

174 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

class telegram.Animation(file_id, file_unique_id, width, height, duration, file_name=None,

mime_type=None, file_size=None, thumbnail=None, *, api_kwargs=None)
Bases: telegram.TelegramObject
This object represents an animation file (GIF or H.264/MPEG-4 AVC video without sound).
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their file_unique_id is equal.

 Use In

• telegram.Bot.get_file()
• telegram.Bot.send_animation()

 Available In

• telegram.ExternalReplyInfo.animation
• telegram.Game.animation
• telegram.InputMediaAnimation.media
• telegram.Message.animation
• telegram.Message.effective_attachment

Changed in version 20.5: Removed the deprecated argument and attribute thumb.
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file.
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the
same over time and for different bots. Can’t be used to download or reuse the file.
• width (int) – Video width as defined by the sender.
• height (int) – Video height as defined by the sender.
• duration (int) – Duration of the video in seconds as defined by the sender.
• file_name (str, optional) – Original animation filename as defined by the sender.
• mime_type (str, optional) – MIME type of the file as defined by the sender.
• file_size (int, optional) – File size in bytes.
• thumbnail (telegram.PhotoSize, optional) – Animation thumbnail as defined by
sender.
Added in version 20.2.
file_id
Identifier for this file, which can be used to download or reuse the file.
Type
str
file_unique_id
Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t
be used to download or reuse the file.
Type
str

6.1. telegram package 175

python-telegram-bot Documentation, Release 22.0

width
Video width as defined by the sender.
Type
int
height
Video height as defined by the sender.
Type
int
duration
Duration of the video in seconds as defined by the sender.
Type
int
file_name
Optional. Original animation filename as defined by the sender.
Type
str
mime_type
Optional. MIME type of the file as defined by the sender.
Type
str
file_size
Optional. File size in bytes.
Type
int
thumbnail
Optional. Animation thumbnail as defined by sender.
Added in version 20.2.
Type
telegram.PhotoSize
__dir__()
Default dir() implementation.
__format__(format_spec, / (Positional-only parameter separator (PEP 570)))
Default object formatter.
Return str(self) if format_spec is empty. Raise TypeError otherwise.
__ge__(value, / )
Return self>=value.
__getattribute__(name, / )
Return getattr(self, name).
__gt__(value, / )
Return self>value.
classmethod __init_subclass__()
This method is called when a class is subclassed.
The default implementation does nothing. It may be overridden to extend subclasses.

176 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

__le__(value, / )
Return self<=value.
__lt__(value, / )
Return self<value.
__ne__(value, / )
Return self!=value.
classmethod __new__(*args, **kwargs)

__reduce__()
Helper for pickle.
__reduce_ex__(protocol, / )
Helper for pickle.
__sizeof__()
Size of object in memory, in bytes.
__str__()
Return str(self).
classmethod __subclasshook__(object, / )
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotIm-
plemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the
normal algorithm (and the outcome is cached).
classmethod de_json(data, bot=None)
See telegram.TelegramObject.de_json().
async get_file(*, read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Convenience wrapper over telegram.Bot.get_file()
For the documentation of the arguments, please see telegram.Bot.get_file().
Returns
telegram.File
Raises
telegram.error.TelegramError –

Audio

class telegram.Audio(file_id, file_unique_id, duration, performer=None, title=None, mime_type=None,

file_size=None, file_name=None, thumbnail=None, *, api_kwargs=None)
Bases: telegram.TelegramObject
This object represents an audio file to be treated as music by the Telegram clients.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their file_unique_id is equal.

 Use In

• telegram.Bot.get_file()
• telegram.Bot.send_audio()

6.1. telegram package 177

python-telegram-bot Documentation, Release 22.0

 Available In

• telegram.ExternalReplyInfo.audio
• telegram.InputMediaAudio.media
• telegram.Message.audio
• telegram.Message.effective_attachment

Changed in version 20.5: Removed the deprecated argument and attribute thumb.
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file.
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the
same over time and for different bots. Can’t be used to download or reuse the file.
• duration (int) – Duration of the audio in seconds as defined by the sender.
• performer (str, optional) – Performer of the audio as defined by the sender or by audio
tags.
• title (str, optional) – Title of the audio as defined by the sender or by audio tags.
• file_name (str, optional) – Original filename as defined by the sender.
• mime_type (str, optional) – MIME type of the file as defined by the sender.
• file_size (int, optional) – File size in bytes.
• thumbnail (telegram.PhotoSize, optional) – Thumbnail of the album cover to
which the music file belongs.
Added in version 20.2.
file_id
Identifier for this file, which can be used to download or reuse the file.
Type
str
file_unique_id
Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t
be used to download or reuse the file.
Type
str
duration
Duration of the audio in seconds as defined by the sender.
Type
int
performer
Optional. Performer of the audio as defined by the sender or by audio tags.
Type
str
title
Optional. Title of the audio as defined by the sender or by audio tags.
Type
str

178 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

file_name
Optional. Original filename as defined by the sender.
Type
str
mime_type
Optional. MIME type of the file as defined by the sender.
Type
str
file_size
Optional. File size in bytes.
Type
int
thumbnail
Optional. Thumbnail of the album cover to which the music file belongs.
Added in version 20.2.
Type
telegram.PhotoSize
__dir__()
Default dir() implementation.
__format__(format_spec, / )
Default object formatter.
Return str(self) if format_spec is empty. Raise TypeError otherwise.
__ge__(value, / )
Return self>=value.
__getattribute__(name, / )
Return getattr(self, name).
__gt__(value, / )
Return self>value.
classmethod __init_subclass__()
This method is called when a class is subclassed.
The default implementation does nothing. It may be overridden to extend subclasses.
__le__(value, / )
Return self<=value.
__lt__(value, / )
Return self<value.
__ne__(value, / )
Return self!=value.
classmethod __new__(*args, **kwargs)

__reduce__()
Helper for pickle.
__reduce_ex__(protocol, / )
Helper for pickle.

6.1. telegram package 179

python-telegram-bot Documentation, Release 22.0

__sizeof__()
Size of object in memory, in bytes.
__str__()
Return str(self).
classmethod __subclasshook__(object, / )
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotIm-
plemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the
normal algorithm (and the outcome is cached).
classmethod de_json(data, bot=None)
See telegram.TelegramObject.de_json().
async get_file(*, read_timeout=None, write_timeout=None, connect_timeout=None,
pool_timeout=None, api_kwargs=None)
Convenience wrapper over telegram.Bot.get_file()
For the documentation of the arguments, please see telegram.Bot.get_file().
Returns
telegram.File
Raises
telegram.error.TelegramError –

Birthdate

class telegram.Birthdate(day, month, year=None, *, api_kwargs=None)

Bases: telegram.TelegramObject
This object describes the birthdate of a user.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their day, and month are equal.

 Available In

telegram.ChatFullInfo.birthdate

Added in version 21.1.

Parameters
• day (int) – Day of the user’s birth; 1-31.
• month (int) – Month of the user’s birth; 1-12.
• year (int, optional) – Year of the user’s birth.
day
Day of the user’s birth; 1-31.
Type
int
month
Month of the user’s birth; 1-12.
Type
int

180 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

year
Optional. Year of the user’s birth.
Type
int
to_date(year=None)
Return the birthdate as a date object.
Changed in version 21.2: Now returns a datetime.date object instead of a datetime.datetime
object, as was originally intended.
Parameters
year (int, optional) – The year to use. Required, if the year was not present.
Returns
The birthdate as a date object.
Return type
datetime.date

BotCommand

class telegram.BotCommand(command, description, *, api_kwargs=None)

Bases: telegram.TelegramObject
This object represents a bot command.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their command and description are equal.

 Use In

telegram.Bot.set_my_commands()

 Returned In

telegram.Bot.get_my_commands()

Parameters
• command (str) – Text of the command; 1- 32 characters. Can contain only lowercase
English letters, digits and underscores.
• description (str) – Description of the command; 1- 256 characters.

command
Text of the command; 1- 32 characters. Can contain only lowercase English letters, digits and under-
scores.
Type
str
description
Description of the command; 1- 256 characters.
Type
str

6.1. telegram package 181

python-telegram-bot Documentation, Release 22.0

MAX_COMMAND = 32
telegram.constants.BotCommandLimit.MAX_COMMAND
Added in version 20.0.
MAX_DESCRIPTION = 256
telegram.constants.BotCommandLimit.MAX_DESCRIPTION
Added in version 20.0.
MIN_COMMAND = 1
telegram.constants.BotCommandLimit.MIN_COMMAND
Added in version 20.0.
MIN_DESCRIPTION = 1
telegram.constants.BotCommandLimit.MIN_DESCRIPTION
Added in version 20.0.

BotCommandScope

class telegram.BotCommandScope(type, *, api_kwargs=None)

Bases: telegram.TelegramObject
Base class for objects that represent the scope to which bot commands are applied. Currently, the following
7 scopes are supported:
• telegram.BotCommandScopeDefault
• telegram.BotCommandScopeAllPrivateChats
• telegram.BotCommandScopeAllGroupChats
• telegram.BotCommandScopeAllChatAdministrators
• telegram.BotCommandScopeChat
• telegram.BotCommandScopeChatAdministrators
• telegram.BotCommandScopeChatMember
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their type is equal. For subclasses with additional attributes, the notion of equality is overridden.

 Note

Please see the official docs on how Telegram determines which commands to display.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

Parameters
type (str) – Scope type.

182 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

type
Scope type.
Type
str
ALL_CHAT_ADMINISTRATORS = 'all_chat_administrators'
telegram.constants.BotCommandScopeType.ALL_CHAT_ADMINISTRATORS
ALL_GROUP_CHATS = 'all_group_chats'
telegram.constants.BotCommandScopeType.ALL_GROUP_CHATS
ALL_PRIVATE_CHATS = 'all_private_chats'
telegram.constants.BotCommandScopeType.ALL_PRIVATE_CHATS
CHAT = 'chat'
telegram.constants.BotCommandScopeType.CHAT
CHAT_ADMINISTRATORS = 'chat_administrators'
telegram.constants.BotCommandScopeType.CHAT_ADMINISTRATORS
CHAT_MEMBER = 'chat_member'
telegram.constants.BotCommandScopeType.CHAT_MEMBER
DEFAULT = 'default'
telegram.constants.BotCommandScopeType.DEFAULT
classmethod de_json(data, bot=None)
Converts JSON data to the appropriate BotCommandScope object, i.e. takes care of selecting the cor-
rect subclass.
Parameters
• data (dict[str, . . . ]) – The JSON data.
• bot (telegram.Bot, optional) – The bot associated with this object. Defaults to
None, in which case shortcut methods will not be available.
Changed in version 21.4: bot is now optional and defaults to None
Returns
The Telegram object.

BotCommandScopeAllChatAdministrators

class telegram.BotCommandScopeAllChatAdministrators(*, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering all group and supergroup chat administrators.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

type
Scope type 'all_chat_administrators'.

6.1. telegram package 183

python-telegram-bot Documentation, Release 22.0

Type
str

BotCommandScopeAllGroupChats

class telegram.BotCommandScopeAllGroupChats(*, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering all group and supergroup chats.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

type
Scope type 'all_group_chats'.
Type
str

BotCommandScopeAllPrivateChats

class telegram.BotCommandScopeAllPrivateChats(*, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering all private chats.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

type
Scope type 'all_private_chats'.
Type
str

BotCommandScopeChat

class telegram.BotCommandScopeChat(chat_id, *, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering a specific chat.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their type and chat_id are equal.

184 Chapter 6. License

 python-telegram-bot Documentation, Release 22.0

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

Parameters
chat_id (str | int) – Unique identifier for the target chat or username of the target super-
group (in the format @supergroupusername).
type
Scope type 'chat'.
Type
str
chat_id
Unique identifier for the target chat or username of the target supergroup (in the format
@supergroupusername).
Type
str | int

BotCommandScopeChatAdministrators

class telegram.BotCommandScopeChatAdministrators(chat_id, *, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering all administrators of a specific group or supergroup chat.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their type and chat_id are equal.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

Parameters
chat_id (str | int) – Unique identifier for the target chat or username of the target super-
group (in the format @supergroupusername).
type
Scope type 'chat_administrators'.
Type
str
chat_id
Unique identifier for the target chat or username of the target supergroup (in the format
@supergroupusername).

6.1. telegram package 185

python-telegram-bot Documentation, Release 22.0

Type
str | int

BotCommandScopeChatMember

class telegram.BotCommandScopeChatMember(chat_id, user_id, *, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the scope of bot commands, covering a specific member of a group or supergroup chat.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if
their type, chat_id and user_id are equal.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()
• telegram.Bot.set_my_commands()

Added in version 13.7.

Parameters
• chat_id (str | int) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername).
• user_id (int) – Unique identifier of the target user.
type
Scope type 'chat_member'.
Type
str
chat_id
Unique identifier for the target chat or username of the target supergroup (in the format
@supergroupusername).
Type
str | int
user_id
Unique identifier of the target user.
Type
int

BotCommandScopeDefault

class telegram.BotCommandScopeDefault(*, api_kwargs=None)

Bases: telegram.BotCommandScope
Represents the default scope of bot commands. Default commands are used if no commands with a narrower
scope are specified for the user.

 Use In

• telegram.Bot.delete_my_commands()
• telegram.Bot.get_my_commands()

186 Chapter 6. License