Platypush documentation

chat.telegram

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: 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) → 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) → 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) → 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: Union[str, int], user_id: int, until_date: Optional[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) → 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) → 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) → 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) → 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) → 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) → 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) → 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) → 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) → 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) → 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) → 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)

previous

chat.irc

next

clipboard