telegram

telegram#

Description#

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.

Configuration#

telegram:
  # [Required]
  # API token as returned by the `@BotFather
  # <https://telegram.me/BotFather>`_
  api_token:   # type=str

  # [Optional]
  # Optional list of chat_id/user_id which are
  # authorized to send messages to the bot. If nothing is specified
  # then no restrictions are applied.
  # authorized_chat_ids:   # type=Optional[List[Union[str, int]]]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install python-telegram-bot

Triggered events#

Actions#

Module reference#

class platypush.plugins.telegram.TelegramPlugin(api_token: str, authorized_chat_ids: List[str | int] | None = None, **kwargs)[source]#

Bases: ChatPlugin, RunnablePlugin

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.

__init__(api_token: str, authorized_chat_ids: List[str | int] | None = None, **kwargs)[source]#
Parameters:

  • api_token –

    API token as returned by the @BotFather

  • authorized_chat_ids – Optional list of chat_id/user_id which are authorized to send messages to the bot. If nothing is specified then no restrictions are applied.

delete_chat_photo(chat_id: str | int, timeout: float | None = 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: float | None = 20) → dict[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: float | None = 20) → List[dict][source]#

Get the list of the administrators of a chat.

Parameters:

  • chat_id – Chat ID.

  • timeout – Upload timeout (default: 20 seconds).

Returns:

[
  {
    "first_name": "string",
    "is_bot": false,
    "language_code": "string",
    "last_name": "string",
    "link": "string",
    "user_id": 93,
    "username": "string"
  }
]

get_chat_members_count(chat_id: int | str, timeout: float | None = 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: float | None = 20) → dict[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: float | None = None) → dict[source]#

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

Parameters:

  • file_id – File ID.

  • timeout – Upload timeout (default: 20 seconds).

Returns:

{
  "file_id": "string",
  "file_path": "string",
  "file_size": 61
}

kick_chat_member(chat_id: str | int, user_id: int, until_date: datetime | None = None, timeout: float | None = 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: float | None = 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: float | None = 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: float | None = 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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 30,
  "audio_file_id": "string",
  "audio_file_size": 59,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 37,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 33,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 28,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 5,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 27,
  "from_username": "string",
  "link": "string",
  "location_latitude": 14,
  "location_longitude": 33,
  "media_group_id": "string",
  "message_id": 70,
  "photo_file_id": "string",
  "photo_file_size": 35,
  "photo_height": 89,
  "photo_width": 67,
  "text": "string",
  "video_duration": 83,
  "video_file_id": "string",
  "video_file_size": 84,
  "video_height": 73,
  "video_mime_type": "string",
  "video_width": 13
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 62,
  "audio_file_id": "string",
  "audio_file_size": 96,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 93,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 99,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 81,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 39,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 36,
  "from_username": "string",
  "link": "string",
  "location_latitude": 24,
  "location_longitude": 57,
  "media_group_id": "string",
  "message_id": 84,
  "photo_file_id": "string",
  "photo_file_size": 30,
  "photo_height": 98,
  "photo_width": 79,
  "text": "string",
  "video_duration": 95,
  "video_file_id": "string",
  "video_file_size": 13,
  "video_height": 78,
  "video_mime_type": "string",
  "video_width": 53
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 8,
  "audio_file_id": "string",
  "audio_file_size": 47,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 75,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 79,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 78,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 88,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 32,
  "from_username": "string",
  "link": "string",
  "location_latitude": 89,
  "location_longitude": 93,
  "media_group_id": "string",
  "message_id": 79,
  "photo_file_id": "string",
  "photo_file_size": 72,
  "photo_height": 17,
  "photo_width": 55,
  "text": "string",
  "video_duration": 92,
  "video_file_id": "string",
  "video_file_size": 12,
  "video_height": 49,
  "video_mime_type": "string",
  "video_width": 7
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 32,
  "audio_file_id": "string",
  "audio_file_size": 89,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 49,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 26,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 33,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 11,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 73,
  "from_username": "string",
  "link": "string",
  "location_latitude": 4,
  "location_longitude": 50,
  "media_group_id": "string",
  "message_id": 88,
  "photo_file_id": "string",
  "photo_file_size": 12,
  "photo_height": 59,
  "photo_width": 63,
  "text": "string",
  "video_duration": 46,
  "video_file_id": "string",
  "video_file_size": 3,
  "video_height": 95,
  "video_mime_type": "string",
  "video_width": 46
}

send_location(chat_id: str | int, latitude: float, longitude: float, disable_notification: bool = False, reply_to_message_id: int | None = None, timeout: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 34,
  "audio_file_id": "string",
  "audio_file_size": 70,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 17,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 86,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 94,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 17,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 10,
  "from_username": "string",
  "link": "string",
  "location_latitude": 8,
  "location_longitude": 78,
  "media_group_id": "string",
  "message_id": 42,
  "photo_file_id": "string",
  "photo_file_size": 14,
  "photo_height": 18,
  "photo_width": 61,
  "text": "string",
  "video_duration": 59,
  "video_file_id": "string",
  "video_file_size": 48,
  "video_height": 99,
  "video_mime_type": "string",
  "video_width": 66
}

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, timeout: float | None = 20, **__) → dict[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.

  • timeout – Request timeout (default: 20 seconds).

Returns:

{
  "audio_duration": 99,
  "audio_file_id": "string",
  "audio_file_size": 64,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 33,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 86,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 4,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 60,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 38,
  "from_username": "string",
  "link": "string",
  "location_latitude": 24,
  "location_longitude": 6,
  "media_group_id": "string",
  "message_id": 84,
  "photo_file_id": "string",
  "photo_file_size": 23,
  "photo_height": 65,
  "photo_width": 78,
  "text": "string",
  "video_duration": 50,
  "video_file_id": "string",
  "video_file_size": 54,
  "video_height": 25,
  "video_mime_type": "string",
  "video_width": 95
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 13,
  "audio_file_id": "string",
  "audio_file_size": 23,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 1,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 82,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 91,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 59,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 65,
  "from_username": "string",
  "link": "string",
  "location_latitude": 7,
  "location_longitude": 70,
  "media_group_id": "string",
  "message_id": 86,
  "photo_file_id": "string",
  "photo_file_size": 91,
  "photo_height": 74,
  "photo_width": 90,
  "text": "string",
  "video_duration": 13,
  "video_file_id": "string",
  "video_file_size": 92,
  "video_height": 76,
  "video_mime_type": "string",
  "video_width": 8
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 13,
  "audio_file_id": "string",
  "audio_file_size": 63,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 55,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 84,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 30,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 60,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 60,
  "from_username": "string",
  "link": "string",
  "location_latitude": 93,
  "location_longitude": 79,
  "media_group_id": "string",
  "message_id": 42,
  "photo_file_id": "string",
  "photo_file_size": 41,
  "photo_height": 30,
  "photo_width": 9,
  "text": "string",
  "video_duration": 1,
  "video_file_id": "string",
  "video_file_size": 85,
  "video_height": 28,
  "video_mime_type": "string",
  "video_width": 55
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 13,
  "audio_file_id": "string",
  "audio_file_size": 57,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 76,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 56,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 49,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 19,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 9,
  "from_username": "string",
  "link": "string",
  "location_latitude": 3,
  "location_longitude": 23,
  "media_group_id": "string",
  "message_id": 10,
  "photo_file_id": "string",
  "photo_file_size": 76,
  "photo_height": 30,
  "photo_width": 36,
  "text": "string",
  "video_duration": 21,
  "video_file_id": "string",
  "video_file_size": 52,
  "video_height": 50,
  "video_mime_type": "string",
  "video_width": 75
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 92,
  "audio_file_id": "string",
  "audio_file_size": 77,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 36,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 57,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 12,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 24,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 43,
  "from_username": "string",
  "link": "string",
  "location_latitude": 90,
  "location_longitude": 9,
  "media_group_id": "string",
  "message_id": 41,
  "photo_file_id": "string",
  "photo_file_size": 36,
  "photo_height": 11,
  "photo_width": 52,
  "text": "string",
  "video_duration": 62,
  "video_file_id": "string",
  "video_file_size": 64,
  "video_height": 63,
  "video_mime_type": "string",
  "video_width": 10
}

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: float | None = 20) → dict[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)

Returns:

{
  "audio_duration": 97,
  "audio_file_id": "string",
  "audio_file_size": 89,
  "audio_mime_type": "string",
  "audio_performer": "string",
  "audio_title": "string",
  "caption": "string",
  "chat_firstname": "string",
  "chat_id": 1,
  "chat_lastname": "string",
  "chat_username": "string",
  "contact_first_name": "string",
  "contact_last_name": "string",
  "contact_phone_number": "string",
  "contact_user_id": 35,
  "contact_vcard": "string",
  "creation_date": "date",
  "document_file_id": "string",
  "document_file_name": "string",
  "document_file_size": 46,
  "document_mime_type": "string",
  "edit_date": "date",
  "forward_date": "date",
  "forward_from_message_id": 2,
  "from_firstname": "string",
  "from_lastname": "string",
  "from_user_id": 87,
  "from_username": "string",
  "link": "string",
  "location_latitude": 44,
  "location_longitude": 58,
  "media_group_id": "string",
  "message_id": 16,
  "photo_file_id": "string",
  "photo_file_size": 19,
  "photo_height": 31,
  "photo_width": 28,
  "text": "string",
  "video_duration": 72,
  "video_file_id": "string",
  "video_file_size": 85,
  "video_height": 25,
  "video_mime_type": "string",
  "video_width": 22
}

set_chat_description(chat_id: str | int, description: str, timeout: float | None = 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: float | None = 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: float | None = 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: float | None = 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: float | None = 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)

Platypush documentation