chat.telegram#

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

Bases: ChatPlugin

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: 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: int | str, timeout: int = 20) → 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: int | str, timeout: int = 20) → 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: 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: int | str, user_id: int, timeout: int = 20) → 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) → 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: str | int, user_id: int, until_date: datetime | None = 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: 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: str | int, message_id: int, disable_notification: bool | None = 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: str | int, user_id: int, can_change_info: bool | None = None, can_post_messages: bool | None = None, can_edit_messages: bool | None = None, can_delete_messages: bool | None = None, can_invite_users: bool | None = None, can_restrict_members: bool | None = None, can_promote_members: bool | None = None, can_pin_messages: bool | None = 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, duration: int | None = None, caption: str | None = None, width: int | None = None, height: int | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, caption: str | None = None, performer: str | None = None, title: str | None = None, duration: float | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, phone_number: str, first_name: str, last_name: str | None = None, vcard: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, filename: str | None = None, caption: str | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, latitude: float, longitude: float, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, text: str, parse_mode: str | None = None, disable_web_page_preview: bool = False, disable_notification: bool = False, reply_to_message_id: int | None = None) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, caption: str | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, latitude: float, longitude: float, title: str, address: str, foursquare_id: str | None = None, foursquare_type: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, duration: int | None = None, caption: str | None = None, width: int | None = None, height: int | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, duration: int | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: str | int, file_id: int | None = None, url: str | None = None, path: str | None = None, caption: str | None = None, duration: float | None = None, parse_mode: str | None = None, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: int = 20) → 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: 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: 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: 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: 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: 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)