diff --git a/source/_integrations/telegram_bot.markdown b/source/_integrations/telegram_bot.markdown index 4ff41d66179d..e8a0af2ade2b 100644 --- a/source/_integrations/telegram_bot.markdown +++ b/source/_integrations/telegram_bot.markdown @@ -18,7 +18,7 @@ ha_platforms: --- Use Telegram on your mobile or desktop device to send and receive messages or commands to/from your Home Assistant. -This integration creates notification actions to send, edit or receive messages from a [Telegram Bot account](https://core.telegram.org/bots). +This integration creates notification actions to send, edit, receive messages or download attachments from a [Telegram Bot account](https://core.telegram.org/bots). ## Introduction - Telegram bot platforms @@ -530,6 +530,36 @@ Sets the bot's reaction for a given message. | `reaction` | no | Emoji to react to the message with. | | `is_big` | yes | Whether to use a large variant of the reaction animation. | +### Action `telegram_bot.download_file` + +Download a file previously sent to the bot and save it to a local path on the Home Assistant host. + +| Data attribute | Optional | Description | +| ---------------- | -------- | ----------- | +| `config_entry_id`| yes | The config entry representing the Telegram bot to get the file. Required if you have multiple Telegram bots. | +| `file_id` | no | ID of the file to get. This is provided in `telegram_attachment` event data as `file_id`. | +| `directory_path` | yes | Local directory path to save the file to. Defaults to `/config/telegram_bot/`. | +| `file_name` | yes | Name to save the file as. If not provided, the original file name will be used. | + +Example YAML usage: + +```yaml +action: telegram_bot.download_file +data: + config_entry_id: "" + file_id: "ABCD1234Efgh5678Ijkl90mnopQRStuvwx" + directory_path: "/config/telegram_bot/" + file_name: "my_downloaded_file" +``` + +{% note %} + +- For file size limits and download behavior, refer to the python-telegram-bot documentation: [python-telegram-bot - get_file](https://docs.python-telegram-bot.org/en/stable/telegram.bot.html#telegram.Bot.get_file) +- For the moment, bots can download files of up to 20 MB in size. +- Ensure the target `directory_path` is included in `allowlist_external_dirs` if you need to serve or access the file from the frontend. + +{% endnote %} + ## Response schemas for actions {% tip %}