telegram.Bot#

class telegram.Bot(*args, **kwargs)[source]#

Bases: telegram.TelegramObject, contextlib.AbstractAsyncContextManager

This object represents a Telegram Bot.

Instances of this class can be used as asyncio context managers, where

async with bot:
    # code

is roughly equivalent to

try:
    await bot.initialize()
    # code
finally:
    await request_object.shutdown()

Note

Most bot methods have the argument api_kwargs which allows passing arbitrary keywords to the Telegram API. This can be used to access new features of the API before they are incorporated into PTB. However, this is not guaranteed to work, i.e. it will fail for passing files.
Bots should not be serialized since if you for e.g. change the bots token, then your serialized instance will not reflect that change. Trying to pickle a bot instance will raise pickle.PicklingError.

New in version 13.2: Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their bot is equal.

Changed in version 20.0:

Removed the deprecated methods kick_chat_member, kickChatMember, get_chat_members_count and getChatMembersCount.
Removed the deprecated property commands.
Removed the deprecated defaults parameter. If you want to use telegram.ext.Defaults, please use the subclass telegram.ext.ExtBot instead.
Attempting to pickle a bot instance will now raise pickle.PicklingError.

Parameters

token (str) – Bot’s unique authentication token.
base_url (str, optional) – Telegram Bot API service URL.
base_file_url (str, optional) – Telegram Bot API file URL.
request (telegram.request.BaseRequest, optional) – Pre initialized telegram.request.BaseRequest instances. Will be used for all bot methods except for get_updates(). If not passed, an instance of telegram.request.HTTPXRequest will be used.
get_updates_request (telegram.request.BaseRequest, optional) – Pre initialized telegram.request.BaseRequest instances. Will be used exclusively for get_updates(). If not passed, an instance of telegram.request.HTTPXRequest will be used.
private_key (bytes, optional) – Private key for decryption of telegram passport data.
private_key_password (bytes, optional) – Password for above private key.

Since this class has a large number of methods and attributes, below you can find a quick overview.

Sending Messages

`send_animation()`	Used for sending animations
`send_audio()`	Used for sending audio files
`send_chat_action()`	Used for sending chat actions
`send_contact()`	Used for sending contacts
`send_dice()`	Used for sending dice messages
`send_document()`	Used for sending documents
`send_game()`	Used for sending a game
`send_invoice()`	Used for sending an invoice
`send_location()`	Used for sending location
`send_media_group()`	Used for sending media grouped together
`send_message()`	Used for sending text messages
`send_photo()`	Used for sending photos
`send_poll()`	Used for sending polls
`send_sticker()`	Used for sending stickers
`send_venue()`	Used for sending venue locations.
`send_video()`	Used for sending videos
`send_video_note()`	Used for sending video notes
`send_voice()`	Used for sending voice messages
`copy_message()`	Used for copying the contents of an arbitrary message
`forward_message()`	Used for forwarding messages

Updating Messages

`answer_callback_query()`	Used for answering the callback query
`answer_inline_query()`	Used for answering the inline query
`answer_pre_checkout_query()`	Used for answering a pre checkout query
`answer_shipping_query()`	Used for answering a shipping query
`answer_web_app_query()`	Used for answering a web app query
`edit_message_caption()`	Used for editing captions
`edit_message_media()`	Used for editing the media on messages
`edit_message_live_location()`	Used for editing the location in live location messages
`edit_message_reply_markup()`	Used for editing the reply markup on messages
`edit_message_text()`	Used for editing text messages
`stop_poll()`	Used for stopping the running poll
`delete_message()`	Used for deleting messages.

Chat Moderation and information

`ban_chat_member()`	Used for banning a member from the chat
`unban_chat_member()`	Used for unbanning a member from the chat
`ban_chat_sender_chat()`	Used for banning a channel in a channel or supergroup
`unban_chat_sender_chat()`	Used for unbanning a channel in a channel or supergroup
`restrict_chat_member()`	Used for restricting a chat member
`promote_chat_member()`	Used for promoting a chat member
`set_chat_administrator_custom_title()`	Used for assigning a custom admin title to an admin
`set_chat_permissions()`	Used for setting the permissions of a chat
`export_chat_invite_link()`	Used for creating a new primary invite link for a chat
`create_chat_invite_link()`	Used for creating an additional invite link for a chat
`edit_chat_invite_link()`	Used for editing a non-primary invite link
`revoke_chat_invite_link()`	Used for revoking an invite link created by the bot
`approve_chat_join_request()`	Used for approving a chat join request
`decline_chat_join_request()`	Used for declining a chat join request
`set_chat_photo()`	Used for setting a photo to a chat
`delete_chat_photo()`	Used for deleting a chat photo
`set_chat_title()`	Used for setting a chat title
`set_chat_description()`	Used for setting the description of a chat
`pin_chat_message()`	Used for pinning a message
`unpin_chat_message()`	Used for unpinning a message
`unpin_all_chat_messages()`	Used for unpinning all pinned chat messages
`get_user_profile_photos()`	Used for obtaining user’s profile pictures
`get_chat()`	Used for getting information about a chat
`get_chat_administrators()`	Used for getting the list of admins in a chat
`get_chat_member_count()`	Used for getting the number of members in a chat
`get_chat_member()`	Used for getting a member of a chat
`set_my_commands()`	Used for setting the list of commands
`delete_my_commands()`	Used for deleting the list of commands
`get_my_commands()`	Used for obtaining the list of commands
`get_my_default_administrator_rights()`	Used for obtaining the default administrator rights for the bot
`set_my_default_administrator_rights()`	Used for setting the default administrator rights for the bot
`get_chat_menu_button()`	Used for obtaining the menu button of a private chat or the default menu button
`set_chat_menu_button()`	Used for setting the menu button of a private chat or the default menu button
`leave_chat()`	Used for leaving a chat

Stickerset management

`add_sticker_to_set()`	Used for adding a sticker to a set
`delete_sticker_from_set()`	Used for deleting a sticker from a set
`create_new_sticker_set()`	Used for creating a new sticker set
`set_chat_sticker_set()`	Used for setting a sticker set
`delete_chat_sticker_set()`	Used for deleting the set sticker set
`set_sticker_position_in_set()`	Used for moving a sticker’s position in the set
`set_sticker_set_thumb()`	Used for setting the thumbnail of a sticker set
`get_sticker_set()`	Used for getting a sticker set
`upload_sticker_file()`	Used for uploading a sticker file

Games

`get_game_high_scores()`	Used for getting the game high scores
`set_game_score()`	Used for setting the game score

Getting updates

`get_updates()`	Used for getting updates using long polling
`get_webhook_info()`	Used for getting current webhook status
`set_webhook()`	Used for setting a webhook to receive updates
`delete_webhook()`	Used for removing webhook integration

Miscellaneous

`close()`	Used for closing server instance when switching to another local server
`log_out()`	Used for logging out from cloud Bot API server
`get_file()`	Used for getting basic info about a file
`get_me()`	Used for getting basic information about the bot

Properties

`bot`	The user instance of the bot as returned by `get_me()`
`can_join_groups`	Whether the bot can join groups
`can_read_all_group_messages`	Whether the bot can read all incoming group messages
`id`	The user id of the bot
`name`	The username of the bot, with leading `@`
`first_name`	The first name of the bot
`last_name`	The last name of the bot
`username`	The username of the bot, without leading `@`
`link`	The t.me link of the bot
`supports_inline_queries`	Whether the bot supports inline queries

async addStickerToSet(user_id, name, emojis, png_sticker=None, mask_position=None, read_timeout=None, write_timeout=20, connect_timeout=None, pool_timeout=None, tgs_sticker=None, api_kwargs=None, webm_sticker=None)[source]#: Alias for add_sticker_to_set()

async add_sticker_to_set(user_id, name, emojis, png_sticker=None, mask_position=None, read_timeout=None, write_timeout=20, connect_timeout=None, pool_timeout=None, tgs_sticker=None, api_kwargs=None, webm_sticker=None)[source]#

Use this method to add a new sticker to a set created by the bot. You must use exactly one of the fields png_sticker, tgs_sticker or webm_sticker. Animated stickers can be added to animated sticker sets and only to them. Animated sticker sets can have up to 50 stickers. Static sticker sets can have up to 120 stickers.

Warning

As of API 4.7 png_sticker 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.

Note

The png_sticker and tgs_sticker argument can be either a file_id, an URL or a file from disk open(filename, 'rb')

Parameters

user_id (int) – User identifier of created sticker set owner.
name (str) – Sticker set name.
png_sticker (str | file object | bytes | pathlib.Path, optional) –
PNG image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px. Pass a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data.

Changed in version 13.2: Accept bytes as input.
tgs_sticker (str | file object | bytes | pathlib.Path, optional) –
TGS animation with the sticker, uploaded using multipart/form-data. See https://core.telegram.org/stickers#animated-sticker-requirements for technical requirements.

Changed in version 13.2: Accept bytes as input.
webm_sticker (str | file object | bytes | pathlib.Path, optional) –
WEBM video with the sticker, uploaded using multipart/form-data. See https://core.telegram.org/stickers#video-sticker-requirements for technical requirements.

New in version 13.11.
emojis (str) – One or more emoji corresponding to the sticker.
mask_position (telegram.MaskPosition, optional) – Position where the mask should be placed on faces.
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 Telegram API.

Returns

On success, True is returned.

Return type

bool

Raises