Client

class pyrogram.Client(session_name: str, api_id: int = None, api_hash: str = None, app_version: str = None, device_model: str = None, system_version: str = None, lang_code: str = None, ipv6: bool = False, proxy: dict = None, test_mode: bool = False, phone_number: str = None, phone_code: str = None, password: str = None, force_sms: bool = False, first_name: str = None, last_name: str = None, workers: int = 4, workdir: str = '.', config_file: str = './config.ini', plugins_dir: str = None)

This class represents a Client, the main mean for interacting with Telegram. It exposes bot-like methods for an easy access to the API as well as a simple way to invoke every single Telegram API method available.

Parameters:
  • session_name (str) – Name to uniquely identify a session of either a User or a Bot. For Users: pass a string of your choice, e.g.: “my_main_account”. For Bots: pass your Bot API token, e.g.: “123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11” Note: as long as a valid User session file exists, Pyrogram won’t ask you again to input your phone number.
  • api_id (int, optional) – The api_id part of your Telegram API Key, as integer. E.g.: 12345 This is an alternative way to pass it if you don’t want to use the config.ini file.
  • api_hash (str, optional) – The api_hash part of your Telegram API Key, as string. E.g.: “0123456789abcdef0123456789abcdef” This is an alternative way to pass it if you don’t want to use the config.ini file.
  • app_version (str, optional) – Application version. Defaults to “Pyrogram 🔥 vX.Y.Z” This is an alternative way to set it if you don’t want to use the config.ini file.
  • device_model (str, optional) – Device model. Defaults to platform.python_implementation() + ” ” + platform.python_version() This is an alternative way to set it if you don’t want to use the config.ini file.
  • system_version (str, optional) – Operating System version. Defaults to platform.system() + ” ” + platform.release() This is an alternative way to set it if you don’t want to use the config.ini file.
  • lang_code (str, optional) – Code of the language used on the client, in ISO 639-1 standard. Defaults to “en”. This is an alternative way to set it if you don’t want to use the config.ini file.
  • ipv6 (bool, optional) – Pass True to connect to Telegram using IPv6. Defaults to False (IPv4).
  • proxy (dict, optional) – Your SOCKS5 Proxy settings as dict, e.g.: dict(hostname=”11.22.33.44”, port=1080, username=”user”, password=”pass”). username and password can be omitted if your proxy doesn’t require authorization. This is an alternative way to setup a proxy if you don’t want to use the config.ini file.
  • test_mode (bool, optional) – Enable or disable log-in to testing servers. Defaults to False. Only applicable for new sessions and will be ignored in case previously created sessions are loaded.
  • phone_number (str, optional) – Pass your phone number (with your Country Code prefix included) to avoid entering it manually. Only applicable for new sessions.
  • phone_code (str | callable, optional) – Pass the phone code as string (for test numbers only), or pass a callback function which accepts a single positional argument (phone_number) and must return the correct phone code (e.g., “12345”). Only applicable for new sessions.
  • password (str, optional) – Pass your Two-Step Verification password (if you have one) to avoid entering it manually. Only applicable for new sessions.
  • force_sms (str, optional) – Pass True to force Telegram sending the authorization code via SMS. Only applicable for new sessions.
  • first_name (str, optional) – Pass a First Name to avoid entering it manually. It will be used to automatically create a new Telegram account in case the phone number you passed is not registered yet. Only applicable for new sessions.
  • last_name (str, optional) – Same purpose as first_name; pass a Last Name to avoid entering it manually. It can be an empty string: “”. Only applicable for new sessions.
  • workers (int, optional) – Thread pool size for handling incoming updates. Defaults to 4.
  • workdir (str, optional) – Define a custom working directory. The working directory is the location in your filesystem where Pyrogram will store your session files. Defaults to “.” (current directory).
  • config_file (str, optional) – Path of the configuration file. Defaults to ./config.ini
  • plugins_dir (str, optional) – Define a custom directory for your plugins. The plugins directory is the location in your filesystem where Pyrogram will automatically load your update handlers. Defaults to None (plugins disabled).

Utilities

start Use this method to start the Client after creating it.
stop Use this method to manually stop the Client.
idle Blocks the program execution until one of the signals are received, then gently stop the Client by closing the underlying connection.
run Use this method to automatically start and idle a Client.
add_handler Use this method to register an update handler.
remove_handler Removes a previously-added update handler.
send Use this method to send Raw Function queries.
resolve_peer Use this method to get the InputPeer of a known peer_id.
download_media Use this method to download the media from a Message.

Decorators

on_message Use this decorator to automatically register a function for handling messages.
on_callback_query Use this decorator to automatically register a function for handling callback queries.
on_deleted_messages Use this decorator to automatically register a function for handling deleted messages.
on_user_status Use this decorator to automatically register a function for handling user status updates.
on_disconnect Use this decorator to automatically register a function for handling disconnections.
on_raw_update Use this decorator to automatically register a function for handling raw updates.

Messages

send_message Use this method to send text messages.
forward_messages Use this method to forward messages of any kind.
send_photo Use this method to send photos.
send_audio Use this method to send audio files.
send_document Use this method to send general files.
send_sticker Use this method to send .webp stickers.
send_video Use this method to send video files.
send_animation Use this method to send animation files (animation or H.264/MPEG-4 AVC video without sound).
send_voice Use this method to send audio files.
send_video_note Use this method to send video messages.
send_media_group Use this method to send a group of photos or videos as an album.
send_location Use this method to send points on the map.
send_venue Use this method to send information about a venue.
send_contact Use this method to send phone contacts.
send_chat_action Use this method when you need to tell the other party that something is happening on your side.
edit_message_text Use this method to edit text messages.
edit_message_caption Use this method to edit captions of messages.
edit_message_reply_markup Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots).
edit_message_media Use this method to edit audio, document, photo, or video messages.
delete_messages Use this method to delete messages, including service messages, with the following limitations:
get_messages Use this method to get one or more messages that belong to a specific chat.
get_history Use this method to retrieve the history of a chat.

Chats

join_chat Use this method to join a group chat or channel.
leave_chat Use this method to leave a group chat or channel.
kick_chat_member Use this method to kick a user from a group, a supergroup or a channel.
unban_chat_member Use this method to unban a previously kicked user in a supergroup or channel.
restrict_chat_member Use this method to restrict a user in a supergroup.
promote_chat_member Use this method to promote or demote a user in a supergroup or a channel.
export_chat_invite_link Use this method to generate a new invite link for a chat; any previously generated link is revoked.
set_chat_photo Use this method to set a new profile photo for the chat.
delete_chat_photo Use this method to delete a chat photo.
set_chat_title Use this method to change the title of a chat.
set_chat_description Use this method to change the description of a supergroup or a channel.
pin_chat_message Use this method to pin a message in a supergroup or a channel.
unpin_chat_message Use this method to unpin a message in a supergroup or a channel.
get_chat Use this method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.)
get_chat_member Use this method to get information about one member of a chat.
get_chat_members Use this method to get the members list of a chat.
get_chat_members_count Use this method to get the number of members in a chat.
get_dialogs Use this method to get the user’s dialogs

Users

get_me A simple method for testing your authorization.
get_users Use this method to get information about a user.
get_user_profile_photos Use this method to get a list of profile pictures for a user.
set_user_profile_photo Use this method to set a new profile photo.
delete_user_profile_photos Use this method to delete your own profile photos

Contacts

add_contacts Use this method to add contacts to your Telegram address book.
get_contacts Use this method to get contacts from your Telegram address book
delete_contacts Use this method to delete contacts from your Telegram address book

Password

enable_cloud_password Use this method to enable the Two-Step Verification security feature (Cloud Password) on your account.
change_cloud_password Use this method to change your Two-Step Verification password (Cloud Password) with a new one.
remove_cloud_password Use this method to turn off the Two-Step Verification security feature (Cloud Password) on your account.

Bots

get_inline_bot_results Use this method to get bot results via inline queries.
send_inline_bot_result Use this method to send an inline bot result.
answer_callback_query Use this method to send answers to callback queries sent from inline keyboards.
request_callback_answer Use this method to request a callback answer from bots.
class pyrogram.Client(session_name: str, api_id: int = None, api_hash: str = None, app_version: str = None, device_model: str = None, system_version: str = None, lang_code: str = None, ipv6: bool = False, proxy: dict = None, test_mode: bool = False, phone_number: str = None, phone_code: str = None, password: str = None, force_sms: bool = False, first_name: str = None, last_name: str = None, workers: int = 4, workdir: str = '.', config_file: str = './config.ini', plugins_dir: str = None)

This class represents a Client, the main mean for interacting with Telegram. It exposes bot-like methods for an easy access to the API as well as a simple way to invoke every single Telegram API method available.

Parameters:
  • session_name (str) – Name to uniquely identify a session of either a User or a Bot. For Users: pass a string of your choice, e.g.: “my_main_account”. For Bots: pass your Bot API token, e.g.: “123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11” Note: as long as a valid User session file exists, Pyrogram won’t ask you again to input your phone number.
  • api_id (int, optional) – The api_id part of your Telegram API Key, as integer. E.g.: 12345 This is an alternative way to pass it if you don’t want to use the config.ini file.
  • api_hash (str, optional) – The api_hash part of your Telegram API Key, as string. E.g.: “0123456789abcdef0123456789abcdef” This is an alternative way to pass it if you don’t want to use the config.ini file.
  • app_version (str, optional) – Application version. Defaults to “Pyrogram 🔥 vX.Y.Z” This is an alternative way to set it if you don’t want to use the config.ini file.
  • device_model (str, optional) – Device model. Defaults to platform.python_implementation() + ” ” + platform.python_version() This is an alternative way to set it if you don’t want to use the config.ini file.
  • system_version (str, optional) – Operating System version. Defaults to platform.system() + ” ” + platform.release() This is an alternative way to set it if you don’t want to use the config.ini file.
  • lang_code (str, optional) – Code of the language used on the client, in ISO 639-1 standard. Defaults to “en”. This is an alternative way to set it if you don’t want to use the config.ini file.
  • ipv6 (bool, optional) – Pass True to connect to Telegram using IPv6. Defaults to False (IPv4).
  • proxy (dict, optional) – Your SOCKS5 Proxy settings as dict, e.g.: dict(hostname=”11.22.33.44”, port=1080, username=”user”, password=”pass”). username and password can be omitted if your proxy doesn’t require authorization. This is an alternative way to setup a proxy if you don’t want to use the config.ini file.
  • test_mode (bool, optional) – Enable or disable log-in to testing servers. Defaults to False. Only applicable for new sessions and will be ignored in case previously created sessions are loaded.
  • phone_number (str, optional) – Pass your phone number (with your Country Code prefix included) to avoid entering it manually. Only applicable for new sessions.
  • phone_code (str | callable, optional) – Pass the phone code as string (for test numbers only), or pass a callback function which accepts a single positional argument (phone_number) and must return the correct phone code (e.g., “12345”). Only applicable for new sessions.
  • password (str, optional) – Pass your Two-Step Verification password (if you have one) to avoid entering it manually. Only applicable for new sessions.
  • force_sms (str, optional) – Pass True to force Telegram sending the authorization code via SMS. Only applicable for new sessions.
  • first_name (str, optional) – Pass a First Name to avoid entering it manually. It will be used to automatically create a new Telegram account in case the phone number you passed is not registered yet. Only applicable for new sessions.
  • last_name (str, optional) – Same purpose as first_name; pass a Last Name to avoid entering it manually. It can be an empty string: “”. Only applicable for new sessions.
  • workers (int, optional) – Thread pool size for handling incoming updates. Defaults to 4.
  • workdir (str, optional) – Define a custom working directory. The working directory is the location in your filesystem where Pyrogram will store your session files. Defaults to “.” (current directory).
  • config_file (str, optional) – Path of the configuration file. Defaults to ./config.ini
  • plugins_dir (str, optional) – Define a custom directory for your plugins. The plugins directory is the location in your filesystem where Pyrogram will automatically load your update handlers. Defaults to None (plugins disabled).
start()

Use this method to start the Client after creating it. Requires no parameters.

Raises:
  • Error in case of a Telegram RPC error.
  • ConnectionError in case you try to start an already started Client.
stop()

Use this method to manually stop the Client. Requires no parameters.

Raises:ConnectionError in case you try to stop an already stopped Client.
idle(stop_signals: tuple = (<Signals.SIGINT: 2>, <Signals.SIGTERM: 15>, <Signals.SIGABRT: 6>))

Blocks the program execution until one of the signals are received, then gently stop the Client by closing the underlying connection.

Parameters:stop_signals (tuple, optional) – Iterable containing signals the signal handler will listen to. Defaults to (SIGINT, SIGTERM, SIGABRT).
run()

Use this method to automatically start and idle a Client. Requires no parameters.

Raises:Error in case of a Telegram RPC error.
add_handler(handler, group: int = 0)

Use this method to register an update handler.

You can register multiple handlers, but at most one handler within a group will be used for a single update. To handle the same update more than once, register your handler using a different group id (lower group id == higher priority).

Parameters:
  • handler (Handler) – The handler to be registered.
  • group (int, optional) – The group identifier, defaults to 0.
Returns:

A tuple of (handler, group)

remove_handler(handler, group: int = 0)

Removes a previously-added update handler.

Make sure to provide the right group that the handler was added in. You can use the return value of the add_handler() method, a tuple of (handler, group), and pass it directly.

Parameters:
  • handler (Handler) – The handler to be removed.
  • group (int, optional) – The group identifier, defaults to 0.
send(data: pyrogram.api.core.object.Object, retries: int = 5, timeout: float = 15)

Use this method to send Raw Function queries.

This method makes possible to manually call every single Telegram API method in a low-level manner. Available functions are listed in the functions package and may accept compound data types from types as well as bare types such as int, str, etc…

Parameters:
  • data (Object) – The API Schema function filled with proper arguments.
  • retries (int) – Number of retries.
  • timeout (float) – Timeout in seconds.
Raises:

Error in case of a Telegram RPC error.

resolve_peer(peer_id: int)

Use this method to get the InputPeer of a known peer_id.

This is a utility method intended to be used only when working with Raw Functions (i.e: a Telegram API method you wish to use which is not available yet in the Client class as an easy-to-use method), whenever an InputPeer type is required.

Parameters:

peer_id (int | str) – The peer id you want to extract the InputPeer from. Can be a direct id (int), a username (str) or a phone number (str).

Returns:

On success, the resolved peer id is returned in form of an InputPeer object.

Raises:
  • Error in case of a Telegram RPC error.
  • KeyError in case the peer doesn’t exist in the internal database.
add_contacts(contacts: list)

Use this method to add contacts to your Telegram address book.

Parameters:contacts (list) – A list of InputPhoneContact
Returns:On success, the added contacts are returned.
Raises:Error in case of a Telegram RPC error.
answer_callback_query(callback_query_id: str, text: str = None, show_alert: bool = None, url: str = None, cache_time: int = 0)

Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.

Parameters:
  • callback_query_id (str) – Unique identifier for the query to be answered.
  • text (str) – Text of the notification. If not specified, nothing will be shown to the user, 0-200 characters.
  • show_alert (bool) – If true, an alert will be shown by the client instead of a notification at the top of the chat screen. Defaults to False.
  • url (str) – URL that will be opened by the user’s client. If you have created a Game and accepted the conditions via @Botfather, specify the URL that opens your game – note that this will only work if the query comes from a callback_game button. Otherwise, you may use links like t.me/your_bot?start=XXXX that open your bot with a parameter.
  • cache_time (int) – The maximum amount of time in seconds that the result of the callback query may be cached client-side. Telegram apps will support caching starting in version 3.14. Defaults to 0.
Returns:

True, on success.

Raises:

Error in case of a Telegram RPC error.

change_cloud_password(current_password: str, new_password: str, new_hint: str = '')

Use this method to change your Two-Step Verification password (Cloud Password) with a new one.

Parameters:
  • current_password (str) – Your current password.
  • new_password (str) – Your new password.
  • new_hint (str, optional) – A new password hint.
Returns:

True on success, False otherwise.

Raises:

Error in case of a Telegram RPC error.

delete_chat_photo(chat_id: int)

Use this method to delete a chat photo. Photos can’t be changed for private chats. You must be an administrator in the chat for this to work and must have the appropriate admin rights.

Note

In regular groups (non-supergroups), this method will only work if the “All Members Are Admins” setting is off.

Parameters:

chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.

Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id belongs to user.
delete_contacts(ids: list)

Use this method to delete contacts from your Telegram address book

Parameters:ids (list) – A list of unique identifiers for the target users. Can be an ID (int), a username (string) or phone number (string).
Returns:True on success.
Raises:Error in case of a Telegram RPC error.
delete_messages(chat_id: int, message_ids, revoke: bool = True)

Use this method to delete messages, including service messages, with the following limitations:

  • A message can only be deleted if it was sent less than 48 hours ago.
  • Users can delete outgoing messages in groups and supergroups.
  • Users granted can_post_messages permissions can delete outgoing messages in channels.
  • If the user is an administrator of a group, it can delete any message there.
  • If the user has can_delete_messages permission in a supergroup or a channel, it can delete any message there.
Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_ids (iterable) – A list of Message identifiers to delete or a single message id. Iterators and Generators are also accepted.
  • revoke (bool, optional) – Deletes messages on both parts. This is only for private cloud chats and normal groups, messages on channels and supergroups are always revoked (i.e.: deleted for everyone). Defaults to True.
Returns:

True on success.

Raises:

Error in case of a Telegram RPC error.

delete_user_profile_photos(id: str)

Use this method to delete your own profile photos

Parameters:id (str | list) – A single Photo id as string or multiple ids as list of strings for deleting more than one photos at once.
Returns:True on success.
Raises:Error in case of a Telegram RPC error.
download_media(message: pyrogram.client.types.messages_and_media.message.Message, file_name: str = '', block: bool = True, progress: callable = None, progress_args: tuple = None)

Use this method to download the media from a Message.

Parameters:
  • message (Message | str) – Pass a Message containing the media, the media itself (message.audio, message.video, …) or the file id as string.
  • file_name (str, optional) – A custom file_name to be used instead of the one provided by Telegram. By default, all files are downloaded in the downloads folder in your working directory. You can also specify a path for downloading files in a custom location: paths that end with “/” are considered directories. All non-existent folders will be created automatically.
  • block (bool, optional) – Blocks the code execution until the file has been downloaded. Defaults to True.
  • progress (callable) – Pass a callback function to view the download progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes downloaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the absolute path of the downloaded file as string is returned, None otherwise.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if the message doesn’t contain any downloadable media
edit_message_caption(chat_id: int, message_id: int, caption: str, parse_mode: str = '', reply_markup=None)

Use this method to edit captions of messages.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_id (int) – Message identifier in the chat specified in chat_id.
  • caption (str) – New caption of the message.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.
Returns:

On success, the edited Message is returned.

Raises:

Error in case of a Telegram RPC error.

edit_message_media(chat_id: int, message_id: int, media, reply_markup=None)

Use this method to edit audio, document, photo, or video messages.

If a message is a part of a message album, then it can be edited only to a photo or a video. Otherwise, message type can be changed arbitrarily. When inline message is edited, new file can’t be uploaded. Use previously uploaded file via its file_id or specify a URL. On success, if the edited message was sent by the bot, the edited Message is returned, otherwise True is returned.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_id (int) – Message identifier in the chat specified in chat_id.
  • media (InputMediaAnimation | InputMediaAudio | InputMediaDocument | InputMediaPhoto | InputMediaVideo) – One of the InputMedia objects describing an animation, audio, document, photo or video.
  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.
Returns:

On success, the edited Message is returned.

Raises:

Error in case of a Telegram RPC error.

edit_message_reply_markup(chat_id: int, message_id: int, reply_markup=None)

Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots).

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_id (int) – Message identifier in the chat specified in chat_id.
  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.
Returns:

On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.

Raises:

Error in case of a Telegram RPC error.

edit_message_text(chat_id: int, message_id: int, text: str, parse_mode: str = '', disable_web_page_preview: bool = None, reply_markup=None)

Use this method to edit text messages.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_id (int) – Message identifier in the chat specified in chat_id.
  • text (str) – New text of the message.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your message. Defaults to Markdown.
  • disable_web_page_preview (bool, optional) – Disables link previews for links in this message.
  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.
Returns:

On success, the edited Message is returned.

Raises:

Error in case of a Telegram RPC error.

enable_cloud_password(password: str, hint: str = '', email: str = '')

Use this method to enable the Two-Step Verification security feature (Cloud Password) on your account.

This password will be asked when you log in on a new device in addition to the SMS code.

Parameters:
  • password (str) – Your password.
  • hint (str, optional) – A password hint.
  • email (str, optional) – Recovery e-mail.
Returns:

True on success, False otherwise.

Raises:

Error in case of a Telegram RPC error.

Use this method to generate a new invite link for a chat; any previously generated link is revoked.

You must be an administrator in the chat for this to work and have the appropriate admin rights.

Parameters:chat_id (int | str) – Unique identifier for the target chat or username of the target channel/supergroup (in the format @username).
Returns:On success, the exported invite link as string is returned.
Raises:Error in case of a Telegram RPC error.
forward_messages(chat_id: int, from_chat_id: int, message_ids, disable_notification: bool = None)

Use this method to forward messages of any kind.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • from_chat_id (int | str) – Unique identifier (int) or username (str) of the source chat where the original message was sent. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_ids (iterable) – A list of Message identifiers in the chat specified in from_chat_id or a single message id. Iterators and Generators are also accepted.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
Returns:

On success and in case message_ids was a list, the returned value will be a list of the forwarded Messages even if a list contains just one element, otherwise if message_ids was an integer, the single forwarded Message is returned.

Raises:

Error in case of a Telegram RPC error.

get_chat(chat_id: int)

Use this method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.)

Parameters:chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
Returns:On success, a Chat object is returned.
Raises:Error in case of a Telegram RPC error.
get_chat_member(chat_id: int, user_id: int)

Use this method to get information about one member of a chat.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • user_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
Returns:

On success, a ChatMember object is returned.

Raises:

Error in case of a Telegram RPC error.

get_chat_members(chat_id: int, offset: int = 0, limit: int = 200, query: str = '', filter: str = 'all')

Use this method to get the members list of a chat.

A chat can be either a basic group, a supergroup or a channel. You must be admin to retrieve the members list of a channel (also known as “subscribers”).

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • offset (int, optional) – Sequential number of the first member to be returned. Defaults to 0 [1].
  • limit (int, optional) – Limits the number of members to be retrieved. Defaults to 200, which is also the maximum server limit allowed per method call.
  • query (str, optional) – Query string to filter members based on their display names and usernames. Defaults to “” (empty string) [2].
  • filter (str, optional) – Filter used to select the kind of members you want to retrieve. Only applicable for supergroups and channels. It can be any of the followings: “all” - all kind of members, “kicked” - kicked (banned) members only, “restricted” - restricted members only, “bots” - bots only, “recent” - recent members only, “administrators” - chat administrators only. Defaults to “all”.
[1]Server limit: on supergroups, you can get up to 10,000 members for a single query and up to 200 members on channels.
[2]A query string is applicable only for “all”, “kicked” and “restricted” filters only.
Returns:

On success, a ChatMembers object is returned.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if you used an invalid filter or a chat_id that belongs to a user.
get_chat_members_count(chat_id: int)

Use this method to get the number of members in a chat.

Parameters:

chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.

Returns:

On success, an integer is returned.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id belongs to user.
get_contacts()

Use this method to get contacts from your Telegram address book

Requires no parameters.

Returns:On success, the user’s contacts are returned
Raises:Error in case of a Telegram RPC error.
get_dialogs(offset_dialogs=None, limit: int = 100, pinned_only: bool = False)

Use this method to get the user’s dialogs

You can get up to 100 dialogs at once.

Parameters:
  • limit (str, optional) – Limits the number of dialogs to be retrieved. Defaults to 100
  • pinned_only (bool, optional) – Pass True if you want to get only pinned dialogs. Defaults to False.
  • offset_dialogs (Dialogs) – Pass the previous dialogs object to retrieve the next dialogs chunk starting from the last dialog. Defaults to None (start from the beginning).
Returns:

On success, a Dialogs object is returned.

Raises:

Error in case of a Telegram RPC error.

get_history(chat_id: int, offset: int = 0, limit: int = 100, offset_id: int = 0, offset_date: int = 0)

Use this method to retrieve the history of a chat.

You can get up to 100 messages at once.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • offset (int, optional) – Sequential number of the first message to be returned. Defaults to 0 (most recent message).
  • limit (int, optional) – Limits the number of messages to be retrieved. By default, the first 100 messages are returned.
  • offset_id (int, optional) – Pass a message identifier as offset to retrieve only older messages starting from that message.
  • offset_date (int, optional) – Pass a date in Unix time as offset to retrieve only older messages starting from that date.
Returns:

On success, a Messages object is returned.

Raises:

Error in case of a Telegram RPC error.

get_inline_bot_results(bot: int, query: str, offset: str = '', latitude: float = None, longitude: float = None)

Use this method to get bot results via inline queries. You can then send a result using send_inline_bot_result

Parameters:
  • bot (int | str) – Unique identifier of the inline bot you want to get results from. You can specify a @username (str) or a bot ID (int).
  • query (str) – Text of the query (up to 512 characters).
  • offset (str, optional) – Offset of the results to be returned.
  • latitude (float, optional) – Latitude of the location. Useful for location-based results only.
  • longitude (float, optional) – Longitude of the location. Useful for location-based results only.
Returns:

On Success, BotResults is returned.

Raises:
  • Error in case of a Telegram RPC error.
  • TimeoutError if the bot fails to answer within 10 seconds
get_me()

A simple method for testing your authorization. Requires no parameters.

Returns:Basic information about the user or bot in form of a User object
Raises:Error in case of a Telegram RPC error.
get_messages(chat_id: int, message_ids: int = None, reply_to_message_ids: int = None, replies: int = 1)

Use this method to get one or more messages that belong to a specific chat. You can retrieve up to 200 messages at once.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_ids (iterable, optional) – Pass a single message identifier or a list of message ids (as integers) to get the content of the message themselves. Iterators and Generators are also accepted.
  • reply_to_message_ids (iterable, optional) – Pass a single message identifier or a list of message ids (as integers) to get the content of the previous message you replied to using this message. Iterators and Generators are also accepted. If message_ids is set, this argument will be ignored.
  • replies (int, optional) – The number of subsequent replies to get for each message. Defaults to 1.
Returns:

On success and in case message_ids or reply_to_message_ids was a list, the returned value will be a list of the requested Messages even if a list contains just one element, otherwise if message_ids or reply_to_message_ids was an integer, the single requested Message is returned.

Raises:

Error in case of a Telegram RPC error.

get_user_profile_photos(user_id: int, offset: int = 0, limit: int = 100)

Use this method to get a list of profile pictures for a user.

Parameters:
  • user_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • offset (int, optional) – Sequential number of the first photo to be returned. By default, all photos are returned.
  • limit (int, optional) – Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100.
Returns:

On success, a UserProfilePhotos object is returned.

Raises:

Error in case of a Telegram RPC error.

get_users(user_ids)

Use this method to get information about a user. You can retrieve up to 200 users at once.

Parameters:user_ids (iterable) – A list of User identifiers (id or username) or a single user id/username. For a contact that exists in your Telegram address book you can use his phone number (str). Iterators and Generators are also accepted.
Returns:On success and in case user_ids was a list, the returned value will be a list of the requested Users even if a list contains just one element, otherwise if user_ids was an integer, the single requested User is returned.
Raises:Error in case of a Telegram RPC error.
join_chat(chat_id: str)

Use this method to join a group chat or channel.

Parameters:chat_id (str) – Unique identifier for the target chat in form of t.me/joinchat/ links or username of the target channel/supergroup (in the format @username).
Raises:Error in case of a Telegram RPC error.
kick_chat_member(chat_id: int, user_id: int, until_date: int = 0)

Use this method to kick a user from a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first. You must be an administrator in the chat for this to work and must have the appropriate admin rights.

Note

In regular groups (non-supergroups), this method will only work if the “All Members Are Admins” setting is off in the target group. Otherwise members may only be removed by the group’s creator or by the member that added them.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • user_id (int | str) – Unique identifier (int) or username (str) of the target user. For a contact that exists in your Telegram address book you can use his phone number (str).
  • until_date (int, optional) – Date when the user will be unbanned, unix time. If user is banned for more than 366 days or less than 30 seconds from the current time they are considered to be banned forever. Defaults to 0 (ban forever).
Returns:

True on success.

Raises:

Error in case of a Telegram RPC error.

leave_chat(chat_id: int, delete: bool = False)

Use this method to leave a group chat or channel.

Parameters:
  • chat_id (int | str) – Unique identifier for the target chat or username of the target channel/supergroup (in the format @username).
  • delete (bool, optional) – Deletes the group chat dialog after leaving (for simple group chats, not supergroups).
Raises:

Error in case of a Telegram RPC error.

on_callback_query(filters=None, group: int = 0)

Use this decorator to automatically register a function for handling callback queries. This does the same thing as add_handler() using the CallbackQueryHandler.

Parameters:
  • filters (Filters) – Pass one or more filters to allow only a subset of callback queries to be passed in your function.
  • group (int, optional) – The group identifier, defaults to 0.
on_deleted_messages(filters=None, group: int = 0)

Use this decorator to automatically register a function for handling deleted messages. This does the same thing as add_handler() using the DeletedMessagesHandler.

Parameters:
  • filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your function.
  • group (int, optional) – The group identifier, defaults to 0.
on_disconnect()

Use this decorator to automatically register a function for handling disconnections. This does the same thing as add_handler() using the DisconnectHandler.

on_message(filters=None, group: int = 0)

Use this decorator to automatically register a function for handling messages. This does the same thing as add_handler() using the MessageHandler.

Parameters:
  • filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your function.
  • group (int, optional) – The group identifier, defaults to 0.
on_raw_update(group: int = 0)

Use this decorator to automatically register a function for handling raw updates. This does the same thing as add_handler() using the RawUpdateHandler.

Parameters:group (int, optional) – The group identifier, defaults to 0.
on_user_status(filters=None, group: int = 0)

Use this decorator to automatically register a function for handling user status updates. This does the same thing as add_handler() using the UserStatusHandler.

Parameters:
  • filters (Filters) – Pass one or more filters to allow only a subset of UserStatus updated to be passed in your function.
  • group (int, optional) – The group identifier, defaults to 0.
pin_chat_message(chat_id: int, message_id: int, disable_notification: bool = None)

Use this method to pin a message in a supergroup or a channel. You must be an administrator in the chat for this to work and must have the “can_pin_messages” admin right in the supergroup or “can_edit_messages” admin right in the channel.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • message_id (int) – Identifier of a message to pin.
  • disable_notification (bool) – Pass True, if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels.
Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id doesn’t belong to a supergroup or a channel.
promote_chat_member(chat_id: int, user_id: int, can_change_info: bool = True, can_post_messages: bool = False, can_edit_messages: bool = False, can_delete_messages: bool = True, can_invite_users: bool = True, can_restrict_members: bool = True, can_pin_messages: bool = False, can_promote_members: bool = False)

Use this method to promote or demote a user in a supergroup or a channel. You must be an administrator in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • user_id (int | str) – Unique identifier (int) or username (str) of the target user. For a contact that exists in your Telegram address book you can use his phone number (str).
  • can_change_info (bool, optional) – Pass True, if the administrator can change chat title, photo and other settings.
  • can_post_messages (bool, optional) – Pass True, if the administrator can create channel posts, channels only.
  • can_edit_messages (bool, optional) – Pass True, if the administrator can edit messages of other users and can pin messages, channels only.
  • can_delete_messages (bool, optional) – Pass True, if the administrator can delete messages of other users.
  • can_invite_users (bool, optional) – Pass True, if the administrator can invite new users to the chat.
  • can_restrict_members (bool, optional) – Pass True, if the administrator can restrict, ban or unban chat members.
  • can_pin_messages (bool, optional) – Pass True, if the administrator can pin messages, supergroups only.
  • can_promote_members (bool, optional) – Pass True, if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by him).
Returns:

True on success.

Raises:

Error in case of a Telegram RPC error.

remove_cloud_password(password: str)

Use this method to turn off the Two-Step Verification security feature (Cloud Password) on your account.

Parameters:password (str) – Your current password.
Returns:True on success, False otherwise.
Raises:Error in case of a Telegram RPC error.
request_callback_answer(chat_id: int, message_id: int, callback_data: str)

Use this method to request a callback answer from bots. This is the equivalent of clicking an inline button containing callback data.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • message_id (int) – The message id the inline keyboard is attached on.
  • callback_data (str) – Callback data associated with the inline button you want to get the answer from.
Returns:

The answer containing info useful for clients to display a notification at the top of the chat screen or as an alert.

Raises:
  • Error in case of a Telegram RPC error.
  • TimeoutError if the bot fails to answer within 10 seconds.
restrict_chat_member(chat_id: int, user_id: int, until_date: int = 0, can_send_messages: bool = False, can_send_media_messages: bool = False, can_send_other_messages: bool = False, can_add_web_page_previews: bool = False)

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.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • user_id (int | str) – Unique identifier (int) or username (str) of the target user. For a contact that exists in your Telegram address book you can use his phone number (str).
  • until_date (int, optional) – Date when the user will be unbanned, unix time. If user is banned for more than 366 days or less than 30 seconds from the current time they are considered to be banned forever. Defaults to 0 (ban forever).
  • can_send_messages (bool, optional) – Pass True, if the user can send text messages, contacts, locations and venues.
  • can_send_media_messages (bool, optional) – Pass True, if the user can send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages.
  • can_send_other_messages (bool, optional) – Pass True, if the user can send animations, games, stickers and use inline bots, implies can_send_media_messages.
  • can_add_web_page_previews (bool, optional) – Pass True, if the user may add web page previews to their messages, implies can_send_media_messages
Returns:

True on success.

Raises:

Error in case of a Telegram RPC error.

send_animation(chat_id: int, animation: str, caption: str = '', parse_mode: str = '', duration: int = 0, width: int = 0, height: int = 0, thumb: str = None, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send animation files (animation or H.264/MPEG-4 AVC video without sound).

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • animation (str) – Animation to send. Pass a file_id as string to send an animation that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get an animation from the Internet, or pass a file path as string to upload a new animation that exists on your local machine.
  • caption (str, optional) – Animation caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • duration (int, optional) – Duration of sent animation in seconds.
  • width (int, optional) – Animation width.
  • height (int, optional) – Animation height.
  • thumb (str, optional) – Thumbnail of the animation file sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 90 pixels. Thumbnails can’t be reused and can be only uploaded as a new file.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_audio(chat_id: int, audio: str, caption: str = '', parse_mode: str = '', duration: int = 0, performer: str = None, title: str = None, thumb: str = None, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send audio files.

For sending voice messages, use the send_voice() method instead.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • audio (str) – Audio file to send. Pass a file_id as string to send an audio file that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get an audio file from the Internet, or pass a file path as string to upload a new audio file that exists on your local machine.
  • caption (str, optional) – Audio caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • duration (int, optional) – Duration of the audio in seconds.
  • performer (str, optional) – Performer.
  • title (str, optional) – Track name.
  • thumb (str, optional) – Thumbnail of the music file album cover. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 90 pixels. Thumbnails can’t be reused and can be only uploaded as a new file.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_chat_action(chat_id: int, action: pyrogram.client.ext.chat_action.ChatAction, progress: int = 0)

Use this method when you need to tell the other party that something is happening on your side.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • action (ChatAction | str) – Type of action to broadcast. Choose one from the ChatAction enumeration, depending on what the user is about to receive. You can also provide a string (e.g. “typing”, “upload_photo”, “record_audio”, …).
  • progress (int, optional) – Progress of the upload process. Currently useless because official clients don’t seem to be handling this.
Returns:

On success, True is returned.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if the provided string is not a valid ChatAction.
send_contact(chat_id: int, phone_number: str, first_name: str, last_name: str = '', vcard: str = '', disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None)

Use this method to send phone contacts.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • phone_number (str) – Contact’s phone number.
  • first_name (str) – 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.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_document(chat_id: int, document: str, thumb: str = None, caption: str = '', parse_mode: str = '', disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send general files.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • document (str) – File to send. Pass a file_id as string to send a file that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a file from the Internet, or pass a file path as string to upload a new file that exists on your local machine.
  • thumb (str) – Thumbnail of the file sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 90 pixels. Thumbnails can’t be reused and can be only uploaded as a new file.
  • caption (str, optional) – Document caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_inline_bot_result(chat_id: int, query_id: int, result_id: str, disable_notification: bool = None, reply_to_message_id: int = None)

Use this method to send an inline bot result. Bot results can be retrieved using get_inline_bot_results

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • query_id (int) – Unique identifier for the answered query.
  • result_id (str) – Unique identifier for the result that was chosen.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (bool, optional) – If the message is a reply, ID of the original message.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_location(chat_id: int, latitude: float, longitude: float, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None)

Use this method to send points on the map.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • latitude (float) – Latitude of the location.
  • longitude (float) – Longitude of the location.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_media_group(chat_id: int, media: list, disable_notification: bool = None, reply_to_message_id: int = None)

Use this method to send a group of photos or videos as an album. On success, an Update containing the sent Messages is returned.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • media (list) – A list containing either InputMediaPhoto or InputMediaVideo objects describing photos and videos to be sent, must include 2–10 items.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
send_message(chat_id: int, text: str, parse_mode: str = '', disable_web_page_preview: bool = None, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None)

Use this method to send text messages.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • text (str) – Text of the message to be sent.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your message. Defaults to Markdown.
  • disable_web_page_preview (bool, optional) – Disables link previews for links in this message.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_photo(chat_id: int, photo: str, caption: str = '', parse_mode: str = '', ttl_seconds: int = None, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send photos.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • photo (str) – Photo to send. Pass a file_id as string to send a photo that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a photo from the Internet, or pass a file path as string to upload a new photo that exists on your local machine.
  • caption (bool, optional) – Photo caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • ttl_seconds (int, optional) – Self-Destruct Timer. If you set a timer, the photo will self-destruct in ttl_seconds seconds after it was viewed.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_sticker(chat_id: int, sticker: str, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send .webp stickers.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • sticker (str) – Sticker to send. Pass a file_id as string to send a sticker that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a .webp sticker file from the Internet, or pass a file path as string to upload a new sticker that exists on your local machine.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_venue(chat_id: int, latitude: float, longitude: float, title: str, address: str, foursquare_id: str = '', foursquare_type: str = '', disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None)

Use this method to send information about a venue.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • latitude (float) – Latitude of the venue.
  • longitude (float) – Longitude of the venue.
  • title (str) – Name of the venue.
  • address (str) – Address of the venue.
  • foursquare_id (str, optional) – Foursquare identifier of the venue.
  • foursquare_type (str, optional) – Foursquare type of the venue, if known. (For example, “arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_video(chat_id: int, video: str, caption: str = '', parse_mode: str = '', duration: int = 0, width: int = 0, height: int = 0, thumb: str = None, supports_streaming: bool = True, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send video files.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • video (str) – Video to send. Pass a file_id as string to send a video that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a video from the Internet, or pass a file path as string to upload a new video that exists on your local machine.
  • caption (str, optional) – Video caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • duration (int, optional) – Duration of sent video in seconds.
  • width (int, optional) – Video width.
  • height (int, optional) – Video height.
  • thumb (str, optional) – Thumbnail of the video sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 90 pixels. Thumbnails can’t be reused and can be only uploaded as a new file.
  • 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.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_video_note(chat_id: int, video_note: str, duration: int = 0, length: int = 1, thumb: str = None, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send video messages.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • video_note (str) – Video note to send. Pass a file_id as string to send a video note that exists on the Telegram servers, or pass a file path as string to upload a new video note that exists on your local machine. Sending video notes by a URL is currently unsupported.
  • duration (int, optional) – Duration of sent video in seconds.
  • length (int, optional) – Video width and height.
  • thumb (str, optional) – Thumbnail of the video sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 90 pixels. Thumbnails can’t be reused and can be only uploaded as a new file.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

send_voice(chat_id: int, voice: str, caption: str = '', parse_mode: str = '', duration: int = 0, disable_notification: bool = None, reply_to_message_id: int = None, reply_markup=None, progress: callable = None, progress_args: tuple = ())

Use this method to send audio files.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).
  • voice (str) – Audio file to send. Pass a file_id as string to send an audio that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get an audio from the Internet, or pass a file path as string to upload a new audio that exists on your local machine.
  • caption (str, optional) – Voice message caption, 0-1024 characters.
  • parse_mode (str, optional) – Use MARKDOWN or HTML if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to Markdown.
  • duration (int, optional) – Duration of the voice message in seconds.
  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.
  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message
  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.
  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).
  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.
Other Parameters:
 
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.
  • current (int) – The amount of bytes uploaded so far.
  • total (int) – The size of the file.
  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.
Returns:

On success, the sent Message is returned.

Raises:

Error in case of a Telegram RPC error.

set_chat_description(chat_id: int, description: str)

Use this method to change the description of a supergroup or a channel. You must be an administrator in the chat for this to work and must have the appropriate admin rights.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • description (str) – New chat description, 0-255 characters.
Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id doesn’t belong to a supergroup or a channel.
set_chat_photo(chat_id: int, photo: str)

Use this method to set a new profile photo for the chat. Photos can’t be changed for private chats. You must be an administrator in the chat for this to work and must have the appropriate admin rights.

Note

In regular groups (non-supergroups), this method will only work if the “All Members Are Admins” setting is off.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • photo (str) – New chat photo. You can pass a Photo id or a file path to upload a new photo.
Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id belongs to user.
set_chat_title(chat_id: int, title: str)

Use this method to change the title of a chat. Titles can’t be changed for private chats. You must be an administrator in the chat for this to work and must have the appropriate admin rights.

Note

In regular groups (non-supergroups), this method will only work if the “All Members Are Admins” setting is off.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • title (str) – New chat title, 1-255 characters.
Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id belongs to user.
set_user_profile_photo(photo: str)

Use this method to set a new profile photo.

This method only works for Users. Bots profile photos must be set using BotFather.

Parameters:photo (str) – Profile photo to set. Pass a file path as string to upload a new photo that exists on your local machine.
Returns:True on success.
Raises:Error in case of a Telegram RPC error.
unban_chat_member(chat_id: int, user_id: int)

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. You must be an administrator for this to work.

Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.
  • user_id (int | str) – Unique identifier (int) or username (str) of the target user. For a contact that exists in your Telegram address book you can use his phone number (str).
Returns:

True on success.

Raises:

Error in case of a Telegram RPC error.

unpin_chat_message(chat_id: int)

Use this method to unpin a message in a supergroup or a channel. You must be an administrator in the chat for this to work and must have the “can_pin_messages” admin right in the supergroup or “can_edit_messages” admin right in the channel.

Parameters:

chat_id (int | str) – Unique identifier (int) or username (str) of the target chat.

Returns:

True on success.

Raises:
  • Error in case of a Telegram RPC error.
  • ValueError if a chat_id doesn’t belong to a supergroup or a channel.