• Home »
• Message

View on GitHub

Star

—

Used by

—

Message

class pyrogram.types.Message

Bases: Object, Update

A message.

Parameters:

• id (int) – Unique message identifier inside this chat.

• from_user (User, optional) – Sender, empty for messages sent to channels.

• sender_chat (Chat, optional) – Sender of the message, sent on behalf of a chat. The channel itself for channel messages. The supergroup itself for messages from anonymous group administrators. The linked channel for messages automatically forwarded to the discussion group.

• sender_boost_count (int, optional) – If the sender of the message boosted the chat, the number of boosts added by the user.

• sender_business_bot (User, optional) – The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the connected business account.

• sender_tag (str, optional) – Tag or custom title of the sender of the message. For supergroups only.

• date (datetime, optional) – Date the message was sent.

• chat (Chat, optional) – Conversation the message belongs to.

• topic_message (bool, optional) – True, if the message is a forum topic message.

• automatic_forward (bool, optional) – True, if the message is a channel post that was automatically forwarded to the connected discussion group.

• from_offline (bool, optional) – True, if the message was sent by an implicit action, for example, as an away or a greeting business message, or as a scheduled message.

• topic (ForumTopic, optional) – Topic the message belongs to.

• forward_origin (MessageOrigin, optional) – Information about the original message for forwarded messages.

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of a topic in a channel direct messages chat administered by the current user. For direct chats only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_to_message_id (int, optional) – The id of the message which this message directly replied to.

• reply_to_story_id (int, optional) – The id of the story which this message directly replied to.

• reply_to_story_user_id (int, optional) – The id of the story sender which this message directly replied to.

• reply_to_top_message_id (int, optional) – The id of the first message which started this message thread.

• reply_to_poll_option_id (str, optional) – Persistent identifier of the specific poll option that is being replied to.

• reply_to_message (Message, optional) – For replies, the original message. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is a reply.

• reply_to_story (Story, optional) – For replies, the original story.

• reply_to_checklist_task_id (int, optional) – Identifier of the specific checklist task that is being replied to.

• mentioned (bool, optional) – The message contains a mention.

• empty (bool, optional) – The message is empty. A message can be empty in case it was deleted or you tried to retrieve a message that doesn’t exist yet.

• service (MessageServiceType, optional) – The message is a service message. This field will contain the enumeration type of the service message. You can use service = getattr(message, message.service.value) to access the service message.

• media (MessageMediaType, optional) – The message is a media message. This field will contain the enumeration type of the media message. You can use media = getattr(message, message.media.value) to access the media message.

• paid_media (PaidMediaInfo, optional) – The message is a paid media message.

• checklist (Checklist, optional) – The message is a checklist message.

• show_caption_above_media (bool, optional) – If True, caption must be shown above the message media.

• edit_date (datetime, optional) – Date the message was last edited.

• edit_hidden (bool, optional) – The message shown as not modified. A message can be not modified in case it has received a reaction.

• media_group_id (int, optional) – The unique identifier of a media message group this message belongs to.

• author_signature (str, optional) – Signature of the post author for messages in channels, or the custom title of an anonymous group administrator.

• is_paid_post (bool, optional) – True, if the message is a paid post. Note that such posts must not be deleted for 24 hours to receive the payment and can’t be edited.

• has_protected_content (bool, optional) – True, if the message can’t be forwarded.

• has_media_spoiler (bool, optional) – True, if the message media is covered by a spoiler animation.

• text (str, optional) – For text messages, the actual UTF-8 text of the message, 0-4096 characters. If the message contains entities (bold, italic, …) you can access text.markdown or text.html to get the marked up message text. In case there is no entity, the fields will contain the same text as text.

• entities (List of MessageEntity, optional) – For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text.

• caption_entities (List of MessageEntity, optional) – For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption.

• audio (Audio, optional) – Message is an audio file, information about the file.

• document (Document, optional) – Message is a general file, information about the file.

• photo (Photo, optional) – Message is a photo, information about the photo.

• sticker (Sticker, optional) – Message is a sticker, information about the sticker.

• animation (Animation, optional) – Message is an animation, information about the animation.

• game (Game, optional) – Message is a game, information about the game.

• giveaway (Giveaway, optional) – Message is a giveaway, information about the giveaway.

• invoice (Invoice, optional) – Message is a invoice, information about the invoice. More about payments »

• story (Story, optional) – Message is a story, information about the story.

• video (Video, optional) – Message is a video, information about the video.

• video_processing_pending (bool, optional) – True, if the video is still processing.

• voice (Voice, optional) – Message is a voice message, information about the file.

• video_note (VideoNote, optional) – Message is a video note, information about the video message.

• caption (str, optional) – Caption for the audio, document, photo, video or voice, 0-1024 characters. If the message contains caption entities (bold, italic, …) you can access caption.markdown or caption.html to get the marked up caption text. In case there is no caption entity, the fields will contain the same text as caption.

• contact (Contact, optional) – Message is a shared contact, information about the contact.

• location (Location, optional) – Message is a shared location, information about the location.

• venue (Venue, optional) – Message is a venue, information about the venue.

• web_page (WebPage, optional) – Message was sent with a webpage preview.

• link_preview_options (LinkPreviewOptions, optional) – Options used for link preview generation for the message.

• poll (Poll, optional) – Message is a native poll, information about the poll.

• dice (Dice, optional) – A dice containing a value that is randomly generated by Telegram.

• new_chat_members (List of User, optional) – New members that were added to the group or supergroup and information about them (the bot itself may be one of these members).

• left_chat_member (User, optional) – A member was removed from the group, information about them (this member may be the bot itself).

• chat_owner_left (ChatOwnerLeft, optional) – Service message: chat owner has left.

• chat_owner_changed (ChatOwnerChanged, optional) – Service message: chat owner has changed.

• chat_join_type (ChatJoinType, optional) – This field will contain the enumeration type of how the user had joined the chat.

• new_chat_title (str, optional) – A chat title was changed to this value.

• new_chat_photo (Photo, optional) – A chat photo was change to this value.

• delete_chat_photo (bool, optional) – Service message: the chat photo was deleted.

• group_chat_created (bool, optional) – Service message: the group has been created.

• supergroup_chat_created (bool, optional) – Service message: the supergroup has been created. This field can’t be received in a message coming through updates, because bot can’t be a member of a supergroup when it is created. It can only be found in reply_to_message if someone replies to a very first message in a directly created supergroup.

• channel_chat_created (bool, optional) – Service message: the channel has been created. This field can’t be received in a message coming through updates, because bot can’t be a member of a channel when it is created. It can only be found in reply_to_message if someone replies to a very first message in a channel.

• migrate_to_chat_id (int, optional) – The group has been migrated to a supergroup with the specified identifier. This number may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it is smaller than 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing this identifier.

• migrate_from_chat_id (int, optional) – The supergroup has been migrated from a group with the specified identifier. This number may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it is smaller than 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing this identifier.

• pinned_message (Message, optional) – Specified message was pinned. Note that the Message object in this field will not contain further reply_to_message fields even if it is itself a reply.

• game_high_score (GameHighScore, optional) – The game score for a user. The reply_to_message field will contain the game Message.

• views (int, optional) – Channel post views.

• forwards (int, optional) – Channel post forwards.

• via_bot (User) – The information of the bot that generated the message from an inline query of a user.

• outgoing (bool, optional) – Whether the message is incoming or outgoing. Messages received from other chats are incoming (outgoing is False). Messages sent from yourself to other chats are outgoing (outgoing is True). An exception is made for your own personal chat; messages sent there will be incoming.

• external_reply (ExternalReplyInfo, optional) – Information about the message that is being replied to, which may come from another chat or forum topic.

• quote (TextQuote, optional) – Chosen quote from the replied message.

• matches (List of regex Matches, *optional*) – A list containing all Match Objects that match the text of this message. Only applicable when using Filters.regex.

• command (List of str, optional) – A list containing the command and its arguments, if any. E.g.: “/start 1 2 3” would produce [“start”, “1”, “2”, “3”]. Only applicable when using command.

• forum_topic_created (ForumTopicCreated, optional) – Service message: forum topic created

• forum_topic_closed (ForumTopicClosed, optional) – Service message: forum topic closed

• forum_topic_reopened (ForumTopicReopened, optional) – Service message: forum topic reopened

• forum_topic_edited (ForumTopicEdited, optional) – Service message: forum topic edited

• general_forum_topic_hidden (GeneralForumTopicHidden, optional) – Service message: general forum topic hidden

• general_forum_topic_unhidden (GeneralForumTopicUnhidden, optional) – Service message: general forum topic unhidden

• video_chat_scheduled (VideoChatScheduled, optional) – Service message: voice chat scheduled.

• history_cleared (HistoryCleared, optional) – Service message: history cleared

• video_chat_started (VideoChatStarted, optional) – Service message: the voice chat started.

• video_chat_ended (VideoChatEnded, optional) – Service message: the voice chat has ended.

• video_chat_members_invited (VoiceChatParticipantsInvited, optional) – Service message: new members were invited to the voice chat.

• phone_call_started (PhoneCallStarted, optional) – Service message: phone call started.

• phone_call_ended (PhoneCallEnded, optional) – Service message: phone call ended.

• web_app_data (WebAppData, optional) – Service message: web app data sent to the bot.

• paid_messages_refunded (PaidMessagesRefunded, optional) – Service message: paid messages refunded.

• paid_messages_price_changed (PaidMessagesPriceChanged, optional) – Service message: paid messages price.

• direct_message_price_changed (DirectMessagePriceChanged, optional) – Service message: direct messages price.

• checklist_tasks_done (ChecklistTasksDone, optional) – Service message: checklist tasks done.

• checklist_tasks_added (ChecklistTasksAdded, optional) – Service message: checklist tasks added.

• premium_gift_code (PremiumGiftCode, optional) – Service message: premium gift code information.

• gifted_premium (GiftedPremium, optional) – Service message: gifted premium information.

• gifted_stars (GiftedStars, optional) – Service message: gifted stars information.

• gifted_ton (GiftedTon, optional) – Service message: gifted ton information.

• gift (Gift, optional) – Service message: star gift information.

• is_prepaid_upgrade (bool, optional) – True, if the messages is about prepaid upgrade of the gift by another user.

• is_from_auction (bool, optional) – True, if the message is a notification about a gift won on an auction.

• suggest_profile_photo (Photo, optional) – Service message: suggested profile photo.

• suggest_birthday (Birthday, optional) – Service message: suggested birthday.

• users_shared (UsersShared, optional) – Service message: users shared information.

• chat_shared (ChatShared, optional) – Service message: chat shared information.

• successful_payment (SuccessfulPayment, optional) – Service message: successful payment.

• refunded_payment (RefundedPayment, optional) – Service message: refunded payment.

• suggested_post_approval_failed (SuggestedPostApprovalFailed, optional) – Service message: suggested post approval failed.

• suggested_post_approved (SuggestedPostApproved, optional) – Service message: suggested post approved.

• suggested_post_declined (SuggestedPostDeclined, optional) – Service message: suggested post declined.

• suggested_post_paid (SuggestedPostPaid, optional) – Service message: suggested post paid.

• suggested_post_refunded (SuggestedPostRefunded, optional) – Service message: suggested post refunded.

• giveaway_created (bool, optional) – Service message: giveaway launched.

• giveaway_winners (GiveawayWinners, optional) – A giveaway with public winners was completed.

• giveaway_completed (GiveawayCompleted, optional) – Service message: a giveaway without public winners was completed.

• managed_bot_created (ManagedBotCreated, optional) – Service message: user created a bot that will be managed by the current bot.

• poll_option_added (PollOptionAdded, optional) – Service message: answer option was added to a poll.

• poll_option_deleted (PollOptionDeleted, optional) – Service message: answer option was deleted from a poll.

• chat_set_theme (ChatTheme, optional) – Service message: The chat theme was changed.

• chat_set_background (ChatBackground, optional) – Service message: The chat background was changed.

• set_message_auto_delete_time (int, optional) – Service message: The auto-delete or self-destruct timer for messages in the chat has been changed.

• chat_boost (int, optional) – Service message: The chat was boosted by the sender of the message. Number of times the chat was boosted.

• write_access_allowed (WriteAccessAllowed, optional) – Service message: the user allowed the bot to write messages after adding it to the attachment or side menu, launching a Web App from a link, or accepting an explicit request from a Web App sent by the method requestWriteAccess

• connected_website (str, optional) – The domain name of the website on which the user has logged in. More about Telegram Login

• contact_registered (ContactRegistered, optional) – Service message: Contact registered in Telegram.

• proximity_alert_triggered (ProximityAlertTriggered, optional) – Service message: A user in the chat came within proximity alert range.

• giveaway_prize_stars (GiveawayPrizeStars, optional) – Service message: Stars were received by the current user from a giveaway.

• screenshot_taken (ScreenshotTaken, optional) – Service message: screenshot of a message in the chat has been taken.

• upgraded_gift_purchase_offer (UpgradedGiftPurchaseOffer, optional) – Service message: An offer to purchase an upgraded gift was sent or received.

• upgraded_gift_purchase_offer_rejected (UpgradedGiftPurchaseOfferRejected, optional) – Service message: An offer to purchase a gift was rejected or expired.

• chat_has_protected_content_toggled (ChatHasProtectedContentToggled, optional) – Service message: An has_protected_content setting was changed or request to change it was rejected in a chat.

• chat_has_protected_content_disable_requested (ChatProtectedContentDisableRequested, optional) – Service message: An process requested to disable has_protected_content in a chat.

• business_connection_id (str, optional) – Unique identifier of the business connection from which the message was received. If non-empty, the message belongs to a chat of the corresponding business account that is independent from any potential bot chat which might share the same identifier. This update may at times be triggered by unavailable changes to message fields that are either unavailable or not actively used by the current bot.

• guest_query_id (str, optional) – Unique identifier of the guest query that triggered this message. Present only for messages received via guest mode (UpdateBotGuestChatQuery). Use answer_guest_query() with this ID to reply.

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

• reactions (MessageReactions) – Reactions of this message.

• send_paid_messages_stars (int, optional) – The number of Telegram Stars the sender paid to send the message.

• raw (Message, optional) – The raw message object, as received from the Telegram API.

• link (str, property) – Generate a link to this message, only for groups and channels.

• content (str, property) – The text or caption content of the message.

• unread_media (bool, optional) – True, if there are unread media attachments in this message.

• silent (bool, optional) – True, if the message sent without notification.

• legacy (bool, optional) – True, if the message is a legacy message. This means that the message is based on the old layer and should be refetched with the new layer.

• pinned (bool, optional) – True, if the message is pinned.

• restriction_reason (List of RestrictionReason, optional) – Contains a list of human-readable description of the reason why access to this message must be restricted.

• fact_check (FactCheck, optional) – Information about fact-check added to the message.

• suggested_post_info (SuggestedPostInfo, optional) – Information about the suggested post.

• channel_post (bool, optional) – True, if the message is a channel post.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• summary_language_code (str, optional) – IETF language tag of the message language on which it can be summarized. None if summary isn’t available for the message.

• guest_bot_caller (Chat, optional) – The user or chat which used a guest bot to send the message.

answer_animation(animation, caption='', parse_mode=None, caption_entities=None, has_spoiler=None, show_caption_above_media=None, duration=0, width=0, height=0, thumb=None, disable_notification=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, progress=None, progress_args=())

Shortcut for method send_animation will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

• has_spoiler (bool, optional) – Pass True if the animation needs to be covered with a spoiler animation.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be shown above the message media.

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

• width (int, optional) – Animation width.

• height (int, optional) – Animation height.

• thumb (str | BinaryIO, 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.

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_audio(audio, caption='', parse_mode=None, caption_entities=None, duration=0, performer=None, title=None, thumb=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_audio will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

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

• performer (str, optional) – Performer.

• title (str, optional) – Track name.

• thumb (str | BinaryIO, 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.

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_contact(phone_number, first_name, last_name='', vcard='', disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_contact will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

Parameters:

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

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

answer_document(document, thumb=None, caption='', parse_mode=None, caption_entities=None, file_name=None, force_document=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, protect_content=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_document will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

• thumb (str | BinaryIO, 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 (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

• file_name (str, optional) – File name of the document sent. Defaults to file’s path basename.

• force_document (bool, optional) – Pass True to force sending files as document. Useful for video files that need to be sent as document messages instead of video messages. Defaults to False.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_game(game_short_name, disable_notification=None, message_thread_id=None, effect_id=<class 'NoneType'>, reply_parameters=None, allow_paid_broadcast=None, reply_markup=None)

Shortcut for method send_game will automatically fill method attributes:

• chat_id

• message_thread_id

Example

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

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For supergroups only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

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

reply_invoice(title, description, payload, currency, prices, message_thread_id=None, provider_token=None, max_tip_amount=None, suggested_tip_amounts=None, start_parameter=None, provider_data=None, photo_url=None, photo_size=None, photo_width=None, photo_height=None, need_name=None, need_phone_number=None, need_email=None, need_shipping_address=None, send_phone_number_to_provider=None, send_email_to_provider=None, is_flexible=None, disable_notification=None, protect_content=None, message_effect_id=None, reply_parameters=None, allow_paid_broadcast=None, direct_messages_topic_id=None, suggested_post_parameters=None, subscription_expiration_date=None, reply_markup=None, caption='', parse_mode=None, caption_entities=None)

Shortcut for method send_invoice will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• reply_parameters

Parameters:

• title (str) – Product name, 1-32 characters.

• description (str) – Product description, 1-255 characters.

• payload (str | bytes) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.

• currency (str) – Three-letter ISO 4217 currency code, see more on currencies. Pass XTR for payments in Telegram Stars.

• prices (List of LabeledPrice) – Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in Telegram Stars.

• message_thread_id (int, optional) – If the message is in a thread, ID of the original message.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• provider_token (str, optional) – Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars.

• max_tip_amount (int, optional) – The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars.

• suggested_tip_amounts (List of int, optional) – An array of suggested amounts of tips in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount.

• start_parameter (str, optional) – Unique deep-linking parameter. If left empty, forwarded copies of the sent message will have a Pay button, allowing multiple users to pay directly from the forwarded message, using the same invoice. If non-empty, forwarded copies of the sent message will have a URL button with a deep link to the bot (instead of a Pay button), with the value used as the start parameter.

• provider_data (str, optional) – JSON-serialized data about the invoice, which will be shared with the payment provider. A detailed description of required fields should be provided by the payment provider.

• photo_url (str, optional) – URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service. People like it better when they see what they are paying for.

• photo_size (int, optional) – Photo size in bytes.

• photo_width (int, optional) – Photo width.

• photo_height (int, optional) – Photo height.

• need_name (bool, optional) – Pass True if you require the user’s full name to complete the order. Ignored for payments in Telegram Stars.

• need_phone_number (bool, optional) – Pass True if you require the user’s phone number to complete the order. Ignored for payments in Telegram Stars.

• need_email (bool, optional) – Pass True if you require the user’s email address to complete the order. Ignored for payments in Telegram Stars.

• need_shipping_address (bool, optional) – Pass True if you require the user’s shipping address to complete the order. Ignored for payments in Telegram Stars.

• send_phone_number_to_provider (bool, optional) – Pass True if the user’s phone number should be sent to the provider. Ignored for payments in Telegram Stars.

• send_email_to_provider (bool, optional) – Pass True if the user’s email address should be sent to the provider. Ignored for payments in Telegram Stars.

• is_flexible (bool, optional) – Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars.

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

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• message_effect_id (int 64-bit, optional) – Unique identifier of the message effect to be added to the message; for private chats only.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• subscription_expiration_date (int, optional) – Expiration date of the subscription, in Unix time. Currently the only allowed subscription period is 30*24*60*60 (1 month). For recurring payments only.

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

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

Returns:

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

answer_invoice(title, description, payload, currency, prices, message_thread_id=None, provider_token=None, max_tip_amount=None, suggested_tip_amounts=None, start_parameter=None, provider_data=None, photo_url=None, photo_size=None, photo_width=None, photo_height=None, need_name=None, need_phone_number=None, need_email=None, need_shipping_address=None, send_phone_number_to_provider=None, send_email_to_provider=None, is_flexible=None, disable_notification=None, protect_content=None, message_effect_id=None, reply_parameters=None, allow_paid_broadcast=None, direct_messages_topic_id=None, suggested_post_parameters=None, subscription_expiration_date=None, reply_markup=None, caption='', parse_mode=None, caption_entities=None)

Shortcut for method send_invoice will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

Parameters:

• title (str) – Product name, 1-32 characters.

• description (str) – Product description, 1-255 characters.

• payload (str | bytes) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.

• currency (str) – Three-letter ISO 4217 currency code, see more on currencies. Pass XTR for payments in Telegram Stars.

• prices (List of LabeledPrice) – Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in Telegram Stars.

• message_thread_id (int, optional) – If the message is in a thread, ID of the original message.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• provider_token (str, optional) – Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars.

• max_tip_amount (int, optional) – The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars.

• suggested_tip_amounts (List of int, optional) – An array of suggested amounts of tips in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount.

• start_parameter (str, optional) – Unique deep-linking parameter. If left empty, forwarded copies of the sent message will have a Pay button, allowing multiple users to pay directly from the forwarded message, using the same invoice. If non-empty, forwarded copies of the sent message will have a URL button with a deep link to the bot (instead of a Pay button), with the value used as the start parameter.

• provider_data (str, optional) – JSON-serialized data about the invoice, which will be shared with the payment provider. A detailed description of required fields should be provided by the payment provider.

• photo_url (str, optional) – URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service. People like it better when they see what they are paying for.

• photo_size (int, optional) – Photo size in bytes.

• photo_width (int, optional) – Photo width.

• photo_height (int, optional) – Photo height.

• need_name (bool, optional) – Pass True if you require the user’s full name to complete the order. Ignored for payments in Telegram Stars.

• need_phone_number (bool, optional) – Pass True if you require the user’s phone number to complete the order. Ignored for payments in Telegram Stars.

• need_email (bool, optional) – Pass True if you require the user’s email address to complete the order. Ignored for payments in Telegram Stars.

• need_shipping_address (bool, optional) – Pass True if you require the user’s shipping address to complete the order. Ignored for payments in Telegram Stars.

• send_phone_number_to_provider (bool, optional) – Pass True if the user’s phone number should be sent to the provider. Ignored for payments in Telegram Stars.

• send_email_to_provider (bool, optional) – Pass True if the user’s email address should be sent to the provider. Ignored for payments in Telegram Stars.

• is_flexible (bool, optional) – Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars.

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

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• message_effect_id (int 64-bit, optional) – Unique identifier of the message effect to be added to the message; for private chats only.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• subscription_expiration_date (int, optional) – Expiration date of the subscription, in Unix time. Currently the only allowed subscription period is 30*24*60*60 (1 month). For recurring payments only.

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

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

Returns:

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

answer_location(latitude, longitude, horizontal_accuracy=None, live_period=None, heading=None, proximity_alert_radius=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_location will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

Parameters:

• latitude (float) – Latitude of the location.

• longitude (float) – Longitude of the location.

• horizontal_accuracy (float, optional) – The radius of uncertainty for the location, measured in meters, 0-1500.

• live_period (int, optional) – For live locations, a period for which the location can be updated, in seconds. Must be between 60 and 86400 for a temporary live location, 0x7FFFFFFF for permanent live location.

• heading (int, optional) – For live locations, a direction in which the user is moving, in degrees. Must be between 1 and 360 if specified.

• proximity_alert_radius (int, optional) – For live locations, a maximum distance for proximity alerts about approaching another chat member, in meters. Must be between 1 and 100000 if specified. Can’t be enabled in channels and Saved Messages.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

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

answer_media_group(media, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, allow_paid_broadcast=None, paid_message_star_count=None)

Shortcut for method send_media_group will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

Parameters:

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

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

Returns:

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

Raises:

RPCError – In case of a Telegram RPC error.

answer_photo(photo, caption='', parse_mode=None, caption_entities=None, has_spoiler=None, show_caption_above_media=None, ttl_seconds=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, view_once=None, protect_content=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_photo will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

• has_spoiler (bool, optional) – Pass True if the photo needs to be covered with a spoiler animation.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be shown above the message media.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• view_once (bool, optional) – Self-Destruct Timer. If True, the photo will self-destruct after it was viewed.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_poll(question, options, media=None, message_thread_id=None, business_connection_id=None, is_anonymous=True, type=pyrogram.enums.PollType.REGULAR, allows_multiple_answers=None, allows_revoting=None, members_only=None, country_codes=None, shuffle_options=None, allow_adding_options=None, hide_results_until_closes=None, correct_option_ids=None, correct_option_id=None, explanation=None, open_period=None, close_date=None, is_closed=None, description=None, disable_notification=None, protect_content=None, allow_paid_broadcast=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_poll will automatically fill method attributes:

• chat_id

• message_thread_id

• business_connection_id

Example

await message.answer_poll("This is a poll", ["A", "B", "C"])

Parameters:

• question (str | FormattedText) – Poll question, 1-255 characters (up to 300 characters for bots). Only custom emoji entities are allowed to be added and only by Premium users.

• options (List of str | List of InputPollOption) – List of 1-12 answer options.

• media (InputMediaPhoto | InputMediaVideo | InputMediaSticker | Location, optional) – Media attached to the poll. Currently supports only photo, video, sticker or location.

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• business_connection_id (str, optional) – Unique identifier of the business connection on behalf of which the message will be sent.

• is_anonymous (bool, optional) – True, if the poll needs to be anonymous. Defaults to True.

• type (PollType, optional) – Poll type, QUIZ or REGULAR. Defaults to REGULAR.

• allows_multiple_answers (bool, optional) – Pass True, if the poll allows multiple answers.

• allows_revoting (bool, optional) – Pass True, if the poll allows to change chosen answer options.

• members_only (bool, optional) – True, if only the users that are members of the chat for more than a day will be able to vote. For channel chats only.

• country_codes (List of str, optional) – The list of two-letter ISO 3166-1 alpha-2 codes of countries, users from which will be able to vote. For channel chats only.

• shuffle_options (bool, optional) – Pass True, if the poll options must be shown in random order.

• allow_adding_options (bool, optional) – Pass True, if answer options can be added to the poll after creation.

• hide_results_until_closes (bool, optional) – Pass True, if poll results must be shown only after the poll closes.

• correct_option_ids (List of int, optional) – List of 0-based identifiers of the correct answer options, required for polls in quiz mode.

• correct_option_id (int, optional) – 0-based identifier of the correct answer option for single-answer quizzes. Alternative to correct_option_ids.

• explanation (str | FormattedText, optional) – Text shown when a user chooses an incorrect answer in a quiz-style poll.

• open_period (int, optional) – Amount of time in seconds the poll will be active after creation, 5-2628000.

• close_date (datetime, optional) – Point in time when the poll will be automatically closed.

• is_closed (bool, optional) – Pass True, if the poll needs to be immediately closed.

• description (str | FormattedText, optional) – Description of the poll to be sent, 0-1024 characters after entities parsing.

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

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply, optional) – Additional interface options.

Returns:

On success, the sent Message is returned.

Raises:

RPCError – In case of a Telegram RPC error.

reply_dice(emoji='🎲', disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, suggested_post_parameters=None, schedule_date=None, protect_content=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_dice will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

• reply_parameters

Parameters:

• emoji (str, optional) – Emoji on which the dice throw animation is based. Currently, must be one of “🎲”, “🎯”, “🏀”, “âš½”, “🎳”, or “🎰”. Dice can have values 1-6 for “🎲”, “🎯” and “🎳”, values 1-5 for “🏀” and “âš½”, and values 1-64 for “🎰”. Defaults to “🎲”.

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

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• 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 dice message is returned.

answer_dice(emoji='🎲', disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, suggested_post_parameters=None, schedule_date=None, protect_content=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_dice will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

Parameters:

• emoji (str, optional) – Emoji on which the dice throw animation is based. Currently, must be one of “🎲”, “🎯”, “🏀”, “âš½”, “🎳”, or “🎰”. Dice can have values 1-6 for “🎲”, “🎯” and “🎳”, values 1-5 for “🏀” and “âš½”, and values 1-64 for “🎰”. Defaults to “🎲”.

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

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• 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 dice message is returned.

answer_sticker(sticker, emoji='', caption='', parse_mode=None, caption_entities=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_sticker will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

• emoji (str, optional) – Emoji associated with this sticker.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_venue(latitude, longitude, title, address, foursquare_id='', foursquare_type='', disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_venue will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

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

answer_video(video, caption='', parse_mode=None, caption_entities=None, has_spoiler=None, show_caption_above_media=None, ttl_seconds=None, view_once=None, duration=0, width=0, height=0, video_start_timestamp=None, video_cover=None, thumb=None, supports_streaming=True, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, no_sound=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_video will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

• has_spoiler (bool, optional) – Pass True if the video needs to be covered with a spoiler animation.

• show_caption_above_media (bool, optional) – Pass True to show the video caption above the video.

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

• view_once (bool, optional) – Self-Destruct Timer. If True, the photo will self-destruct after it was viewed.

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

• width (int, optional) – Video width.

• height (int, optional) – Video height.

• video_start_timestamp (int, optional) – Video startpoint, in seconds.

• video_cover (str | BinaryIO, optional) – Video cover. Pass a file_id as string to attach a photo that exists on the Telegram servers, pass an HTTP URL as a string for Telegram to get a photo from the Internet, pass a file path as string to upload a new photo that exists on your local machine, or pass a binary file-like object with its attribute “.name” set for in-memory uploads.

• thumb (str | BinaryIO, 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.

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• no_sound (bool, optional) – Pass True, if the uploaded video is a video message with no sound. Doesn’t work for external links.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_video_note(video_note, duration=0, length=1, thumb=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, protect_content=None, view_once=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_video_note will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• length (int, optional) – Video width and height.

• thumb (str | BinaryIO, 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.

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• view_once (bool, optional) – Self-Destruct Timer. If True, the video note will self-destruct after it was viewed.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

answer_voice(voice, caption='', parse_mode=None, caption_entities=None, duration=0, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, view_once=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None, progress=None, progress_args=())

Shortcut for method send_voice will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

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.

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

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• view_once (bool, optional) – Self-Destruct Timer. If True, the voice note will self-destruct after it was listened.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• 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 file transmission progress. The function must take (current, total) as positional arguments (look at Other Parameters below for a detailed description) and will be called back each time a new file chunk has been successfully transmitted.

• progress_args (tuple, optional) – Extra custom arguments for the progress callback function. You can pass anything you need to be available in the progress callback scope; for example, a Message object or a Client instance in order to edit the message with the updated progress status.

Other Parameters:

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

• total (int) – The total 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.

reply_paid_media(stars_amount, media, caption='', payload=None, parse_mode=None, caption_entities=None, disable_notification=None, direct_messages_topic_id=None, reply_parameters=None, suggested_post_parameters=None, schedule_date=None, protect_content=None, show_caption_above_media=None)

Shortcut for method send_paid_media will automatically fill method attributes:

• chat_id

• direct_messages_topic_id

• business_connection_id

• reply_parameters

Parameters:

• stars_amount (int) – The number of Telegram Stars that must be paid to buy access to the media.

• media (List of InputMediaPhoto, InputMediaVideo) – A list describing photos and videos to be sent, must include 1–10 items.

• caption (str, optional) – Media caption, 0-1024 characters after entities parsing.

• invoice_payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

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

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be shown above the message media.

Returns:

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

answer_paid_media(stars_amount, media, caption='', payload=None, parse_mode=None, caption_entities=None, disable_notification=None, direct_messages_topic_id=None, reply_parameters=None, suggested_post_parameters=None, schedule_date=None, protect_content=None, show_caption_above_media=None)

Shortcut for method send_paid_media will automatically fill method attributes:

• chat_id

• direct_messages_topic_id

• business_connection_id

• reply_parameters

Parameters:

• stars_amount (int) – The number of Telegram Stars that must be paid to buy access to the media.

• media (List of InputMediaPhoto, InputMediaVideo) – A list describing photos and videos to be sent, must include 1–10 items.

• caption (str, optional) – Media caption, 0-1024 characters after entities parsing.

• invoice_payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.

• parse_mode (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

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

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be shown above the message media.

Returns:

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

answer_cached_media(file_id, caption='', parse_mode=None, caption_entities=None, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, reply_parameters=None, allow_paid_broadcast=None, paid_message_star_count=None, suggested_post_parameters=None, reply_markup=None)

Shortcut for method send_cached_media will automatically fill method attributes:

• chat_id

• message_thread_id

• direct_messages_topic_id

• business_connection_id

Parameters:

• 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 (ParseMode, optional) – By default, texts are parsed using both Markdown and HTML styles. You can combine both syntaxes together.

• caption_entities (List of MessageEntity) – List of special entities that appear in the caption, which can be specified instead of parse_mode.

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

• suggested_post_parameters (SuggestedPostParameters, optional) – Information about the suggested post.

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

get_media_group()

Shortcut for method get_media_group will automatically fill method attributes:

• chat_id

• message_id

Returns:

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

Raises:

ValueError – In case the passed message id doesn’t belong to a media group.

answer_inline_bot_result(query_id, result_id, disable_notification=None, message_thread_id=None, direct_messages_topic_id=None, reply_parameters=None, paid_message_star_count=None)

Shortcut for method send_inline_bot_result will automatically fill method attributes:

• chat_id

• direct_messages_topic_id

• message_thread_id

Parameters:

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

• message_thread_id (int, optional) – Unique identifier of a message thread to which the message belongs. For forums only.

• direct_messages_topic_id (int, optional) – Unique identifier of the topic in a channel direct messages chat administered by the current user. For directs only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

Returns:

Message – On success, the sent message is returned.

Raises:

RPCError – In case of a Telegram RPC error.

reply_checklist(checklist, disable_notification=None, protect_content=None, message_thread_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, paid_message_star_count=None, reply_markup=None, quote=None)

Shortcut for method send_checklist will automatically fill method attributes:

• chat_id

• message_thread_id

• business_connection_id

• reply_parameters

Example

await message.reply_checklist("To do", [
    types.InputChecklistTask(id=1, text="Task 1"),
    types.InputChecklistTask(id=2, text="Task 2")
])

Parameters:

• checklist (InputChecklist) – Checklist to send.

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

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

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

answer_checklist(checklist, disable_notification=None, protect_content=None, message_thread_id=None, effect_id=None, reply_parameters=None, schedule_date=None, repeat_period=None, paid_message_star_count=None, reply_markup=None)

Shortcut for method send_checklist will automatically fill method attributes:

• chat_id

• message_thread_id

• business_connection_id

Example

await message.reply_checklist("To do", [
    types.InputChecklistTask(id=1, text="Task 1"),
    types.InputChecklistTask(id=2, text="Task 2")
])

Parameters:

• checklist (InputChecklist) – Checklist to send.

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

• protect_content (bool, optional) – Protects the contents of the sent message from forwarding and saving.

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• effect_id (int, optional) – Unique identifier of the message effect. For private chats only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• repeat_period (int, optional) – Period after which the message will be sent again in seconds.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

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

edit_checklist(checklist, reply_markup=None)

Shortcut for method edit_message_checklist will automatically fill method attributes:

• chat_id

• message_id

• business_connection_id

Parameters:

• checklist (InputChecklist) – New checklist.

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

Returns:

On success, the edited Message is returned.

Raises:

RPCError – In case of a Telegram RPC error.

edit_live_location(latitude, longitude, horizontal_accuracy=None, live_period=None, heading=None, proximity_alert_radius=None)

Use this method to edit live location messages.

Parameters:

• latitude (float) – Latitude of the location.

• longitude (float) – Longitude of the location.

• horizontal_accuracy (float, optional) – The radius of uncertainty for the location, measured in meters, 0-1500.

• live_period (int, optional) – New period in seconds during which the location can be updated, starting from the message send date. If 0x7FFFFFFF is specified, then the location can be updated forever. Otherwise, the new value must not exceed the current live_period by more than a day, and the live location expiration date must remain within the next 90 days. If not specified, then live_period remains unchanged.

• heading (int, optional) – For live locations, a direction in which the user is moving, in degrees. Must be between 1 and 360 if specified.

• proximity_alert_radius (int, optional) – For live locations, a maximum distance for proximity alerts about approaching another chat member, in meters. Must be between 1 and 100000 if specified. Can’t be enabled in channels and Saved Messages.

Returns:

On success, the edited Message is returned.

stop_live_location()

Use this method to stop updating a live location message before live_period expires.

Returns:

On success, the edited Message is returned.

copy_media_group(chat_id, captions=None, has_spoilers=None, disable_notification=None, message_thread_id=None, reply_parameters=None, schedule_date=None, show_caption_above_media=None, allow_paid_broadcast=None, paid_message_star_count=None, reply_to_message_id=None, reply_to_chat_id=None, reply_to_story_id=None, quote_text=None, parse_mode=None, quote_entities=None, quote_offset=None)

Shortcut for method copy_media_group will automatically fill method attributes:

• from_chat_id

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

• captions (str | List of str , optional) – New caption for media, 0-1024 characters after entities parsing for each media. If not specified, the original caption is kept. Pass “” (empty string) to remove the caption.

  If a str is passed, it becomes a caption only for the first media. If a list of str passed, each element becomes caption for each media element. You can pass None in list to keep the original caption.

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

• message_thread_id (int, optional) – Unique identifier for the target message thread (topic) of the forum. For supergroups only.

• reply_parameters (ReplyParameters, optional) – Describes reply parameters for the message that is being sent.

• schedule_date (datetime, optional) – Date when the message will be automatically sent.

• show_caption_above_media (bool, optional) – Pass True, if the caption must be shown above the message media.

• allow_paid_broadcast (bool, optional) – If True, you will be allowed to send up to 1000 messages per second. Ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot’s balance. For bots only.

• paid_message_star_count (int, optional) – The number of Telegram Stars the user agreed to pay to send the messages.

Returns:

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

retract_vote()

Shortcut for method retract_vote will automatically fill method attributes:

• chat_id

• message_id

Returns:

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

Raises:

RPCError – In case of a Telegram RPC error.

vote(option)

Shortcut for method vote_poll will automatically fill method attributes:

• chat_id

• message_id

Parameters:

option (int | List of int) – Index or list of indexes (for multiple answers) of the poll option(s) you want to vote for (0 to 11).

Returns:

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

Raises:

RPCError – In case of a Telegram RPC error.

view()

Shortcut for method view_messages will automatically fill method attributes:

• chat_id

• message_id

Returns:

True on success.

Raises:

RPCError – In case of a Telegram RPC error.

pay()

Bound method pay of Message.

Use as a shortcut for:

invoice = types.InputInvoiceMessage(
        chat_id=chat_id,
        message_id=123
    )

form = await app.get_payment_form(invoice)

await app.send_payment_form(
    payment_form_id=form.id,
    input_invoice=invoice
)

Example

await message.pay()

Returns:

PaymentResult – On success, the payment result is returned.

accept_gift_purchase_offer()

Shortcut for method process_gift_purchase_offer will automatically fill method attributes:

• message_id

Returns:

Message – On success, the sent message is returned.

reject_gift_purchase_offer()

Shortcut for method process_gift_purchase_offer will automatically fill method attributes:

• message_id

Returns:

Message – On success, the sent message is returned.

summarize(translate_to_language_code=None)

Shortcut for method summarize_message will automatically fill method attributes:

• chat_id

• message_id

• translate_to_language_code

Parameters:

translate_to_language_code (str, optional) – Language code of the language to which the message is translated. Must be one of “af”, “sq”, “am”, “ar”, “hy”, “az”, “eu”, “be”, “bn”, “bs”, “bg”, “ca”, “ceb”, “zh-CN”, “zh”, “zh-Hans”, “zh-TW”, “zh-Hant”, “co”, “hr”, “cs”, “da”, “nl”, “en”, “eo”, “et”, “fi”, “fr”, “fy”, “gl”, “ka”, “de”, “el”, “gu”, “ht”, “ha”, “haw”, “he”, “iw”, “hi”, “hmn”, “hu”, “is”, “ig”, “id”, “in”, “ga”, “it”, “ja”, “jv”, “kn”, “kk”, “km”, “rw”, “ko”, “ku”, “ky”, “lo”, “la”, “lv”, “lt”, “lb”, “mk”, “mg”, “ms”, “ml”, “mt”, “mi”, “mr”, “mn”, “my”, “ne”, “no”, “ny”, “or”, “ps”, “fa”, “pl”, “pt”, “pa”, “ro”, “ru”, “sm”, “gd”, “sr”, “st”, “sn”, “sd”, “si”, “sk”, “sl”, “so”, “es”, “su”, “sw”, “sv”, “tl”, “tg”, “ta”, “tt”, “te”, “th”, “tr”, “tk”, “uk”, “ur”, “ug”, “uz”, “vi”, “cy”, “xh”, “yi”, “ji”, “yo”, “zu” Defaults to the client’s language code.

Returns:

FormattedText – On success, information about the summarized text is returned.

Raises:

ValueError – In case of this message can’t be summarized.