Bound Methods

Some Pyrogram types define what are called bound methods. Bound methods are functions attached to a class which are accessed via an instance of that class. They make it even easier to call specific methods by automatically inferring some of the required arguments.

from pyrogram import Client

app = Client("my_account")


@app.on_message()
def hello(client, message)
    message.reply("hi")


app.run()

Details

Message.click()

Bound method click Message.

Use as a shortcut for clicking a button attached to the message instead of:

  • Clicking inline buttons:

client.request_callback_answer(
    chat_id=message.chat.id,
    message_id=message.message_id,
    callback_data=message.reply_markup[i][j].callback_data
)
  • Clicking normal buttons:

client.send_message(
    chat_id=message.chat.id,
    text=message.reply_markup[i][j].text
)

Example

This method can be used in three different ways:

  1. Pass one integer argument only (e.g.: .click(2), to click a button at index 2). Buttons are counted left to right, starting from the top.

  2. Pass two integer arguments (e.g.: .click(1, 0), to click a button at position (1, 0)). The origin (0, 0) is top-left.

  3. Pass one string argument only (e.g.: .click("Settings"), to click a button by using its label). Only the first matching button will be pressed.

Parameters
  • x (int | str) – Used as integer index, integer abscissa (in pair with y) or as string label. Defaults to 0 (first button).

  • y (int, optional) – Used as ordinate only (in pair with x).

  • quote (bool, optional) – Useful for normal buttons only, where pressing it will result in a new message sent. If True, the message will be sent as a reply to this message. Defaults to True in group chats and False in private chats.

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

Returns

  • The result of request_callback_answer() in case of inline callback button clicks.

  • The result of reply() in case of normal button clicks.

  • A string in case the inline button is a URL, a switch_inline_query or a switch_inline_query_current_chat button.

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

  • ValueError – In case the provided index or position is out of range or the button label was not found.

  • TimeoutError – In case, after clicking an inline button, the bot fails to answer within the timeout.

Message.delete()

Bound method delete Message.

Use as a shortcut for:

client.delete_messages(
    chat_id=chat_id,
    message_ids=message.message_id
)

Example

message.delete()
Parameters

revoke (bool, optional) – Deletes messages on both parts. This is only for private cloud chats and normal groups, messages on channels and supergroups are always revoked (i.e.: deleted for everyone). Defaults to True.

Returns

True on success, False otherwise.

Raises

RPCError – In case of a Telegram RPC error.

Message.download()

Bound method download Message.

Use as a shortcut for:

client.download_media(message)

Example

message.download()
Parameters
  • 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.

Returns

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

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

  • ValueError – If the message doesn’t contain any downloadable media

Message.edit()

Bound method edit Message.

Use as a shortcut for:

client.edit_message_text(
    chat_id=message.chat.id,
    message_id=message.message_id,
    text="hello"
)

Example

message.edit("hello")
Parameters
  • text (str) – New text of the message.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your message. Defaults to “markdown”.

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

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

Returns

On success, the edited Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.edit_caption()

Bound method edit_caption Message.

Use as a shortcut for:

client.edit_message_caption(
    chat_id=message.chat.id,
    message_id=message.message_id,
    caption="hello"
)

Example

message.edit_caption("hello")
Parameters
  • caption (str) – New caption of the message.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your message. Defaults to “markdown”.

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

Returns

On success, the edited Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.edit_media()

Bound method edit_media Message.

Use as a shortcut for:

client.edit_message_media(
    chat_id=message.chat.id,
    message_id=message.message_id,
    media=media
)

Example

message.edit_media(media)
Parameters
Returns

On success, the edited Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.edit_reply_markup()

Bound method edit_reply_markup Message.

Use as a shortcut for:

client.edit_message_reply_markup(
    chat_id=message.chat.id,
    message_id=message.message_id,
    reply_markup=inline_reply_markup
)

Example

message.edit_reply_markup(inline_reply_markup)
Parameters

reply_markup (InlineKeyboardMarkup) – An InlineKeyboardMarkup object.

Returns

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

Raises

RPCError – In case of a Telegram RPC error.

Message.forward()

Bound method forward Message.

Use as a shortcut for:

client.forward_messages(
    chat_id=chat_id,
    from_chat_id=message.chat.id,
    message_ids=message.message_id
)

Example

message.forward(chat_id)
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).

  • 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

On success, the forwarded Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.pin()

Bound method pin Message.

Use as a shortcut for:

client.pin_chat_message(
    chat_id=message.chat.id,
    message_id=message_id
)

Example

message.pin()
Parameters

disable_notification (bool) – Pass True, if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels.

Returns

True on success.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply()

Bound method reply Message.

Use as a shortcut for:

client.send_message(
    chat_id=message.chat.id,
    text="hello",
    reply_to_message_id=message.message_id
)

Example

message.reply("hello", quote=True)
Parameters
  • text (str) – Text of the message to be sent.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your message. Defaults to “markdown”.

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

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_animation()

Bound method reply_animation Message.

Use as a shortcut for:

client.send_animation(
    chat_id=message.chat.id,
    animation=animation
)

Example

message.reply_animation(animation)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • caption (str, optional) – Animation caption, 0-1024 characters.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

  • duration (int, optional) – Duration of sent animation in seconds.

  • width (int, optional) – Animation width.

  • height (int, optional) – Animation height.

  • thumb (str, optional) – Thumbnail of the animation file sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 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

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_audio()

Bound method reply_audio Message.

Use as a shortcut for:

client.send_audio(
    chat_id=message.chat.id,
    audio=audio
)

Example

message.reply_audio(audio)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • caption (str, optional) – Audio caption, 0-1024 characters.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

  • duration (int, optional) – Duration of the audio in seconds.

  • performer (str, optional) – Performer.

  • title (str, optional) – Track name.

  • thumb (str, optional) – Thumbnail of the music file album cover. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 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

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_cached_media()

Bound method reply_cached_media Message.

Use as a shortcut for:

client.send_cached_media(
    chat_id=message.chat.id,
    file_id=file_id
)

Example

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

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

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

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_chat_action()

Bound method reply_chat_action Message.

Use as a shortcut for:

client.send_chat_action(
    chat_id=message.chat.id,
    action="typing"
)

Example

message.reply_chat_action("typing")
Parameters

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 chat action.

Message.reply_contact()

Bound method reply_contact Message.

Use as a shortcut for:

client.send_contact(
    chat_id=message.chat.id,
    phone_number=phone_number,
    first_name=first_name
)

Example

message.reply_contact(phone_number, "Dan")
Parameters
  • phone_number (str) – Contact’s phone number.

  • first_name (str) – Contact’s first name.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • last_name (str, optional) – Contact’s last name.

  • vcard (str, optional) – Additional data about the contact in the form of a vCard, 0-2048 bytes

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_document()

Bound method reply_document Message.

Use as a shortcut for:

client.send_document(
    chat_id=message.chat.id,
    document=document
)

Example

message.reply_document(document)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • 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) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).

  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.

Other Parameters
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.

  • current (int) – The amount of bytes uploaded so far.

  • total (int) – The size of the file.

  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.

Returns

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_game()

Bound method reply_game Message.

Use as a shortcut for:

client.send_game(
    chat_id=message.chat.id,
    game_short_name="lumberjack"
)

Example

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

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • 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

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_inline_bot_result()

Bound method reply_inline_bot_result Message.

Use as a shortcut for:

client.send_inline_bot_result(
    chat_id=message.chat.id,
    query_id=query_id,
    result_id=result_id
)

Example

message.reply_inline_bot_result(query_id, result_id)
Parameters
  • query_id (int) – Unique identifier for the answered query.

  • result_id (str) – Unique identifier for the result that was chosen.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • 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

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_location()

Bound method reply_location Message.

Use as a shortcut for:

client.send_location(
    chat_id=message.chat.id,
    latitude=41.890251,
    longitude=12.492373
)

Example

message.reply_location(41.890251, 12.492373)
Parameters
  • latitude (float) – Latitude of the location.

  • longitude (float) – Longitude of the location.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_media_group()

Bound method reply_media_group Message.

Use as a shortcut for:

client.send_media_group(
    chat_id=message.chat.id,
    media=list_of_media
)

Example

message.reply_media_group(list_of_media)
Parameters
  • media (list) – A list containing either InputMediaPhoto or InputMediaVideo objects describing photos and videos to be sent, must include 2–10 items.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • 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

On success, a Messages object is returned containing all the single messages sent.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_photo()

Bound method reply_photo Message.

Use as a shortcut for:

client.send_photo(
    chat_id=message.chat.id,
    photo=photo
)

Example

message.reply_photo(photo)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

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

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

  • ttl_seconds (int, optional) – Self-Destruct Timer. If you set a timer, the photo will self-destruct in ttl_seconds seconds after it was viewed.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).

  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.

Other Parameters
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.

  • current (int) – The amount of bytes uploaded so far.

  • total (int) – The size of the file.

  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.

Returns

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_poll()

Bound method reply_poll Message.

Use as a shortcut for:

client.send_poll(
    chat_id=message.chat.id,
    question="Is Pyrogram the best?",
    options=["Yes", "Yes"]
)

Example

message.reply_poll("Is Pyrogram the best?", ["Yes", "Yes"])
Parameters
  • question (str) – The poll question, as string.

  • options (List of str) – The poll options, as list of strings (2 to 10 options are allowed).

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_sticker()

Bound method reply_sticker Message.

Use as a shortcut for:

client.send_sticker(
    chat_id=message.chat.id,
    sticker=sticker
)

Example

message.reply_sticker(sticker)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).

  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.

Other Parameters
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.

  • current (int) – The amount of bytes uploaded so far.

  • total (int) – The size of the file.

  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.

Returns

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_venue()

Bound method reply_venue Message.

Use as a shortcut for:

client.send_venue(
    chat_id=message.chat.id,
    latitude=41.890251,
    longitude=12.492373,
    title="Coliseum",
    address="Piazza del Colosseo, 1, 00184 Roma RM"
)

Example

message.reply_venue(41.890251, 12.492373, "Coliseum", "Piazza del Colosseo, 1, 00184 Roma RM")
Parameters
  • latitude (float) – Latitude of the venue.

  • longitude (float) – Longitude of the venue.

  • title (str) – Name of the venue.

  • address (str) – Address of the venue.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • foursquare_id (str, optional) – Foursquare identifier of the venue.

  • foursquare_type (str, optional) – Foursquare type of the venue, if known. (For example, “arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

Returns

On success, the sent Message is returned.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_video()

Bound method reply_video Message.

Use as a shortcut for:

client.send_video(
    chat_id=message.chat.id,
    video=video
)

Example

message.reply_video(video)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • caption (str, optional) – Video caption, 0-1024 characters.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

  • duration (int, optional) – Duration of sent video in seconds.

  • width (int, optional) – Video width.

  • height (int, optional) – Video height.

  • thumb (str, optional) – Thumbnail of the video sent. The thumbnail should be in JPEG format and less than 200 KB in size. A thumbnail’s width and height should not exceed 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

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_video_note()

Bound method reply_video_note Message.

Use as a shortcut for:

client.send_video_note(
    chat_id=message.chat.id,
    video_note=video_note
)

Example

message.reply_video_note(video_note)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • 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

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

Message.reply_voice()

Bound method reply_voice Message.

Use as a shortcut for:

client.send_voice(
    chat_id=message.chat.id,
    voice=voice
)

Example

message.reply_voice(voice)
Parameters
  • 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.

  • quote (bool, optional) – If True, the message will be sent as a reply to this message. If reply_to_message_id is passed, this parameter will be ignored. Defaults to True in group chats and False in private chats.

  • caption (str, optional) – Voice message caption, 0-1024 characters.

  • parse_mode (str, optional) – Pass “markdown” or “html” if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your caption. Defaults to “markdown”.

  • duration (int, optional) – Duration of the voice message in seconds.

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

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

  • reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

  • progress (callable, optional) – Pass a callback function to view the upload progress. The function must take (client, current, total, *args) as positional arguments (look at the section below for a detailed description).

  • progress_args (tuple, optional) – Extra custom arguments for the progress callback function. Useful, for example, if you want to pass a chat_id and a message_id in order to edit a message with the updated progress.

Other Parameters
  • client (Client) – The Client itself, useful when you want to call other API methods inside the callback function.

  • current (int) – The amount of bytes uploaded so far.

  • total (int) – The size of the file.

  • *args (tuple, optional) – Extra custom arguments as defined in the progress_args parameter. You can either keep *args or add every single extra argument in your function signature.

Returns

On success, the sent Message is returned. In case the upload is deliberately stopped with stop_transmission(), None is returned instead.

Raises

RPCError – In case of a Telegram RPC error.

CallbackQuery.answer()

Bound method answer of CallbackQuery.

Use this method as a shortcut for:

client.answer_callback_query(
    callback_query.id,
    text="Hello",
    show_alert=True
)

Example

callback_query.answer("Hello", show_alert=True)
Parameters
  • 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.

InlineQuery.answer()

Bound method answer of InlineQuery.

Use this method as a shortcut for:

client.answer_inline_query(
    inline_query.id,
    results=[...]
)

Example

inline_query.answer([...])
Parameters
  • 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.