# tg_backup

Incremental media backup for Telegram chats. Downloads photos and documents from a chat, remembers where it stopped, and picks up from there on the next run.

Single Python file, one dependency ([Telethon](https://docs.telethon.dev/)).

## Install

```bash
pip install telethon
cp tg_backup.py ~/bin/ && chmod +x ~/bin/tg_backup.py
```

## Setup

Run it once with no arguments to create the config:

```bash
tg_backup.py
```

It writes `~/.config/telegram_backup/config.json` and exits. Fill in the two values from [my.telegram.org](https://my.telegram.org) (API development tools):

```json
{
    "api_id": 12345,
    "api_hash": "<your 32-character hash>"
}
```

`api_id` is an integer, `api_hash` a 32-character hex string.

Nothing else from that page is needed. FCM credentials and MTProto server addresses are for full client implementations.

The first real run prompts for your phone number and login code. That session is saved and shared by every subsequent run, so you log in once.

## Usage

List your chats to find a target:

```bash
tg_backup.py --list-chats
```

```
             ID  TYPE      USERNAME              NAME
 -1001234567890  group     @examplegroup         Example Group
      123456789  user      @examplecontact       Example Contact
      987654321  user      -                     Contact Without Handle
```

Back one up:

```bash
tg_backup.py --target=@examplegroup --archive-dir ~/backups/examplegroup
tg_backup.py --target=-1001234567890 --archive-dir ~/backups/examplegroup
```

Numeric IDs are more durable than usernames, which their owners can change. Chats showing `-` have no public handle and can only be addressed by ID.

`--target` also accepts `me` (Saved Messages), t.me links, and invite links for groups you have already joined.

Update it later with just the directory:

```bash
tg_backup.py --archive-dir ~/backups/examplegroup
```

The target is recorded in the archive directory on the first run, so repeat runs do not need it. Passing the same `--target` again is fine; the `@` and letter case do not have to match.

Passing a *different* one is refused, because the directory's resume position belongs to the old chat and would skip the new chat's history. Use one directory per chat. If a chat genuinely changed handle or ID, `--force-target` accepts the new target and keeps the resume position. Switching between a chat's `@username` and its numeric ID also trips this, as the two cannot be compared without resolving them first.

### Options

| Option | Default | Meaning |
|---|---|---|
| `--target` | first run only | Chat to back up: `@username`, numeric ID, t.me link, or `me`. Reused from the archive directory afterwards |
| `--archive-dir` | `./tg_archive` | Where media and resume state are written; created if missing |
| `--list-chats` | | Print your dialogs with IDs and usernames, then exit |
| `--force-target` | | Accept a `--target` that differs from the one saved in the archive directory |
| `--self-check` | | Run internal assertions and exit. No network, no login |

Use one archive directory per chat. Prefer absolute paths: the default is relative to the current directory, so running from elsewhere silently starts a second archive.

### Negative IDs need `=`

```bash
tg_backup.py --target=-1001234567890     # correct
tg_backup.py --target -1001234567890     # error: expected one argument
```

Without `=`, argparse reads the leading `-` as the start of another flag.

## How it works

Messages are processed oldest to newest, and the last message ID seen is written to `state.json` in the archive directory after every message, alongside the chat it belongs to. An interrupted run resumes from there instead of rescanning the whole chat.

Media is saved as `{message_id}_{original_name}`. Downloads land in a temporary `.part` file and are renamed only on success, so a killed run never leaves a truncated file that a later run would mistake for a complete one. Files that already exist are skipped, so even a lost `state.json` degrades to a slow rescan rather than re-downloading everything.

Rate limits are handled at two levels: Telegram's requested wait is honoured for both individual downloads and history fetches, and other errors (dropped connections, expired file references) are retried with exponential backoff. A download that fails permanently is skipped rather than stalling the run forever, and its message ID is appended to `failures.json` so the gap is auditable:

```bash
jq -s 'map(.id)' ~/backups/examplegroup/failures.json
```

One JSON object per line, written only after all retries are exhausted. Nothing retries or prunes these; the file is a record, not a queue.

Only media is saved. Message text and captions are not.

## Files

| Path | Contents |
|---|---|
| `~/.config/telegram_backup/config.json` | API credentials |
| `~/.config/telegram_backup/session.session` | Login session, shared across all archive directories |
| `<archive-dir>/state.json` | Resume position and saved target for that chat |
| `<archive-dir>/failures.json` | Message IDs whose media never downloaded |
| `<archive-dir>/*` | Downloaded media |

The session file is account credentials: anyone holding it can read your Telegram. It is created mode `0600` inside a `0700` directory. Keep it out of version control and off shared storage.

## License

Copyright (C) 2026 Danilo M. <danix@danix.xyz>

Released under the GNU General Public License version 2. See [LICENSE](LICENSE) for the full text.

## Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.