Skip to main content

Download File

Downloads a file from Telegram to your local storage using the file ID. Useful for processing files received from users or retrieving media from messages.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Input​

  • Client Id - (Optional) The unique identifier for the bot client connection obtained from the Connect node. If not provided, you can use Bot Token instead.
  • File Id - The unique identifier for the file to download. This ID is obtained from received messages that contain files (photos, documents, audio, etc.).
  • Save Path - The local path where the downloaded file should be saved. Can be:
    • An absolute file path (e.g., C:\Downloads\file.pdf)
    • Empty string to save to system temp directory with auto-generated name

Options​

  • Bot Token - (Optional) The Telegram bot token credential. This is an alternative to using Client Id - provide either Client Id OR Bot Token.

Output​

  • File Path - The full path where the file was saved. Use this output to process or send the downloaded file.

How It Works​

The Download File node retrieves a file from Telegram's servers and saves it locally. When executed, the node:

  1. Either uses the provided Client Id or creates a temporary connection using Bot Token
  2. Validates the File Id
  3. If Save Path is empty, creates a temporary file in the system temp directory
  4. If Save Path is provided, creates the necessary parent directories
  5. Calls Telegram's API to get file information using the File Id
  6. Downloads the file from Telegram's servers
  7. Saves the file to the specified location
  8. Returns the full path of the downloaded file in the File Path output

Requirements​

  • Either a valid Client Id from a Connect node OR a valid Bot Token credential
  • A valid File Id from a Telegram message
  • Sufficient disk space for the file
  • Write permissions for the save location
  • The file must still be available on Telegram's servers (files may expire after some time)

Error Handling​

The node will return errors in the following cases:

  • Empty or invalid File Id
  • Invalid Client Id or Bot Token
  • File not found (file may have been deleted or expired)
  • Insufficient disk space
  • Permission denied for save path
  • Directory creation failed
  • Network connectivity issues
  • Telegram API errors

Usage Examples​

Download from Received Message:

Receive Message
  → If (message.document exists)
    → Download File (
        File Id: message.document.file_id,
        Save Path: "C:\Downloads\received_file.pdf"
      )
    → Process File

Download to Temp Directory:

Receive Message
  → Download File (
      File Id: message.photo.file_id,
      Save Path: ""  // Auto temp path
    )
  → Process Image (file_path)
  → Delete File (file_path)

Download and Forward:

Receive Message (from user)
  → Download File (File Id: message.document.file_id)
  → Send Document (
      Chat Id: admin_chat,
      Document Path: file_path
    )

Batch Download:

For Each (file in message.files)
  → Download File (
      File Id: file.file_id,
      Save Path: `/downloads/${file.file_name}`
    )

File ID Sources​

File IDs can be obtained from various message properties:

Document:

message.document.file_id

Photo:

// Photos have multiple sizes, get the largest
message.photo.file_id  // Last/largest size

Audio:

message.audio.file_id

Voice:

message.voice.file_id

Video:

message.video.file_id

Video Note:

message.video_note.file_id

Sticker:

message.sticker.file_id

Use Cases​

Document Processing:

Receive Message (with document)
  → Download File
  → Parse PDF/Excel
  → Extract Data
  → Send Message (results)

Image Analysis:

Receive Message (with photo)
  → Download File
  → Run OCR
  → Send Message (extracted text)

File Backup:

Receive Message
  → Download File
  → Upload to Cloud Storage
  → Send Message ("Backed up!")

Media Conversion:

Receive Message (with audio)
  → Download File
  → Convert Format
  → Send Audio (converted file)

Virus Scanning:

Receive Message (with document)
  → Download File
  → Scan for Viruses
  → If (clean)
    → Forward to Admin
  → Else
    → Send Message ("File blocked")

Best Practices​

  • Validate File Ids - Check that file IDs exist before attempting download
  • Use temp directory - For temporary processing, leave Save Path empty
  • Clean up files - Delete downloaded files after processing to save space
  • Check file size - Large files take longer to download
  • Handle errors - Files may be expired or unavailable
  • Create directories - The node creates parent directories automatically
  • Use absolute paths - Always use full paths for Save Path
  • Monitor disk space - Ensure sufficient space before downloading

Save Path Behavior​

Empty Save Path:

Save Path: ""
Result: /tmp/telegram_download_1699876543000

Absolute Path:

Save Path: "C:\Downloads\myfile.pdf"
Result: C:\Downloads\myfile.pdf

With Parent Directories:

Save Path: "/home/user/files/2024/report.pdf"
Result: Creates /home/user/files/2024/ if needed, saves file

Common Patterns​

Download and Process:

Receive Message
  → Extract File Id
  → Download File (to temp)
  → Process File
  → Delete File
  → Send Message ("Processed!")

Download with Original Name:

let fileName = message.document.file_name;
let savePath = `/downloads/${fileName}`;

// Use savePath in Download File node

Conditional Download:

Receive Message
  → If (message.document.file_size < 10000000)  // 10 MB
    → Download File
    → Process
  → Else
    → Send Message ("File too large")

Error Recovery:

Try {
  Download File (to primary location)
}
Catch {
  Download File (to backup location)
}

File Information​

Before downloading, you can check:

File Size:

message.document.file_size  // in bytes

File Name:

message.document.file_name

File Type:

message.document.mime_type

Temporary Files​

Auto-Generated Names:

  • Format: telegram_download_{timestamp}
  • Location: System temp directory
  • Unique per download

Cleanup:

Download File (Save Path: "")
  → Process File (file_path)
  → Delete File (file_path)

Storage Considerations​

Disk Space:

  • Check available space before downloading large files
  • Monitor temp directory usage
  • Implement cleanup routines

File Size Limits:

  • Telegram files can be up to 2 GB (for premium users)
  • Regular users: up to 2 GB for files uploaded via bot
  • Ensure your storage can handle the files

Download Performance​

Speed Factors:

  • File size
  • Network connection
  • Telegram server load
  • Geographic location

Optimization:

  • Download only necessary files
  • Use temp directory for temporary processing
  • Delete files after processing
  • Consider caching frequently accessed files

Troubleshooting​

File Not Found:

  • File may have expired (Telegram keeps files temporarily)
  • File Id may be invalid
  • File may have been deleted

Permission Denied:

  • Check write permissions for save path
  • Ensure directory is accessible
  • Try using temp directory (empty Save Path)

Disk Full:

  • Check available disk space
  • Clean up old files
  • Use a different storage location

Download Timeout:

  • Large files may take time
  • Check network connection
  • Retry the operation

Invalid File Id:

  • Verify the File Id is from a valid message
  • Check that the message type contains a file
  • Ensure the File Id string is complete

File Path Output​

The File Path output contains the absolute path to the downloaded file:

// Example output
file_path = "C:\Users\Bot\AppData\Local\Temp\telegram_download_1699876543000"

Use this output to:

  • Process the file
  • Send it to another chat
  • Upload to cloud storage
  • Analyze the content
  • Pass to other nodes

Tips​

  • File IDs are unique and can only be used once per download operation
  • Downloaded files remain until you delete them - implement cleanup
  • The node creates parent directories automatically if they don't exist
  • Empty Save Path is useful for one-time processing
  • File IDs expire after some time - download files promptly
  • For photos, multiple file IDs exist for different sizes
  • Use the largest photo size for best quality
  • The output File Path is always absolute, even if you provide a relative Save Path
  • Consider implementing rate limiting for bulk downloads
  • Telegram's file storage is temporary - don't rely on it for long-term storage