Telegram Archive¶

Telegram Archive backs up one or more Telegram accounts to a machine you host, in Docker or from the Python package. Telegram Desktop's own export is a file you make by hand: it holds no earlier version of an edited message, no deleted message, and nothing reads it like the app. Telegram Archive runs on a schedule, fetches only what is new, keeps every edit and every deletion, and shows the archive in a viewer that reads like Telegram. Start with Run with Docker, then Using the viewer. Only the backup talks to Telegram; the viewer only reads the archive.

The viewer¶

The viewer looks and works like the Telegram app, with the archive behind it: chats, folders, forum topics, search, shared media and an info panel. What Telegram no longer shows, it keeps and marks: a deleted message stays with its text, an edited message keeps its earlier versions, and What changed lists every deletion, edit and new transcript. Logins, viewer accounts and share links covers who can open which chats, Themes and wallpaper the twelve themes, and Exposing the viewer safely a reverse proxy in front of it.

What it saves¶

• Messages with their formatting, replies, forwards, reactions, pinned messages, polls and service messages.
• Every edit, with the earlier text, and every deletion, kept and marked. See Catching changes to older messages.
• Photos, videos, voice notes, audio, round videos, GIFs, stickers, documents and link previews, each file stored once. Files over 100 MB are skipped by default. See Media downloads.
• Forum topics, Telegram folders, archived chats, avatars and earlier profile photos.
• Several accounts in one archive, transcripts of voice messages, and imports of Telegram Desktop exports. Bot chats are skipped unless you add them.

How it runs¶

flowchart TB
    TG[Telegram]
    subgraph backup [Backup container]
        SCH[Scheduler]
        CL[One client per account]
        LI[Real-time listener]
        MIG[Migrations on start]
    end
    DB[(Database<br/>SQLite by default<br/>PostgreSQL optional)]
    MEDIA[(Media folder)]
    TR[Transcription server, optional]
    subgraph viewer [Viewer container]
        WEB[Web viewer on port 8000<br/>reachable from this machine only]
    end
    BR[Browser]

    TG <--> CL
    SCH --> CL
    LI --> CL
    CL --> DB
    CL --> MEDIA
    MIG --> DB
    backup -.->|audio| TR
    DB --> WEB
    MEDIA --> WEB
    WEB <--> BR

• Two images, drumsergio/telegram-archive for the backup and drumsergio/telegram-archive-viewer, share one version number, run on amd64 and arm64, and run as user id 1000.
• The listener saves new messages, edits and reactions as they happen. A full backup runs when the container starts, then on a cron schedule, once a day by default, to fetch what the listener could not see.
• The archive is SQLite by default, or PostgreSQL. An upgrade is usually a pin change and a restart; Backing up the archive says how to keep a copy.

What it does not do¶

• It does not save secret chats.
• It cannot recover messages deleted before the first backup.
• It never sends or changes anything in your account. Only the separate restore script posts archived messages back to a chat, as you. See Command line and Python API.
• The viewer is in English only and has no offline mode.

Privacy¶

• The archive stays on your own disk. Nothing leaves it unless you turn on one of the three optional features below.
• The logs never contain message text, chat ids, account labels or phone numbers.
• Transcription sends the audio, its file name and its content hash to the server you configure. No message text or chat details go with it.
• The event webhook sends each edit or deletion, message text included, to the URL you configure.
• Web Push with PUSH_NOTIFICATIONS=full sends the chat title, the sender and the first 100 characters of each new message through your browser's push service, encrypted for the browser.

Getting help¶

• Something broken: read Monitoring and troubleshooting, then open an issue with the details it lists.
• A security problem: follow the security policy, never a public issue.
• What changed between releases: the changelog on GitHub. What is planned: the Roadmap.
• Terms these pages use: the Glossary. Scripting against the viewer: the HTTP API. Sending a fix: Development.

License¶

Telegram Archive is released under the GPL-3.0-or-later license. It is built on Telethon.