TelegramBot

TelegramBot

class TelegramBot(bot_token)

The base class to interact with the Telegram SDK

Parameters

bot_token (String) – Insert here the bot token received by the Botfather

set_callback_method(self, method)

This method is used to define the callback method to handle incoming updates

Parameters

method (method) – Method to call

get_updates(self, *, offset=None, limit=None, timeout=None, allowed_updates=None) → list

Call this method to receive Messages

Parameters
  • offset (int) – Optional: Only updates with an id greater or equal the offset are returned

  • limit (int) – Optional: Set a limit how many Updates are returned

  • timeout (int) – Optional: Set the timeout for long polling

  • allowed_updates (list of str) – Optional: Specify the type of updates that are allowed to returned

Returns

Returns list of Updates

Return type

list of Update

get_me(self) → telegram_bot_sdk.telegram_objects.user.User

Get information about the bot

Returns

Returns an user instance which holds the information about the bot

Return type

User

get_chat(self, chat_id) → telegram_bot_sdk.telegram_objects.chat.Chat

Use this method to get information about a chat

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Chat object

Return type

Chat

send_message(self, *, chat_id, text, parse_mode=None, disable_web_page_preview=None, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This method is used to send messages.

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • text (str) – Text of the message to be sent

  • parse_mode (str) – Optional: “Markdown” or “HTML” to use the Markdown or HTML parser

  • disable_web_page_preview (bool) – Optional: Disables link previews for links in this message

  • disable_notification (bool) – Optional: Sends the message silently

  • reply_to_message_id (int) – ID of the original message if message is a reply

  • reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply) – Additional interface options. A JSON-Serialized object.

Returns

On success, the send Message is returned

Return type

Message

get_user_profile_photos(self, *, user_id, offset=None, limit=None) → telegram_bot_sdk.telegram_objects.userProfilePhotos.UserProfilePhotos

Get a list of profile pictures for a user

Parameters
  • user_id (int) – Unique id of the target

  • offset (int) – Optional: Sequential number of the first photo to be returned. By default, all photos are returned

  • limit (int) – Optional: Limits the number of photos to be retrieved. Values between 1 and 100 are accepted. Defaults to 100

Returns

Returns an UserProfilePhotos object

Return type

UserProfilePhotos

send_location(self, *, chat_id, latitude, longitude, live_period=None, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This method is used to send locations

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • latitude (float) – Latitude of the location

  • longitude (float) – Longitude of the location

  • live_period (int) – Optional: Period in seconds for which the location will be updated, should be between 60-864000

  • disable_notification (bool) – Optional: Sends the message silently

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

  • reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply) – Additional interface options

Returns

On success the sent message is returned

Return type

Message

send_venue(self, *, chat_id, latitude, longitude, title, address, foursquare_id=None, foursquare_type=None, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This method is user to send information about a venue

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • 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

  • disable_notification (bool) – Optional: Sends the message silently

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

  • reply_markup (InlineKeyboardMarkup or object_reply_keyboard_markup or ReplyKeyboardRemove or ForceReply) – Additional interface options

Returns

On success the sent message is returned

Return type

Message

send_contact(self, *, chat_id, phone_number, first_name, last_name=None, vcard=None, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This method is used to send phone contacts

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • 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

  • disable_notification (bool) – Optional: Sends the message silently

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

  • reply_markup (InlineKeyboardMarkup or object_reply_keyboard_markup or ReplyKeyboardRemove or ForceReply) – Optional: Additional interface options

Returns

On success the sent message is returned

Return type

Message

send_poll(self, *, chat_id, question, options, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This message is used to send a native poll. A native poll can’t be send to a private chat.

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

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

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

  • disable_notification (bool) – Optional: Sends the message silently

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

  • reply_markup (InlineKeyboardMarkup or object_reply_keyboard_markup or ReplyKeyboardRemove or ForceReply) – Optional: Additional interface

Returns

On success the sent message is returned

Return type

Message

send_chat_action(self, *, chat_id, action) → bool

This method is used to send chat action

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • action (str) – Type of action to broadcast. Options: typing, upload_photo, record_video or upload_video, record_audio or upload_audio, upload_document, find_location, record_video_note or upload_video_note

Returns

Returns True on success

Return type

bool

get_file(self, file_id) → telegram_bot_sdk.telegram_objects.file.File

This method is used to get basic information about a file and prepare it for downloading

Parameters

file_id – File identifier to get info about

Returns

Returns File object on success

Return type

object_file

kick_chat_member(self, *, chat_id, user_id, until_date=None) → bool

This method is used to kick a user from a group, a supergroup or a channel

Parameters
  • chat_id (int or str) – Unique identifier for the target group or username of the target supergroup or channel (format @channelusername)

  • user_id (int) – Unique identifier of the target user

  • until_date (int) – Optional: Date when the user will be banned, unix time. If the user is banned for more than 366 days or less than 30 seconds from the current time they are considered to be banned forever

Returns

Returns True on success

Return type

bool

unban_chat_member(self, *, chat_id, user_id) → bool

This method is used to unban a previously kicked user in a supergroup or channel

Parameters
  • chat_id (int or str) – Unique identifier for the target group or username of the target supergroup or channel (format @username)

  • user_id (int) – Unique identifier of the target user

Returns

Returns true on success

Return type

bool

restrict_chat_member(self, *, chat_id, user_id, permissions, until_date=None) → bool

This method is used to restrict a user in a supergroup

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target supergroup (format @supergroupname)

  • user_id (int) – Unique identifier of the target user

  • permissions (ChatPermissions) – New user permissions

  • until_date – Optional: Date when restrictions will be lifted for the user, unix time. If the user is restricted for more than 366 days or less than 30 seconds from the current time, they are considered to be restricted forever

Returns

Return True on success

Return type

bool

promote_chat_member(self, *, chat_id, user_id, can_change_info=None, can_post_messages=None, can_edit_messages=None, can_delete_messages=None, can_invite_users=None, can_restrict_members=None, can_pin_messages=None, can_promote_members=None) → bool

This method is used to promote or demote a user in a supergroup or a channel

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • user_id (int) – Unique identifier of the target user

  • can_change_info (bool) – Optional: Pass True, if the administrator can change title, photo and other settings

  • can_post_messages (bool) – Optional: Pass True, if the administrator can create channel posts, channels only

  • can_edit_messages (bool) – Optional: Pass True, if the administrator can edit messages of other users and can pin messages, channels only

  • can_delete_messages (bool) – Optional: Pass True, if the administrator can delete messages of other users

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

  • can_restrict_members (bool:) – Optional: Pass True, if the administrator can restrict, ban or unban chat chat members

  • can_pin_messages (bool) – Optional: Pass True, if the administrator can pin messages, supergroups only

  • can_promote_members (bool) – Optional: Pass True, if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted (directly or indirectly)

Returns

Returns True on success

Return type

bool

set_chat_permissions(self, *, chat_id, permissions=None) → bool

This method is used to set default chat permissions for all members

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target supergroup (format @supergroupname)

  • permissions (ChatPermissions) – New default chat permissions

Returns

Returns True on success

Return type

bool

set_chat_title(self, *, chat_id, title) → bool

This method is used to change the title of a chat

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • title (str) – New chat title, 1-255 characters

Returns

Return True on success

Return type

bool

set_chat_description(self, *, chat_id, description=None) → bool

This method is used to change the description of a group, a supergroup or a channel

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • description – New chat description, 0-255 characters

Returns

Returns True on success

Return type

bool

pin_chat_message(self, *, chat_id, message_id, disable_notification=None) → bool

This method is used to pin a message in a group, a supergroup or in a channel

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Identifier of a message to pin

  • disable_notification (bool) – Optional: Pass True, if it is not necessary to send a notification to all chat members about the new pinned message

Returns

Returns True on success

Return type

bool

unpin_chat_message(self, chat_id) → bool

This method is used to unpin a message in a group, supergroup or channel

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Returns True on success

Return type

bool

leave_chat(self, chat_id) → telegram_bot_sdk.telegram_objects.chat.Chat

This method is used to leave a group, supergroup or channel

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Returns True on success

Return type

bool

get_chat_administrators(self, chat_id) → list

This method is used to get a list of administrators of a chat

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Returns a list of object_chat_member objects that contains information about all chat administrators except other bots

Return type

list of object_chat_member

get_chat_members_counter(self, chat_id) → int

This method is used to get the number of members in a chat

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Returns the count on success

Return type

int

get_chat_member(self, *, chat_id, user_id) → telegram_bot_sdk.telegram_objects.chatMember.ChatMember

This method is used to get information about a member of a chat

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • user_id (int) – Unique identifier of the target user

Returns

Returns a object_chat_member object on success

Return type

object_chat_member

set_chat_sticker_set(self, *, chat_id, sticker_set_name) → bool

This method is used to set a new group sticker set for a supergroup

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • sticker_set_name (str) – Name of the sticker set to be set as the group sticker set

Returns

Returns True on success

Return type

bool

delete_chat_sticker_set(self, chat_id) → bool

This method is used to delete a group sticker set from a supergroup

Parameters

chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

Returns

Returns True on success

Return type

bool

answer_callback_query(self, *, callback_query_id, text=None, show_alert=None, url=None, cache_time=None) → bool

This method is used to send answers to callback queries sent from inline keyboards

Parameters
  • callback_query_id (str) – Unique identifier for the query to be answered

  • text (str) – Optional: Text of the notification. If not specified, nothing will be shown to the user. 0-200 characters

  • show_alert (bool) – Optional: If True, an alert will be shown by the client instead of a notification at the top of the chat screen. Defaults to false

  • url (str) – Optional: URL that will be opened by the user’s client

  • cache_time (int) – Optional: The maximum amount of time in seconds that the result of the callback query may be cached client-side. Defaults to 0

Returns

Returns True on success

Return type

bool

edit_message_text(self, *, text, chat_id=None, message_id=None, inline_message_id=None, parse_mode=None, disable_web_page_preview=None, reply_markup=None) → Union[bool, telegram_bot_sdk.telegram_objects.message.Message]

This method is used to edit text and game messages

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

  • chat_id (int or str) – Optional: Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Optional: Required if inline_message_id is not specified, Identifier of the message to edit

  • inline_message_id (str) – Optional: Required if chat_id and message_id are not specified

  • parse_mode (str) – Optional: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot’s message

  • disable_web_page_preview (bool) – Optional: Disables link previews for links in this message

  • reply_markup (InlineKeyboardMarkup) – A JSON serialized object for an inline keyboard

Returns

Returns the edited Message, if the edited message is sent by the bot, otherwise True

Return type

bool or Message

edit_message_caption(self, *, chat_id=None, message_id=None, inline_message_id=None, caption=None, parse_mode=None, reply_markup=None) → Union[bool, telegram_bot_sdk.telegram_objects.message.Message]

This method is used to edit the caption of a message

Parameters
  • chat_id (int or str) – Optional: Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Optional: Required if inline_message_id is not specified. Identifier of the message to edit

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

  • caption (str) – Optional: New caption of the message

  • parse_mode (str) – Optional: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed- width text or inline URLs in the message caption.

  • reply_markup (InlineKeyboardMarkup) – Optional: A JSON-serialized object for an inline keyboard

Returns

Return the edited Message, if the edited message is sent by the bot, otherwise True

Return type

bool or Message

edit_message_media(self, *, media, chat_id=None, message_id=None, inline_message_id=None, reply_markup=None) → Union[bool, telegram_bot_sdk.telegram_objects.message.Message]

This method is used to edit animation, audio, document, photo or video messages. If a message is a part of a message album, then it can be edited only to a photo or a video. Otherwise, message type can be changed arbitrarily. When inline message is edited, new file can’t be uploaded. Use previously uploaded file via its file_id or specify a URL.

Parameters
  • media (object_input_media) – A JSON-serialized object for a new media content of the message

  • chat_id (int or str) – Optional: Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Optional: Optional: Required if inline_message_id is not specified. Identifier of the message to edit

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

  • reply_markup (InlineKeyboardMarkup) – Optional: A JSON-serialized object for a new media content of the message

Returns

Return the edited message, if the edited message is sent by the bot, otherwise True

Return type

bool or Message

edit_message_reply_markup(self, *, chat_id=None, message_id=None, inline_message_id=None, reply_markup=None) → Union[bool, telegram_bot_sdk.telegram_objects.message.Message]

This method is used to edit only the reply markup of messages

Parameters
  • chat_id (int or str) – Optional: Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel (format @channlerusername)

  • message_id (int) – Optional: Required if inline_message_id is not specified. Identifier of the message to edit

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

  • reply_markup (InlineKeyboardMarkup) – Optional: A JSON-serialized object for an inline keyboard

Returns

Return the edited message, if the edited message is sent by the bot, otherwise True

Return type

bool or Message

stop_poll(self, *, chat_id, message_id, reply_markup=None) → telegram_bot_sdk.telegram_objects.poll.Poll

This method is used to stop a poll which was sent by the bot

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Identifier of the original message with the poll

  • reply_markup – Optional: A JSON-serialized object for a new message inline keyboard

:type InlineKeyboardMarkup

Returns

Returns the stopped poll on success

Return type

Poll

delete_message(self, *, chat_id, message_id) → bool

This method is used to delete a message, including service messages, with the following limitations: * A message can only be deleted if it was sent less than 48 hours ago. * Bots can delete outgoing messages in private chats, groups, and supergroups. * Bots can delete incoming messages in private chats. * Bots granted can_post_messages permissions can delete outgoing messages in channels. * If the bot is an administrator of a group, it can delete any message there. * If the bot has can_delete_messages permission in a supergroup or a channel, it can delete any message there.

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • message_id (int) – Identifier of the message to delete

Returns

Returns True on success

Return type

bool

send_sticker(self, *, chat_id, sticker, disable_notification=None, reply_to_message_id=None, reply_markup=None) → telegram_bot_sdk.telegram_objects.message.Message

This method is used to send static .WEBP or animated .TGS stickers

Parameters
  • chat_id (int or str) – Unique identifier for the target chat or username of the target channel (format @channelusername)

  • sticker (object_input_file or str) – Sticker to send. Pass a file_id as str to send a file that exists on the Telegram servers (recommended), pass a HTTP URL as a str for Telegram to get .webp file from the internet or upload a new one using multipart/form-data

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

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

  • reply_markup (Optional: InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply) – Optional: Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user

Returns

Returns the sent message on success

Return type

Message

get_sticker_set(self, name) → telegram_bot_sdk.telegram_objects.stickerSet.StickerSet

This method is used to get a sticker set

Parameters

name (str) – Name of the sticker set

Returns

Returns a sticker set

Return type

object_sticker_set

upload_sticker_file(self, *, user_id, png_sticker) → telegram_bot_sdk.telegram_objects.file.File

This method is used to upload .png file with a sticker for later use in method_create_new_sticker_set and method_add_sticker_set methods

Parameters
  • user_id (int) – User identifier of sticker file owner

  • png_sticker (object_input_file) – PNG image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px

Returns

Returns the uploaded file

Return type

object_file

create_new_sticker_set(self, *, user_id, name, title, png_sticker, emojis, contains_mask=None, mask_position=None) → bool

This method is used to create a new sticker set owned by a user. The bot will be able to edit the created sticker set

Parameters
  • user_id (int) – User identifier of created sticker set owner

  • name (str) – Short name of sticker set, to be used in ``t.me/addstickers/``URLs. Can contain only english letters, digits and undersocres. Must begin with a leeter, can’t contain consecutive underscores and must end in “_by_<bot_username>”. <bot_username> is case insensitive. 1-64 characters

  • title (str) – Sticker set title, 1-64 characters

  • png_sticker (object_input_file or str) – PNG image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px. Pass a file_id as a str to send a file that already exists on the Telegram servers, pass a HTTP URL as a str for Telegram to get a file from the Internet, or upload a new one using multipart/form-data

  • emojis (str) – One or more emoji corresponding to the sticker

  • contains_mask (bool) – Optional: Pass True, if a set of mask stickers should be created

  • mask_position (MaskPosition) – Optional: A JSON.serialized object for position where the mask should be played on faces

Returns

Returns True on success

Return type

bool

add_sticker_to_set(self, user_id, name, png_sticker, emojis, mask_position=None) → bool

This method is used to add a set created by the bot

Parameters
  • user_id (int) – User identifier of sticker set owner

  • name (str) – Sticker set name

  • png_sticker (str or object_input_file) – PNG image with the sticker, must be up to 512 kb in size, dimensions must not exceed 512px and either width or height must exactly 512px. Pass a file_id as a str to send a file that already exists on the telegram servers, pass an HTTP URL as a str for telegram to get a file from the internet or upload a new one using multipart/form-data

  • emojis (str) – One or more emoji corresponding to the sticker

  • mask_position (MaskPosition) – Optional: A JSON-serialized object for position where the mask should be placed on faces

Returns

Returns True on success

Return type

bool

set_sticker_position_in_set(self, *, sticker, position) → bool

This method is used to move a sticker in a set created by the bot to a specific position

Parameters
  • sticker (str) – File identifier for the sticker

  • position (int) – New sticker position in the set, zero based

Returns

Returns True on success

Return type

bool

delete_sticker_from_set(self, sticker) → bool

This method is used to delete a sticker from a set created by the bot

Parameters

sticker (str) – File identifier for sticker

Returns

Returns True on success

Return type

bool