Configuration Reference¶

Complete reference for all configuration options.

Configuration Methods¶

environment:
  - TDL_API_ID=12345678
  - TDL_DAEMON_ENABLED=true

api_id = 12345678

[daemon]
enabled = true

Environment Variable Format¶

Format: TDL_SECTION_KEY (uppercase, underscore-separated)

Examples: - TDL_API_ID → api_id - TDL_DAEMON_ENABLED → daemon.enabled - TDL_SOURCES_0_URL → sources[0].url

Core Settings¶

Telegram API Credentials¶

Required for all operations.

- TDL_API_ID=12345678
- TDL_API_HASH=abcdef1234567890abcdef1234567890
- TDL_PHONE_NUMBER=+1234567890

api_id = 12345678
api_hash = "abcdef1234567890abcdef1234567890"
phone_number = "+1234567890"

Paths and Storage¶

When TDL_FLAT_STRUCTURE is false (default), files are organized as {download_dir}/{channel_name}/{filename}. When true, all files go directly into {download_dir}/{filename}.

When TDL_TRACK_DOWNLOADS is true (default), a persistent history of downloaded files is kept in the state database. This prevents re-downloading files that have been moved, renamed, or processed by external tools (e.g., media servers, Paperless-ngx, mergerfs). The tracking uses Telegram's file_unique_id, which is stable and unique per file content regardless of source. Set to false to disable and rely only on file-exists checks.

Docker Environment¶

These are standard Docker environment variables, not prefixed with TDL_.

- PUID=1000
- PGID=1000
- TZ=Europe/Lisbon
- TDL_FLAT_STRUCTURE=true
- TDL_TRACK_DOWNLOADS=true

flat_structure = true
track_downloads = true
# PUID, PGID, and TZ are Docker-only (not in config.toml)

Daemon Configuration¶

Controls continuous background operation.

- TDL_DAEMON_ENABLED=true
- TDL_DAEMON_CHECK_INTERVAL=300  # Check every 5 minutes
- TDL_DAEMON_LOG_LEVEL=INFO

[daemon]
enabled = true
check_interval = 300  # Check every 5 minutes
log_level = "INFO"

Notification Configuration¶

Discord webhooks and generic HTTP POST notifications.

- TDL_NOTIFICATIONS_ENABLED=true
- TDL_NOTIFICATIONS_DETAIL_LEVEL=summary
- TDL_NOTIFICATIONS_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123/abc

[notifications]
enabled = true
detail_level = "summary"
discord_webhook_url = "https://discord.com/api/webhooks/123/abc"

Detail levels: - minimal: Status only (success/failure) - summary: Status + file counts + error types (default) - detailed: Includes file names, timestamps, stack traces

Source Configuration¶

Configure download sources (channels, groups, forum topics, private chats).

Source URL Format¶

Source Settings¶

Format: TDL_SOURCES_N_KEY where N is the source index (0, 1, 2, ...)

- TDL_SOURCES_0_URL=https://t.me/channel1
- TDL_SOURCES_0_NAME=Channel One
- TDL_SOURCES_1_URL=https://t.me/c/1234567890/123
- TDL_SOURCES_1_NAME=Forum Topic

[[sources]]
url = "https://t.me/channel1"
name = "Channel One"

[[sources]]
url = "https://t.me/c/1234567890/123"
name = "Forum Topic"

Filter Configuration¶

Per-source filters override global defaults.

- TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi
- TDL_SOURCES_0_FILTERS_MIN_SIZE=100KB
- TDL_SOURCES_0_FILTERS_MAX_SIZE=500MB
- TDL_SOURCES_0_FILTERS_MIN_DATE=2026-01-01
- TDL_SOURCES_0_FILTERS_PATTERNS=*ebook*,*book*

[[sources]]
url = "https://t.me/channel1"

[sources.filters]
extensions = [".pdf", ".epub", ".mobi"]
min_size = "100KB"
max_size = "500MB"
min_date = "2026-01-01"
patterns = ["*ebook*", "*book*"]

Size format: Number + unit (KB, MB, GB) or raw bytes Pattern format: Wildcards (* = any characters, ? = single character) or regex (auto-detected)

Global Filter Defaults¶

Applied to all sources unless overridden.

Retry Configuration¶

Error handling and retry behavior.

Example:

- TDL_RETRY_MAX_RETRIES=3
- TDL_RETRY_BASE_DELAY=2
- TDL_RETRY_MAX_DELAY=120

config.toml Example¶

Alternative to environment variables:

api_id = 12345678
api_hash = "abcdef1234567890abcdef1234567890"
phone_number = "+1234567890"
download_dir = "/downloads"
flat_structure = true
track_downloads = true

[daemon]
enabled = true
check_interval = 300
health_file = "/app/health_status.txt"

[notifications]
enabled = true
detail_level = "summary"
discord_webhook_url = "https://discord.com/api/webhooks/123/abc"

[[sources]]
url = "https://t.me/channel1"
name = "Channel One"

[sources.filters]
extensions = [".pdf", ".epub", ".mobi"]
min_size = "100KB"
max_size = "500MB"

[[sources]]
url = "https://t.me/c/1234567890/123"
name = "Forum Topic"

Note: Environment variables override config.toml values.