chat.telegram
Platypush documentation
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:
Open a Telegram conversation with the @BotFather.
Send
/start
followed by/newbot
. Choose a display name and a username for your bot.Copy the provided API token in the configuration of this plugin.
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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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
orpath
.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)