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.