Available Methods

This page is about Pyrogram methods. All the methods listed here are bound to a Client instance.

from pyrogram import Client

app = Client("my_account")

with app:
    app.send_message("haskell", "hi")

Index

Advanced Usage (Raw API)

Learn more about these methods at Advanced Usage.


Details

Client.start()

Start the Client.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ConnectionError – In case you try to start an already started Client.

Client.stop()

Stop the Client.

Raises

ConnectionError – In case you try to stop an already stopped Client.

Client.restart()

Restart the Client.

Raises

ConnectionError – In case you try to restart a stopped Client.

Client.idle()

Block the main script execution until a signal (e.g.: from CTRL+C) is received. Once the signal is received, the client will automatically stop and the main script will continue its execution.

This is used after starting one or more clients and is useful for event-driven applications only, that are, applications which react upon incoming Telegram updates through handlers, rather than executing a set of methods sequentially.

The way Pyrogram works, will keep your handlers in a pool of workers, which are executed concurrently outside the main script; calling idle() will ensure the client(s) will be kept alive by not letting the main script to end, until you decide to quit.

Parameters

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

Client.run()

Start the Client and automatically idle the main script.

This is a convenience method that literally just calls start() and idle(). It makes running a client less verbose, but is not suitable in case you want to run more than one client in a single main script, since idle() will block.

Raises

RPCError – In case of a Telegram RPC error.

Client.add_handler()

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

tuple – A tuple consisting of (handler, group).

Client.remove_handler()

Remove a previously-registered 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.

Client.stop_transmission()

Stop downloading or uploading a file. Must be called inside a progress callback function.

Client.export_session_string()

Export the current session as serialized string.

Returns

str – The session serialized into a printable, url-safe string.

Client.send_message()

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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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

Message – On success, the sent text message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.forward_messages()

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.

  • as_copy (bool, optional) – Pass True to forward messages without the forward header (i.e.: send a copy of the message content). Defaults to False.

  • remove_caption (bool, optional) – If set to True and as_copy is enabled as well, media captions are not preserved when copying the message. Has no effect if as_copy is not enabled. Defaults to False.

Returns

Message | List of Message – In case message_ids was an integer, the single forwarded message is returned, otherwise, in case message_ids was an iterable, the returned value will be a list of messages, even if such iterable contained just a single element.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_photo()

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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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

Message | None – On success, the sent photo message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_audio()

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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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 320 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

Message | None – On success, the sent audio message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_document()

Send generic 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, optional) – Thumbnail of the file sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 320 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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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

Message | None – On success, the sent document message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_sticker()

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

Message | None – On success, the sent sticker message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_animated_sticker()

Send .tgs animated 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).

  • animated_sticker (str) – Animated sticker to send. Pass a file_id as string to send a animated sticker that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a .webp animated sticker file from the Internet, or pass a file path as string to upload a new animated 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

Message | None – On success, the sent animated sticker message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_video()

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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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 320 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

Message | None – On success, the sent video message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_animation()

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.

  • unsave (bool, optional) – By default, the server will save into your own collection any new animation GIF you send. Pass True to automatically unsave the sent animation. Defaults to False.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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 320 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

Message | None – On success, the sent animation message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_voice()

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) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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

Message | None – On success, the sent voice message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_video_note()

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 320 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

Message | None – On success, the sent video note message is returned, otherwise, in case the upload is deliberately stopped with stop_transmission(), None is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_media_group()

Send a group of photos or videos as an album.

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 of InputMediaPhoto and InputMediaVideo) – A list 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.

Returns

List of Message – On success, a list of the sent messages is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_location()

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

Message – On success, the sent location message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_venue()

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

Message – On success, the sent venue message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_contact()

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

Message – On success, the sent contact message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_cached_media()

Send any media stored on the Telegram servers using a file_id.

This convenience method works with any valid file_id only. It does the same as calling the relevant method for sending media using a file_id, thus saving you from the hassle of using the correct method for the media the file_id is pointing to.

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).

  • file_id (str) – Media to send. Pass a file_id as string to send a media that exists on the Telegram servers.

  • caption (bool, optional) – Media caption, 0-1024 characters.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • 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

Message – On success, the sent media message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_chat_action()

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 (str) – Type of action to broadcast. Choose one, depending on what the user is about to receive: “typing” for text messages, “upload_photo” for photos, “record_video” or “upload_video” for videos, “record_audio” or “upload_audio” for audio files, “upload_document” for general files, “find_location” for location data, “record_video_note” or “upload_video_note” for video notes, “choose_contact” for contacts, “playing” for games or “cancel” to cancel any chat action currently displayed.

Returns

bool – On success, True is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case the provided string is not a valid ChatAction.

Client.edit_message_text()

Edit the text 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.

  • text (str) – New text of the message.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • disable_web_page_preview (bool, optional) – Disables link previews for links in this message.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

Message – On success, the edited message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_message_caption()

Edit the caption of media 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 media message.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

Message – On success, the edited message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_message_media()

Edit animation, 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, the message type can be changed arbitrarily.

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 (InputMedia) – One of the InputMedia objects describing an animation, audio, document, photo or video.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

Message – On success, the edited message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_message_reply_markup()

Edit only the reply markup of messages sent by the bot.

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

Message – On success, the edited message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_inline_text()

Edit the text of inline messages.

Parameters
  • inline_message_id (str) – Identifier of the inline message.

  • text (str) – New text of the message.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • disable_web_page_preview (bool, optional) – Disables link previews for links in this message.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_inline_caption()

Edit the caption of inline media messages.

Parameters
  • inline_message_id (str) – Identifier of the inline message.

  • caption (str) – New caption of the media message.

  • parse_mode (str, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together. Pass “markdown” to enable Markdown-style parsing only. Pass “html” to enable HTML-style parsing only. Pass None to completely disable style parsing.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_inline_media()

Edit inline animation, audio, document, photo or video messages.

When the inline message is edited, a new file can’t be uploaded. Use a previously uploaded file via its file_id or specify a URL.

Parameters
  • inline_message_id (str) – Required if chat_id and message_id are not specified. Identifier of the inline message.

  • media (InputMedia) – One of the InputMedia objects describing an animation, audio, document, photo or video.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.edit_inline_reply_markup()

Edit only the reply markup of inline messages sent via the bot (for inline bots).

Parameters
  • inline_message_id (str) – Identifier of the inline message.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.delete_messages()

Delete messages, including service 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_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

bool – True on success, False otherwise.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_messages()

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. Pass 0 for no reply at all or -1 for unlimited replies. Defaults to 1.

Returns

Message | List of Message – In case message_ids was an integer, the single requested message is returned, otherwise, in case message_ids was an iterable, the returned value will be a list of messages, even if such iterable contained just a single element.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_history()

Retrieve a chunk of the history of a chat.

You can get up to 100 messages at once. For a more convenient way of getting a chat history see iter_history().

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).

  • limit (int, optional) – Limits the number of messages to be retrieved. By default, the first 100 messages are returned.

  • offset (int, optional) – Sequential number of the first message to be returned. Defaults to 0 (most recent message). Negative values are also accepted and become useful in case you set offset_id or offset_date.

  • 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.

  • reverse (bool, optional) – Pass True to retrieve the messages in reversed order (from older to most recent).

Returns

List of Message - On success, a list of the retrieved messages is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_history_count()

Get the total count of messages in a chat.

Note

Due to Telegram latest internal changes, the server can’t reliably find anymore the total count of messages a private or a basic group chat has with a single method call. To overcome this limitation, Pyrogram has to iterate over all the messages. Channels and supergroups are not affected by this limitation.

Parameters

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

Returns

int – On success, the chat history count is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.read_history()

Mark a chat’s message history as read.

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).

  • max_id (int, optional) – The id of the last message you want to mark as read; all the messages before this one will be marked as read as well. Defaults to 0 (mark every unread message as read).

Returns

bool - On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.iter_history()

Iterate through a chat history sequentially.

This convenience method does the same as repeatedly calling get_history() in a loop, thus saving you from the hassle of setting up boilerplate code. It is useful for getting the whole chat history with a single call.

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).

  • limit (int, optional) – Limits the number of messages to be retrieved. By default, no limit is applied and all messages are returned.

  • offset (int, optional) – Sequential number of the first message to be returned.. Negative values are also accepted and become useful in case you set offset_id or offset_date.

  • offset_id (int, optional) – Identifier of the first message to be returned.

  • offset_date (int, optional) – Pass a date in Unix time as offset to retrieve only older messages starting from that date.

  • reverse (bool, optional) – Pass True to retrieve the messages in reversed order (from older to most recent).

Returns

Generator – A generator yielding Message objects.

Raises

RPCError – In case of a Telegram RPC error.

Client.send_poll()

Send a new poll.

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).

  • question (str) – Poll question, 1-255 characters.

  • options (List of str) – List of answer options, 2-10 strings 1-100 characters each.

  • 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

Message – On success, the sent poll message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.vote_poll()

Vote a poll.

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) – Identifier of the original message with the poll.

  • option (int) – Index of the poll option you want to vote for (0 to 9).

Returns

Poll - On success, the poll with the chosen option is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.stop_poll()

Stop a poll which was sent by you.

Stopped polls can’t be reopened and nobody will be able to vote in it anymore.

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) – Identifier of the original message with the poll.

  • reply_markup (InlineKeyboardMarkup, optional) – An InlineKeyboardMarkup object.

Returns

Poll – On success, the stopped poll with the final results is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.retract_vote()

Retract your vote in a poll.

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) – Identifier of the original message with the poll.

Returns

Poll – On success, the poll with the retracted vote is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.download_media()

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

str | None – On success, the absolute path of the downloaded file is returned, otherwise, in case the download failed or was deliberately stopped with stop_transmission(), None is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError if the message doesn't contain any downloadable media

Client.join_chat()

Join a group chat or channel.

Parameters

chat_id (str) – Unique identifier for the target chat in form of a t.me/joinchat/ link or username of the target channel/supergroup (in the format @username).

Returns

Chat – On success, a chat object is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.leave_chat()

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

RPCError – In case of a Telegram RPC error.

Client.kick_chat_member()

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

Message | bool – On success, a service message will be returned (when applicable), otherwise, in case a message object couldn’t be returned, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.unban_chat_member()

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

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.restrict_chat_member()

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.

  • can_send_polls (bool, optional) – Pass True, if the user can send polls, implies can_send_media_messages.

  • can_change_info (bool, optional) – Pass True, if the user can change the chat title, photo and other settings.

  • can_invite_users (bool, optional) – Pass True, if the user can invite new users to the chat.

  • can_pin_messages (bool, optional) – Pass True, if the user can pin messages.

Returns

Chat – On success, a chat object is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.promote_chat_member()

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_restrict_members (bool, optional) – Pass True, if the administrator can restrict, ban or unban chat members.

  • can_invite_users (bool, optional) – Pass True, if the administrator can invite new users to the chat.

  • 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

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

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.

Note

Each administrator in a chat generates their own invite links. Bots can’t use invite links generated by other administrators. If you want your bot to work with invite links, it will need to generate its own link using this method – after this the link will become available to the bot via the get_chat() method. If your bot needs to generate a new invite link replacing its previous one, use this method again.

Parameters

chat_id (int | str) – Unique identifier for the target chat or username of the target channel/supergroup (in the format @username).

Returns

str – On success, the exported invite link is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case the chat_id belongs to a user.

Client.set_chat_photo()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – if a chat_id belongs to user.

Client.delete_chat_photo()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError if a chat_id belongs to user.

Client.set_chat_title()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case a chat id belongs to user.

Client.set_chat_description()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError if a chat_id doesn't belong to a supergroup or a channel.

Client.pin_chat_message()

Pin a message in a group, channel or your own chat. 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

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.unpin_chat_message()

Unpin a message in a group, channel or your own chat. 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

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_chat()

Get up to date information about a chat.

Information include 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. Unique identifier for the target chat in form of a t.me/joinchat/ link, identifier (int) or username of the target channel/supergroup (in the format @username).

Returns

Chat | ChatPreview – On success, if you’ve already joined the chat, a chat object is returned, otherwise, a chat preview object is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case the chat invite link points to a chat you haven’t joined yet.

Client.get_chat_member()

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 user. For you yourself 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

ChatMember – On success, a chat member is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_chat_members()

Get a chunk of the members list of a chat.

You can get up to 200 chat members at once. 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”). For a more convenient way of getting chat members see iter_chat_members().

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. Only applicable to supergroups and channels. Defaults to 0 1.

  • limit (int, optional) – Limits the number of members to be retrieved. Only applicable to supergroups and channels. 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. Only applicable to supergroups and channels. 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. Only applicable to supergroups and channels. 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

List of ChatMember – On success, a list of chat members is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case you used an invalid filter or a chat id that belongs to a user.

Client.get_chat_members_count()

Get the number of members in a chat.

Parameters

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

Returns

int – On success, the chat members count is returned.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case a chat id belongs to user.

Client.iter_chat_members()

Iterate through the members of a chat sequentially.

This convenience method does the same as repeatedly calling get_chat_members() in a loop, thus saving you from the hassle of setting up boilerplate code. It is useful for getting the whole members list of a chat with a single call.

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

  • limit (int, optional) – Limits the number of members to be retrieved. By default, no limit is applied and all members are returned.

  • query (str, optional) – Query string to filter members based on their display names and usernames. Defaults to “” (empty string).

  • 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”.

Returns

Generator – A generator yielding ChatMember objects.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_dialogs()

Get a chunk of the user’s dialogs.

You can get up to 100 dialogs at once. For a more convenient way of getting a user’s dialogs see iter_dialogs().

Parameters
  • offset_date (int) – The offset date in Unix time taken from the top message of a Dialog. Defaults to 0. Valid for non-pinned dialogs only.

  • limit (str, optional) – Limits the number of dialogs to be retrieved. Defaults to 100. Valid for non-pinned dialogs only.

  • pinned_only (bool, optional) – Pass True if you want to get only pinned dialogs. Defaults to False.

Returns

List of Dialog – On success, a list of dialogs is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.iter_dialogs()

Iterate through a user’s dialogs sequentially.

This convenience method does the same as repeatedly calling get_dialogs() in a loop, thus saving you from the hassle of setting up boilerplate code. It is useful for getting the whole dialogs list with a single call.

Parameters
  • offset_date (int) – The offset date in Unix time taken from the top message of a Dialog. Defaults to 0 (most recent dialog).

  • limit (str, optional) – Limits the number of dialogs to be retrieved. By default, no limit is applied and all dialogs are returned.

Returns

Generator – A generator yielding Dialog objects.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_dialogs_count()

Get the total count of your dialogs.

pinned_only (bool, optional):

Pass True if you want to count only pinned dialogs. Defaults to False.

Returns

int – On success, the dialogs count is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.restrict_chat()

Restrict a chat. Pass True for all boolean parameters to lift restrictions from a chat.

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

  • 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.

  • can_send_polls (bool, optional) – Pass True, if the user can send polls, implies can_send_media_messages.

  • can_change_info (bool, optional) – Pass True, if the user can change the chat title, photo and other settings.

  • can_invite_users (bool, optional) – Pass True, if the user can invite new users to the chat.

  • can_pin_messages (bool, optional) – Pass True, if the user can pin messages.

Returns

Chat – On success, a chat object is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.update_chat_username()

Update a channel or a supergroup username.

To update your own username (for users only, not bots) you can use update_username().

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

  • username (str | None) – Username to set. Pass “” (empty string) or None to remove the username.

Returns

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case a chat id belongs to a user or chat.

Client.archive_chats()

Archive one or more chats.

Parameters

chat_ids (int | str | List[int, str]) – Unique identifier (int) or username (str) of the target chat. You can also pass a list of ids (int) or usernames (str).

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.unarchive_chats()

Unarchive one or more chats.

Parameters

chat_ids (int | str | List[int, str]) – Unique identifier (int) or username (str) of the target chat. You can also pass a list of ids (int) or usernames (str).

Returns

bool – On success, True is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_me()

Get your own user identity.

Returns

User – Basic information about the user or bot.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_users()

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

User | List of User – In case user_ids was an integer or string the single requested user is returned, otherwise, in case user_ids was an iterable a list of users is returned, even if the iterable contained one item only.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_profile_photos()

Get a list of profile pictures for a user or a chat.

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 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

List of Photo – On success, a list of profile photos is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_profile_photos_count()

Get the total count of profile pictures for a user.

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).

Returns

int – On success, the user profile photos count is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.iter_profile_photos()

Iterate through a chat or a user profile photos sequentially.

This convenience method does the same as repeatedly calling get_profile_photos() in a loop, thus saving you from the hassle of setting up boilerplate code. It is useful for getting all the profile photos with a single call.

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).

  • limit (int, optional) – Limits the number of profile photos to be retrieved. By default, no limit is applied and all profile photos are returned.

  • offset (int, optional) – Sequential number of the first profile photo to be returned.

Returns

Generator – A generator yielding Photo objects.

Raises

RPCError – In case of a Telegram RPC error.

Client.set_profile_photo()

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

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.delete_profile_photos()

Delete your own profile photos.

Parameters

photo_ids (str | List of str) – A single Photo id as string or multiple ids as list of strings for deleting more than one photos at once.

Returns

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.update_username()

Update your own username.

This method only works for users, not bots. Bot usernames must be changed via Bot Support or by recreating them from scratch using BotFather. To update a channel or supergroup username you can use update_chat_username().

Parameters

username (str | None) – Username to set. “” (empty string) or None to remove it.

Returns

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_user_dc()

Get the assigned DC (data center) of a user.

Note

This information is approximate: it is based on where Telegram stores a user profile pictures and does not by any means tell you the user location (i.e. a user might travel far away, but will still connect to its assigned DC). More info at FAQs.

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).

Returns

int | None – The DC identifier as integer, or None in case it wasn’t possible to get it (i.e. the user has no profile picture or has the privacy setting enabled).

Raises

RPCError – In case of a Telegram RPC error.

Client.block_user()

Block a user.

Returns

bool – True on success

Raises

RPCError – In case of Telegram RPC Error.

Client.unblock_user()

Unblock a user.

Returns

bool – True on success

Raises

RPCError – In case of Telegram RPC Error.

Client.add_contacts()

Add contacts to your Telegram address book.

Parameters

contacts (List of InputPhoneContact) – The contact list to be added

Returns

types.contacts.ImportedContacts

Raises

RPCError – In case of a Telegram RPC error.

Client.get_contacts()

Get contacts from your Telegram address book.

Returns

List of User – On success, a list of users is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.get_contacts_count()

Get the total count of contacts from your Telegram address book.

Returns

int – On success, the contacts count is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.delete_contacts()

Delete contacts from your Telegram address book.

Parameters

ids (List of int) – A list of unique identifiers for the target users. Can be an ID (int), a username (string) or phone number (string).

Returns

bool – True on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.enable_cloud_password()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case there is already a cloud password enabled.

Client.change_cloud_password()

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

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case there is no cloud password to change.

Client.remove_cloud_password()

Turn off the Two-Step Verification security feature (Cloud Password) on your account.

Parameters

password (str) – Your current password.

Returns

bool – True on success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • ValueError – In case there is no cloud password to remove.

Client.get_inline_bot_results()

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

BotResults – On Success.

Raises
  • RPCError – In case of a Telegram RPC error.

  • TimeoutError – In case the bot fails to answer within 10 seconds.

Client.send_inline_bot_result()

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.

  • hide_via (bool) – Sends the message with via @bot hidden.

Returns

Message – On success, the sent inline result message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.answer_callback_query()

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

bool – True, on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.answer_inline_query()

Send answers to an inline query. No more than 50 results per query are allowed.

Parameters
  • inline_query_id (str) – Unique identifier for the answered query.

  • results (List of InlineQueryResult) – A list of results for the inline query.

  • cache_time (int, optional) – The maximum amount of time in seconds that the result of the inline query may be cached on the server. Defaults to 300.

  • is_personal (bool, optional) – Pass True, if results may be cached on the server side only for the user that sent the query. By default, results may be returned to any user who sends the same query.

  • next_offset (str, optional) – Pass the offset that a client should send in the next query with the same text to receive more results. Pass an empty string if there are no more results or if you don‘t support pagination. Offset length can’t exceed 64 bytes.

  • switch_pm_text (str, optional) – If passed, clients will display a button with specified text that switches the user to a private chat with the bot and sends the bot a start message with the parameter switch_pm_parameter

  • switch_pm_parameter (str, optional) –

    Deep-linking parameter for the /start message sent to the bot when user presses the switch button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are allowed.

    Example: An inline bot that sends YouTube videos can ask the user to connect the bot to their YouTube account to adapt search results accordingly. To do this, it displays a “Connect your YouTube account” button above the results, or even before showing any. The user presses the button, switches to a private chat with the bot and, in doing so, passes a start parameter that instructs the bot to return an oauth link. Once done, the bot can offer a switch_inline button so that the user can easily return to the chat where they wanted to use the bot’s inline capabilities.

Returns

bool – True, on success.

Raises

RPCError – In case of a Telegram RPC error.

Client.request_callback_answer()

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 | bytes) – Callback data associated with the inline button you want to get the answer from.

  • timeout (int, optional) – Timeout in seconds.

Returns

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

Raises
  • RPCError – In case of a Telegram RPC error.

  • TimeoutError – In case the bot fails to answer within 10 seconds.

Client.send_game()

Send a game.

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).

  • game_short_name (str) – Short name of the game, serves as the unique identifier for the game. Set up your games via Botfather.

  • disable_notification (bool, optional) – Sends the message silently. Users will receive a notification with no sound.

  • reply_to_message_id (int, optional) – If the message is a reply, ID of the original message.

  • reply_markup (InlineKeyboardMarkup, optional) – An object for an inline keyboard. If empty, one ‘Play game_title’ button will be shown automatically. If not empty, the first button must launch the game.

Returns

Message – On success, the sent game message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Client.set_game_score()

Set the score of the specified user in a game.

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).

  • score (int) – New score, must be non-negative.

  • force (bool, optional) – Pass True, if the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters.

  • disable_edit_message (bool, optional) – Pass True, if the game message should not be automatically edited to include the current scoreboard.

  • chat_id (int | str, optional) – 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). Required if inline_message_id is not specified.

  • message_id (int, optional) – Identifier of the sent message. Required if inline_message_id is not specified.

Returns

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

Raises

RPCError – In case of a Telegram RPC error.

Client.get_game_high_scores()

Get data for high score tables.

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).

  • chat_id (int | str, optional) – 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). Required if inline_message_id is not specified.

  • message_id (int, optional) – Identifier of the sent message. Required if inline_message_id is not specified.

Returns

List of GameHighScore – On success.

Raises

RPCError – In case of a Telegram RPC error.

Client.send()

Send raw Telegram queries.

This method makes it 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…

Note

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).

Parameters
  • data (RawFunction) – The API Schema function filled with proper arguments.

  • retries (int) – Number of retries.

  • timeout (float) – Timeout in seconds.

Returns

RawType – The raw type response generated by the query.

Raises

RPCError – In case of a Telegram RPC error.

Client.resolve_peer()

Get the InputPeer of a known peer id. Useful whenever an InputPeer type is required.

Note

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).

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

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

Raises
  • RPCError – In case of a Telegram RPC error.

  • KeyError – In case the peer doesn’t exist in the internal database.

Client.save_file()

Upload a file onto Telegram servers, without actually sending the message to anyone. Useful whenever an InputFile type is required.

Note

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).

Parameters
  • path (str) – The path of the file you want to upload that exists on your local machine.

  • file_id (int, optional) – In case a file part expired, pass the file_id and the file_part to retry uploading that specific chunk.

  • file_part (int, optional) – In case a file part expired, pass the file_id and the file_part to retry uploading that specific chunk.

  • 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

InputFile – On success, the uploaded file is returned in form of an InputFile object.

Raises

RPCError – In case of a Telegram RPC error.