Skip to main content

Send Document

Sends a document (file) to a Telegram chat. Supports various file types including PDF, DOCX, XLSX, ZIP, and more, with options for captions and custom filenames.

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.
  • Chat Id - The target chat identifier where the document will be sent. Can be:
    • A user's Telegram ID (e.g., 123456789)
    • A group chat ID (e.g., -987654321)
    • A channel ID (e.g., -1001234567890)
  • Document Path - The local file path of the document to be sent (e.g., C:\Reports\report.pdf). Note: This node only supports local files, not URLs.

Options​

  • Bot Token - (Optional) The Telegram bot token credential. This is an alternative to using Client Id - provide either Client Id OR Bot Token.
  • Reply Id - (Optional) The message ID to reply to. If specified, the document will be sent as a reply. Default: 0 (no reply).
  • Caption - (Optional) Text caption for the document. Supports up to 1024 characters.
  • File Name - (Optional) Override the filename that appears in Telegram. If not specified, uses the original filename from the path.
  • MIME Type - (Optional) Specify the MIME type of the document (e.g., application/pdf, application/zip). Leave empty to let Telegram detect automatically.

Output​

  • n/a - No output

How It Works​

The Send Document node uploads and sends a file to a specified Telegram chat. When executed, the node:

  1. Either uses the provided Client Id or creates a temporary connection using Bot Token
  2. Validates the Chat Id and Document Path
  3. Checks that the file exists and is readable
  4. Extracts the filename from the path (or uses the custom File Name if provided)
  5. Applies optional caption and MIME type if provided
  6. Uploads the file to Telegram
  7. If Reply Id is provided, sends the document as a reply to that message
  8. Returns success or error based on the API response

Requirements​

  • Either a valid Client Id from a Connect node OR a valid Bot Token credential
  • A valid Chat Id where the bot has permission to send files
  • For document files:
    • The file must exist on the local filesystem
    • The file must be readable
    • Maximum file size: 50 MB
    • All file types are supported

Error Handling​

The node will return errors in the following cases:

  • Empty or invalid Chat Id
  • Empty or invalid Document Path
  • File not found at the specified path
  • File too large (over 50 MB)
  • File not readable (permission issues)
  • Bot doesn't have permission to send files to the chat
  • Network connectivity issues
  • Telegram API errors

Usage Examples​

Send PDF Report:

Connect
  → Send Document (
      Chat Id: 123456789,
      Document Path: "C:\Reports\monthly_report.pdf"
    )
  → Disconnect

Send Excel with Caption:

Send Document:
  Chat Id: 123456789
  Document Path: "/tmp/sales_data.xlsx"
  Caption: "Q4 2024 Sales Data"

Send with Custom Filename:

Send Document:
  Chat Id: 123456789
  Document Path: "/var/reports/output.csv"
  File Name: "Customer_Report_2024.csv"
  Caption: "Latest customer export"

Reply with Document:

Receive Message
  → Generate Report
  → Send Document (
      Chat Id: message.chat.id,
      Reply Id: message.message_id,
      Document Path: reportPath
    )

Supported Document Types​

The Send Document node supports virtually any file type:

Office Documents:

  • PDF (.pdf)
  • Microsoft Word (.doc, .docx)
  • Microsoft Excel (.xls, .xlsx)
  • Microsoft PowerPoint (.ppt, .pptx)
  • LibreOffice (.odt, .ods, .odp)

Archives:

  • ZIP (.zip)
  • RAR (.rar)
  • 7-Zip (.7z)
  • TAR (.tar, .tar.gz)

Data Files:

  • CSV (.csv)
  • JSON (.json)
  • XML (.xml)
  • TXT (.txt)

Code Files:

  • Source code (.py, .js, .java, .go, etc.)
  • Configuration files (.yaml, .conf, .ini)

Media Files:

  • Any file can be sent as a document (even images, video, audio)

Use Cases​

Automated Reports:

Generate Report
  → Save as PDF
  → Send Document (to stakeholders)

Backup System:

Create Backup
  → Compress to ZIP
  → Send Document (to backup channel)

Document Distribution:

Receive Message (request)
  → Retrieve Document from Database
  → Send Document (to requester)

Invoice Delivery:

Generate Invoice
  → Save as PDF
  → Send Document (to customer with details)

Data Export:

Export Database
  → Save as CSV
  → Send Document (to analyst channel)

Best Practices​

  • Use absolute paths - Always provide full file paths, not relative ones
  • Validate file existence - Check that files exist before sending
  • Add descriptive captions - Help users understand what the document contains
  • Use custom filenames - Make filenames user-friendly and descriptive
  • Compress large files - ZIP files before sending to reduce size
  • Check file size - Ensure files are under 50 MB
  • Set appropriate MIME types - For better client compatibility
  • Clean up files - Delete temporary files after sending

File Path Examples​

Windows:

C:\Users\John\Documents\report.pdf
D:\Exports\data_2024.xlsx
C:\Temp\backup.zip
\\NetworkShare\Files\document.docx

Linux/Mac:

/home/user/documents/report.pdf
/tmp/export.csv
~/Downloads/file.zip
/var/reports/output.json

MIME Type Examples​

Common MIME types for documents:

application/pdf                    - PDF files
application/vnd.ms-excel           - Excel XLS files
application/vnd.openxmlformats-... - Excel XLSX files
application/msword                 - Word DOC files
application/vnd.openxmlformats-... - Word DOCX files
application/zip                    - ZIP archives
application/json                   - JSON files
text/csv                          - CSV files
text/plain                        - Text files
application/xml                   - XML files

Common Patterns​

Batch Document Sending:

For Each (document in documentList)
  → Send Document (
      Chat Id: chatId,
      Document Path: document.path,
      Caption: document.description
    )
  → Delay (2 seconds)  // Avoid rate limits

Dynamic Filename Generation:

let timestamp = new Date().toISOString().slice(0,10);
let fileName = `Report_${timestamp}.pdf`;

// Use in File Name field

Multi-File Report:

Generate PDF Report → tempPath1
Generate Excel Data → tempPath2

Send Document (PDF)
Send Document (Excel)
Send Message ("Reports sent")

Delete File (tempPath1)
Delete File (tempPath2)

Error Handling:

Try {
  Send Document (primary path)
}
Catch {
  Send Document (backup path)
  Send Message ("Sent backup version")
}

File Size Management​

For Large Files (over 50 MB):

  • Compress the file first
  • Split into multiple parts
  • Use a file hosting service and send the link instead

Compression Example:

Create ZIP Archive (source files)
  → Send Document (compressed file)

Telegram Document Display​

  • Documents show with a file icon and name
  • Displays file size
  • Shows preview for supported formats (PDF, images)
  • Download button for users
  • Captions appear below the document
  • Automatic thumbnail generation for some formats

Caption Formatting​

Captions support formatting like Send Message (requires Parse Mode configuration):

Simple Caption:

"Q4 2024 Financial Report"

Detailed Caption:

Document: Annual Report
Year: 2024
Pages: 45
Author: Finance Team

Troubleshooting​

File Not Found:

  • Verify the file path is correct and absolute
  • Check the file exists at that location
  • Ensure correct path separators (\ for Windows, / for Linux/Mac)

Permission Denied:

  • Check file permissions
  • Ensure the bot process can read the file
  • Try copying the file to a location with read access

File Too Large:

  • Check file size (max 50 MB)
  • Compress the file
  • Split into multiple smaller files
  • Use a file hosting service instead

Upload Fails:

  • Check network connectivity
  • Verify bot has send permissions in the chat
  • Try with a smaller test file
  • Check Telegram API status

Wrong File Type:

  • Any file type is supported as a document
  • If you want special handling, use Send Photo, Send Audio, etc.
  • MIME type detection is automatic but can be overridden

Document vs. Other Send Nodes​

Use Send Document for:

  • PDF, Office files, archives
  • Files that should be downloadable
  • Files you want to preserve in original format
  • Any file type not covered by other nodes

Use Send Photo for:

  • Images you want to display inline
  • Photos with thumbnail previews

Use Send Audio for:

  • Audio files with player integration
  • Music with metadata display

Tips​

  • Documents preserve the original file perfectly - no compression or conversion
  • Users can download documents directly to their device
  • Telegram creates thumbnails for PDFs and some image formats
  • The File Name parameter affects only the display name, not the actual file
  • Documents can be forwarded by users (unless using Protect Content)
  • Consider adding version numbers or dates to filenames
  • For sensitive documents, use private chats instead of groups
  • Telegram scans files for malware automatically
  • You can send the same file to multiple chats without re-uploading (using file_id from first send)
  • Documents sent as replies create a clear reference to the original request