platypush.plugins.chat.telegram

class platypush.plugins.chat.telegram.ChatTelegramPlugin(api_token: str, **kwargs)[source]

Plugin to programmatically send Telegram messages through a Telegram bot. In order to send messages to contacts, groups or channels you’ll first need to register a bot. To do so:

  1. Open a Telegram conversation with the @BotFather.
  2. Send /start followed by /newbot. Choose a display name and a username for your bot.
  3. Copy the provided API token in the configuration of this plugin.
  4. Open a conversation with your newly created bot.

Requires:

  • python-telegram-bot (pip install python-telegram-bot)
__init__(api_token: str, **kwargs)[source]
Parameters:api_token

API token as returned by the @BotFather

delete_chat_photo(chat_id: Union[str, int], timeout: int = 20)[source]

Delete the photo of a channel/group.

Parameters:
  • chat_id – Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.
  • timeout – Request timeout (default: 20 seconds)
get_chat(chat_id: Union[int, str], timeout: int = 20) → platypush.message.response.chat.telegram.TelegramChatResponse[source]

Get the info about a Telegram chat.

Parameters:
  • chat_id – Chat ID.
  • timeout – Upload timeout (default: 20 seconds).
get_chat_administrators(chat_id: Union[int, str], timeout: int = 20) → platypush.message.response.chat.telegram.TelegramUsersResponse[source]

Get the list of the administrators of a chat.

Parameters:
  • chat_id – Chat ID.
  • timeout – Upload timeout (default: 20 seconds).
get_chat_members_count(chat_id: Union[int, str], timeout: int = 20) → int[source]

Get the number of users in a chat.

Parameters:
  • chat_id – Chat ID.
  • timeout – Upload timeout (default: 20 seconds).
get_chat_user(chat_id: Union[int, str], user_id: int, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramUserResponse[source]

Get the info about a user connected to a chat.

Parameters:
  • chat_id – Chat ID.
  • user_id – User ID.
  • timeout – Upload timeout (default: 20 seconds).
get_file(file_id: str, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramFileResponse[source]

Get the info and URL of an uploaded file by file_id.

Parameters:
  • file_id – File ID.
  • timeout – Upload timeout (default: 20 seconds).
kick_chat_member(chat_id: Union[str, int], user_id: int, until_date: Optional[datetime.datetime] = None, timeout: int = 20)[source]

Kick a user from a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • user_id – Unique user ID.
  • until_date – End date for the ban.
  • timeout – Request timeout (default: 20 seconds)
leave_chat(chat_id: Union[str, int], timeout: int = 20)[source]

Leave a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • timeout – Request timeout (default: 20 seconds)
pin_chat_message(chat_id: Union[str, int], message_id: int, disable_notification: Optional[bool] = None, timeout: int = 20)[source]

Pin a message in a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • message_id – Message ID.
  • disable_notification – If True then no notification will be sent to the users.
  • timeout – Request timeout (default: 20 seconds)
promote_chat_member(chat_id: Union[str, int], user_id: int, can_change_info: Optional[bool] = None, can_post_messages: Optional[bool] = None, can_edit_messages: Optional[bool] = None, can_delete_messages: Optional[bool] = None, can_invite_users: Optional[bool] = None, can_restrict_members: Optional[bool] = None, can_promote_members: Optional[bool] = None, can_pin_messages: Optional[bool] = None, timeout: int = 20)[source]

Promote or demote a member.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • user_id – Unique user ID.
  • can_change_info – Pass True if the user can change channel info.
  • can_post_messages – Pass True if the user can post messages.
  • can_edit_messages – Pass True if the user can edit messages.
  • can_delete_messages – Pass True if the user can delete messages.
  • can_invite_users – Pass True if the user can invite other users to the channel/group.
  • can_restrict_members – Pass True if the user can restrict the permissions of other users.
  • can_promote_members – Pass True if the user can promote mebmers.
  • can_pin_messages – Pass True if the user can pin messages.
  • timeout – Request timeout (default: 20 seconds)
send_animation(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, duration: Optional[int] = None, caption: Optional[str] = None, width: Optional[int] = None, height: Optional[int] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send an animation (GIF or H.264/MPEG-4 AVC video without sound) to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • duration – Duration in seconds.
  • caption – Optional caption for the picture.
  • width – Video width.
  • height – Video height.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_audio(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, caption: Optional[str] = None, performer: Optional[str] = None, title: Optional[str] = None, duration: Optional[float] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send audio to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • caption – Optional caption for the picture.
  • performer – Optional audio performer.
  • title – Optional audio title.
  • duration – Duration of the audio in seconds.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_contact(chat_id: Union[str, int], phone_number: str, first_name: str, last_name: Optional[str] = None, vcard: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a contact to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • phone_number – Phone number.
  • first_name – First name.
  • last_name – Last name.
  • vcard – Additional contact info in vCard format (0-2048 bytes).
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_document(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, filename: Optional[str] = None, caption: Optional[str] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a document to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • filename – Name of the file as it will be shown in Telegram.
  • caption – Optional caption for the picture.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_location(chat_id: Union[str, int], latitude: float, longitude: float, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a location to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • latitude – Latitude
  • longitude – Longitude
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_message(chat_id: Union[str, int], text: str, parse_mode: Optional[str] = None, disable_web_page_preview: bool = False, disable_notification: bool = False, reply_to_message_id: Optional[int] = None) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a message to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • text – Text to be sent.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_web_page_preview – If True then web previews for URLs will be disabled.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
send_photo(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, caption: Optional[str] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a picture to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • caption – Optional caption for the picture.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_venue(chat_id: Union[str, int], latitude: float, longitude: float, title: str, address: str, foursquare_id: Optional[str] = None, foursquare_type: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send the address of a venue to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • latitude – Latitude
  • longitude – Longitude
  • title – Venue name.
  • address – Venue address.
  • foursquare_id – Foursquare ID.
  • foursquare_type – Foursquare type.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_video(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, duration: Optional[int] = None, caption: Optional[str] = None, width: Optional[int] = None, height: Optional[int] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a video to a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • duration – Duration in seconds.
  • caption – Optional caption for the picture.
  • width – Video width.
  • height – Video height.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_video_note(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, duration: Optional[int] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send a video note to a chat. As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • duration – Duration in seconds.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
send_voice(chat_id: Union[str, int], file_id: Optional[int] = None, url: Optional[str] = None, path: Optional[str] = None, caption: Optional[str] = None, duration: Optional[float] = None, parse_mode: Optional[str] = None, disable_notification: bool = False, reply_to_message_id: Optional[int] = None, timeout: int = 20) → platypush.message.response.chat.telegram.TelegramMessageResponse[source]

Send audio to a chat as a voice file. For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as Audio or Document).

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • file_id – Set it if the file already exists on Telegram servers and has a file_id. Note that you’ll have to specify either file_id, url or path.
  • url – Set it if you want to send a file from a remote URL. Note that you’ll have to specify either file_id, url or path.
  • path – Set it if you want to send a file from the local filesystem. Note that you’ll have to specify either file_id, url or path.
  • caption – Optional caption for the picture.
  • duration – Duration of the voice in seconds.
  • parse_mode – Set to ‘Markdown’ or ‘HTML’ to send either Markdown or HTML content.
  • disable_notification – If True then no notification will be sent to the users.
  • reply_to_message_id – If set then the message will be sent as a response to the specified message.
  • timeout – Upload timeout (default: 20 seconds)
set_chat_description(chat_id: Union[str, int], description: str, timeout: int = 20)[source]

Set the description of a channel/group.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • description – New chat description.
  • timeout – Request timeout (default: 20 seconds)
set_chat_photo(chat_id: Union[str, int], path: str, timeout: int = 20)[source]

Set the photo of a channel/group.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • path – Path of the new image.
  • timeout – Request timeout (default: 20 seconds)
set_chat_title(chat_id: Union[str, int], title: str, timeout: int = 20)[source]

Set the title of a channel/group.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • title – New chat title.
  • timeout – Request timeout (default: 20 seconds)
unban_chat_member(chat_id: Union[str, int], user_id: int, timeout: int = 20)[source]

Lift the ban from a chat member.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • user_id – Unique user ID.
  • timeout – Request timeout (default: 20 seconds)
unpin_chat_message(chat_id: Union[str, int], timeout: int = 20)[source]

Unpin the message of a chat.

Parameters:
  • chat_id

    Chat ID. Can be either a numerical ID or a unique identifier in the format @channelname. In order to get your own Telegram chat_id open a conversation with @IDBot and type /start followed by /getid. Similar procedures also exist to get a group or channel chat_id - just Google for “Telegram get channel/group chat_id”.

  • timeout – Request timeout (default: 20 seconds)