Telegram Download Chat

telegram-download-chat

SCOPE: This skill drives the telegram-download-chat CLI to download, convert, filter, and export Telegram chats on the user's behalf. It ONLY invokes the CLI and reports the resulting output paths. It does NOT modify project source code, and does NOT use the GUI, MCP server, or web interface.

Steps

Step 0 — Verify the CLI is available

Run which telegram-download-chat. If found, use that command directly. If not found, try python -m telegram_download_chat --version. If neither works, the tool is not installed — tell the user so and proactively offer to install it, using the methods documented in the project README.md ("Installation" section):

• pip install telegram-download-chat (recommended persistent install)
• uvx telegram-download-chat <args> (run without installing)
• uv tool install telegram-download-chat (persistent install via uv)
• pip install -e ".[dev,gui]" from a checkout of this repo (development)

Do not install anything without the user's confirmation.

Step 1 — Verify credentials

Confirm api_id and api_hash are present without exposing their values. --show-config prints the full config file contents, including the api_hash secret, so prefer a redacted presence check that prints no values:

• Find the config path (default OS location, or the -c/--config value), then run a quiet check that requires a numeric api_id (it is cast with int() before connecting) and a real api_hash (exactly 32 hex chars from my.telegram.org). The api_hash check anchors on exactly 32 hex chars with balanced quoting (both ", both ', or none) so it rejects empty (""/''), null/~, the shipped YOUR_API_HASH placeholder, and short/garbage values like api_hash: a — all of which would fail the real auth check later. E.g. grep -qE '^\s*api_id:\s*("[0-9]+"|'"'"'[0-9]+'"'"'|[0-9]+)\s*$' <config> && grep -qiE '^\s*api_hash:\s*("[0-9a-f]{32}"|'"'"'[0-9a-f]{32}'"'"'|[0-9a-f]{32})\s*$' <config> && ! grep -qE 'YOUR_API_(ID|HASH)' <config> && echo present. A bare key-presence check is not enough — a fresh config has both keys but with placeholder/empty values, and the next connection will fail.
• If you do run --show-config (e.g. just to learn the path), do NOT echo, repeat, or paste the api_hash value back into your response.

These come from https://my.telegram.org — NEVER invent them. If missing, tell the user to add them to the config file (its location is shown by --show-config).

Logging in is its own command: telegram-download-chat login (code from Telegram) or telegram-download-chat login --qr (scan a QR code from an app that is already logged in). Run it as a foreground ! <cmd> in a real, attachable terminal so the user can type the code, the phone or a 2FA password — never in the background.

A download with no saved session offers the same login only when it runs in a real terminal; with no terminal it never prompts, it logs No Telegram session. Run telegram-download-chat login … and exits 1. So a backgrounded or piped run fails fast with a message instead of hanging on a prompt nobody can answer. Only --show-config and --help run fully offline; convert mode (.json input) also opens a Telegram connection (it requires api_id/api_hash and a saved session, though it never offers to log in), so treat convert as needing credentials and an existing session.

Step 2 — Detect the mode from the target

The positional CHAT argument selects the mode (see cli/__init__.py):

• ends with .json → convert an existing export to TXT/HTML/PDF. The CLI still opens a Telegram connection for convert (it needs api_id/api_hash and a saved session), so it is not offline — only --show-config/--help run with no connection. Convert never offers to log in: with no session it fails with the login instruction.
• starts with folder: (e.g. folder:Work) → download every chat in that Telegram folder (live).
• username (@name or name), phone number, numeric id, or channel id (-100…) → live download of that chat.
• comma-separated list of any of the above → processed one by one.
• absent, or gui → GUI mode. Out of scope for this skill; mention only and do not launch it.

Step 3 — Build the command from intent

Map the user's request to flags (full reference below). Common building blocks: -o/--output, -l/--limit, date range (--max-date/--from, --min-date/--until, --last-days), --user, --keywords, --subchat, --split, --media, --comments, --stt, --html, --pdf. Add --results-json whenever you need to parse the outcome programmatically.

Step 4 — Run it

• --show-config and --help: run in the foreground normally (no connection).
• Convert mode (.json input) and short capped downloads (e.g. small -l): run in the foreground normally only when credentials and a saved session already exist — both still open a Telegram connection.
• With no saved session: run telegram-download-chat login (or login --qr) as a foreground ! <cmd> in a real, attachable terminal first, so the user can type the phone, the code and an optional 2FA password. A live download started in such a terminal offers the same login itself; anywhere else it exits 1 with the instruction rather than hanging. Never background a run that may need to log in.
• Large/long-running downloads where a saved session already exists (no login prompt possible): run as a foreground ! <cmd> to watch progress, or in the background. Confirm scope first (see Constraints).

Step 5 — Report results

Prefer --results-json: it prints {"results": [ ... ]}, where each entry has chat_id, chat_title, chat_type, messages (count), from/to, result_json, result_txt, matched keywords, and — when produced — result_topics, result_attachments, result_html, result_pdf (each a path, or a list of paths when --split is used). Parse it and report the concrete output paths to the user. Output is organized per-chat under the downloads dir: <chat_name>/messages.json, messages.txt, optionally messages.html/messages.pdf, and attachments/.

CLI reference

Source of truth: src/telegram_download_chat/cli/arguments.py. Run telegram-download-chat --help to confirm the live flag set.

Positional argument

• CHAT (optional) — the target. Accepts:
  • username (@name or name), phone number, numeric id, or channel id (-100…) → live download;
  • a path ending in .json → convert an existing export (still opens a Telegram connection — needs credentials, see Step 1/2);
  • folder:Name (e.g. folder:Work) → every chat in that Telegram folder;
  • a comma-separated list of any of the above → processed one by one (the list is split on , and trimmed).
  • omitted → GUI mode (out of scope for this skill).

Output

• -o, --output — output file path (default: <chat_name>.json).
• --split {month,year,topics} — split output by month, by year, or by forum topic (one <chat>/<topic_slug>/ subdirectory per topic). Note: topics only works on a live download of a forum/supergroup; on a .json convert it silently falls back to year-bucketing.
• --overwrite — replace existing output files instead of resuming.
• --results-json — print a results summary as JSON to stdout (preferred machine-readable output).

Limits & range

• -l, --limit — maximum number of messages to download (default: 0 = no limit).
• --since-id — start downloading after the specified message ID.
• --max-date, --from — only messages on or before this date (YYYY-MM-DD). Also the base date for --last-days.
• --min-date, --until — only messages on or after this date (YYYY-MM-DD).
• --last-days — number of days back from --max-date (or today) to download.

Filtering

• --user — sender identifier (12345 or user12345). Caveat: it only actually filters when converting a Telegram Desktop archive export (a JSON dict containing about/chats). For a normal message-list JSON it does NOT filter — it only tags the output filename (..._user_<id>.txt). Live downloads ignore it entirely. To restrict a normal export to one sender, filter the JSON yourself.
• --keywords — comma-separated keywords to search in messages.
• --subchat — filter to a subchat/reply thread by message id or URL. Works on JSON→TXT conversion, and on live downloads when combined with -o/--output (without -o, an existing .json input is required).
• --subchat-name — name for the subchat directory (default: subchat_<subchat_id>).

Sort

• --sort {asc,desc} — sort messages by date (default: asc).

Media

• --media — download all media attachments (images, videos, audio, documents, etc.).
• --no-fast-download — disable parallel multi-connection media downloads (use single-stream Telethon downloader).
• --media-placeholders — insert media type indicators (e.g. [photo], [file=name.pdf]) in TXT output.

Comments (channels only)

• --comments — download post comments from the channel's linked discussion group (a no-op on other entities and on channels without comments). Comments are merged into the same messages.json/.txt/.html and nested under their post.
• --comments-limit — max comments fetched per post (requires --comments; omit for unlimited).
• --comments-min-reactions — drop comments whose total reaction count is below N (requires --comments; 0 = keep all). Applied after --comments-limit, so the limit caps how many are fetched and this trims the low-reaction ones.

Enrichment

• --reactions — append each message's reactions as an inline suffix (e.g. [👍5 ❤️2]) in the TXT output.
• --stt — transcribe voice messages and round video notes via Telegram's speech-to-text. Requires a Telegram Premium account; without one the pass is skipped with a warning and makes no API calls. Transcripts appear as a transcript field in JSON, a [stt] … line in TXT, and an italic block in HTML/PDF. Results are cached locally (keyed by the audio's document id), so a re-download — or the same audio in another chat — is never transcribed twice.

Export

• --html — export chat as a Telegram-style HTML file.
• --html-media-links — show clickable file path captions under each media element in HTML export.
• --pdf — export chat as a PDF document.

Config & debug

• -c, --config — path to config file (default: OS-specific location).
• --show-config — show the current configuration file location and contents, then exit.
• --debug — enable debug logging.
• --preset — name of a preset from config to use.
• --proxy-url — proxy URL for the Telegram connection (e.g. socks5://host:1080, http://host:8080).

Info

• -v, --version — print version and exit.
• -h, --help — show help and exit.

Scenarios

Each scenario lists a runnable command and the situation it fits. Replace @chat / paths with the user's actual target.

• Basic download — "download this chat": telegram-download-chat @chat
• Limited count + custom output — "grab the last 100 messages into report.json": telegram-download-chat @chat -l 100 -o report.json
• Date range — "messages between two dates": telegram-download-chat @chat --min-date 2025-01-01 --max-date 2025-03-31
• Recent window — "the last week of messages": telegram-download-chat @chat --last-days 7
• Split by month + media — "download everything, split per month, with attachments": telegram-download-chat @chat --split month --media
• Keyword search + machine-readable result — "find messages mentioning 'invoice' and give me the paths": telegram-download-chat @chat --keywords invoice,payment --results-json
• JSON → TXT conversion with sort — "convert this export, newest first": telegram-download-chat ./chat/messages.json --sort desc (Adding --user user12345 only filters a Telegram Desktop archive export; for a normal message-list JSON it just tags the filename — see the --user caveat above.)
• Subchat extraction from JSON — "pull the reply thread under this message out of the export": telegram-download-chat ./chat/messages.json --subchat https://t.me/c/123456/789 --subchat-name design-thread
• Folder download — "download every chat in my Work folder": telegram-download-chat folder:Work
• HTML / PDF export — "export this chat as a readable HTML page and a PDF": telegram-download-chat @chat --html --pdf
• Channel with comments — "export this channel including the discussion comments, but only the ones people reacted to": telegram-download-chat @channel --comments --comments-min-reactions 3 --html
• Voice transcription — "download this chat and transcribe the voice messages": telegram-download-chat @chat --stt --media --html
• Proxy + preset — "use my socks proxy and the 'archive' preset": telegram-download-chat @chat --proxy-url socks5://127.0.0.1:1080 --preset archive

Constraints — when to stop and ask

• Confirm before large/long downloads. If the user gives no -l/--limit and no date range on a live chat, the download is unbounded. Confirm scope (or suggest a --last-days / -l cap) before starting.
• Never invent api_id / api_hash. They come only from https://my.telegram.org. If --show-config shows them missing, ask the user to add them — do not guess.
• Logging in needs a real terminal. login / login --qr ask for the phone, the code and an optional 2FA password, and a live download offers the same when it runs in a terminal. Run those as a foreground ! <cmd>; never assume a login can run unattended. Exit codes are reliable from both telegram-download-chat and python -m telegram_download_chat, so a failure is detectable without scraping the log.
• Respect a user-set --proxy-url / proxy config. Don't strip or override the proxy the user configured.
• Don't modify project source code. This skill only invokes the CLI and reports output paths. For GUI / MCP / web usage, defer — they are out of scope here.