Telegram Chat Downloader
A powerful command-line, GUI and web interface utility to download and analyze Telegram chat history in multiple formats.
Features
- Download complete chat history from any Telegram chat, group, supergroup, channel or Telegram export archive
- Download chats folder
- Extract sub-conversations from message threads
- Save messages in JSON format with full message metadata
- Generate human and LLM readable TXT exports with user-friendly display names
- Download media attachments (photos, videos, documents, audio, etc.)
- Use presets for common option sets via
--preset
- Cross-platform support (Windows, macOS, Linux)
- CLI-first, optional graphical user interface and web interface
Filtering
- Filter messages by date range
- Filter messages by specific users
- Filter saved messages by keywords
- Filter messages by sub-conversations from message threads
Usage
For the first run, you will need to log in to your Telegram account. A browser window will open for authentication.
Basic Commands
# Download chat by username
telegram-download-chat username
# Download chat by numeric ID (negative for groups/channels)
telegram-download-chat -123456789
# Download chat by invite link
telegram-download-chat https://t.me/+invite_code
# Download chat by phone number (must be in your contacts)
telegram-download-chat +1234567890
# Download multiple chats at once
telegram-download-chat chat1,chat2,chat3
Advanced Usage
# Download with a limit on number of messages
telegram-download-chat username --limit 1000
# Download all chats from folder
telegram-download-chat folder:folder_name
# Download messages on or after a specific date (YYYY-MM-DD)
telegram-download-chat username --min-date 2025-05-01
# Download last N days of messages from a specific date
telegram-download-chat username --max-date 2025-06-05 --last-days 1
# Filter messages by specific user
telegram-download-chat group_username --user 123456
# Filter messages containing given keywords (comma-separated, case-insensitive)
telegram-download-chat username --keywords "hello,bye"
# Download messages from a specific thread/reply chain
telegram-download-chat group_username --subchat 12345
# Specify custom output file
telegram-download-chat username -o custom_output.json
# Enable debug logging
telegram-download-chat username --debug
# Download messages with media attachments (photos, videos, documents, etc.)
telegram-download-chat username --media
# Include media type indicators in TXT output (e.g. [photo], [file=report.pdf])
telegram-download-chat username --media-placeholders
# Download a channel together with the comments under each post
telegram-download-chat channel_username --comments
# Cap comments fetched per post (here: 50 per post)
telegram-download-chat channel_username --comments --comments-limit 50
# Keep only comments with at least 2 total reactions
telegram-download-chat channel_username --comments --comments-min-reactions 2
# Include each message's reactions inline in the TXT output
telegram-download-chat username --reactions
# Split output into separate files by month or year
telegram-download-chat username --split month
# Split a forum into one subdirectory per topic
telegram-download-chat group_username --split topics
# Export a Telegram-style HTML page (alongside JSON/TXT)
telegram-download-chat username --html
# Export HTML with clickable media file-path captions
telegram-download-chat username --media --html --html-media-links
# Export a PDF document (alongside JSON/TXT)
telegram-download-chat username --pdf
# Disable parallel multi-connection media downloads (use single-stream)
telegram-download-chat username --media --no-fast-download
# Show current configuration
telegram-download-chat --show-config
# Output results summary as JSON to stdout
telegram-download-chat username --results-json
# Use predefined preset
telegram-download-chat username --preset short
# Resume download starting after a specific message ID
telegram-download-chat username --since-id 5000
Command Line Options
usage: telegram-download-chat [-h] [-o OUTPUT] [--limit LIMIT] [--max-date DATE] [--last-days DAYS]
[--min-date DATE] [--subchat SUBCHAT]
[--subchat-name NAME] [--user USER] [--config CONFIG] [--debug]
[--sort {asc,desc}] [--show-config] [-v]
[chat]
Download Telegram chat history to JSON and TXT formats.
positional arguments:
chat Chat identifier (username, phone number, chat ID, or URL)
