dotiphant

Use cases

Back up your Telegram chats locally

Dotiphant copies your Telegram chats into one SQLite file in a private folder on your computer and keeps it up to date, in the background every 15 minutes if you want. It only reads from Telegram, has no cloud, and never deletes a message from the archive when it syncs.

It is an archive to search and read, not a tool that restores messages back into Telegram.

Why keep a local copy

Your chat history lives on Telegram's servers. Messages get deleted or edited, people leave groups, and searching years of history in the app is slow. A local copy gives you the full history of your chats with people and groups in a file you control, with fast full-text search, and readable by your AI assistant if you connect one.

Set it up

  1. Install Dotiphant. The setup opens in your browser and takes about five minutes: create your own free API id at my.telegram.org, scan a QR code with the Telegram app, choose what to archive, and run the first sync.
    curl -fsSL https://dotiphant.com/install.sh | sh
  2. The first sync loads the last 365 days by default. For everything, run a full sync once. Large accounts take a while; you can stop with Ctrl-C, and the next sync continues where it stopped.
    dotiphant sync --all-history
  3. Turn on background refresh, if you did not in the setup. It runs a sync every 15 minutes by default; --every sets another interval in minutes.
    dotiphant schedule installdotiphant schedule install --every 60  # once an hour
  4. Check that it works. dotiphant status shows the login, the archive size, the last sync, whether background refresh is on, and the path of the data folder.
    dotiphant status

Where the archive lives

Everything is in one data folder, created readable only by your user account. The messages are in dotiphant.db, a SQLite file.

SystemData folder
macOS~/Library/Application Support/Dotiphant
Linux~/.local/share/dotiphant
Windows (experimental)%APPDATA%\Dotiphant

Set DOTIPHANT_HOME to use another folder. Your Telegram login session and API id are not in this folder: they are in the system keychain.

What the archive keeps

  • The full history of your chats with people and groups, including forum topics and groups that were upgraded to supergroups.
  • Messages that were deleted in Telegram stay in the archive, because a sync never deletes stored messages. Edits to a chat's recent messages are picked up when the chat gets new messages or is synced on its own, and Dotiphant keeps the earlier text too.
  • Photos, files and voice notes are downloaded on demand, to save space. Use the button in the viewer, or dotiphant media CHAT.
  • Channels are off by default, because they are often large and easy to reread in Telegram. Turn them on with dotiphant setup --reconfigure.
  • Secret chats are not included. They are end-to-end encrypted between two devices and never reach Telegram's servers in readable form.

Protect the archive

Dotiphant does not encrypt the archive beyond what your disk encryption provides. Turn on FileVault (macOS), BitLocker (Windows) or full-disk encryption (Linux). The stored Telegram session gives full access to your account, the same as a logged-in Telegram Desktop, so protect this computer like your phone: a login password, screen lock and disk encryption.

If you copy the data folder to another backup, the same care applies there. It holds other people's messages, not only yours.

Remove a chat

If someone asks you to delete their messages, or you no longer want a chat kept, remove it. This deletes the chat, its messages and its media from the archive and stops syncing it.

dotiphant forget "Chat name"

To keep a chat out of the archive from the start, add its id to excluded_chats in settings.json in the data folder. Messages already archived stay until you run dotiphant forget.

Honest limits

  • It is a read-only archive. Dotiphant cannot restore messages into Telegram, and it never sends, edits or deletes anything there.
  • Your computer has to be on for background refresh to run. Messages deleted before the next sync are not caught.
  • Windows support is experimental.

Once the archive is there, you can search it, export chats as Markdown, or read the full security notes.

Install Dotiphant

Free and open source (MIT). macOS and Linux; Windows experimental. The command installs the latest GitHub release and opens the setup in your browser. It takes about five minutes.

The script is about 150 lines. Read it first, or see other ways to install. The installer verifies the download against the release checksums (SHA256SUMS) before installing. You can check signed build provenance with gh attestation verify; see Verify a download.

curl -fsSL https://dotiphant.com/install.sh | shdotiphant open  # setup opens in your browser

Updated . Something wrong or unclear? Open an issue.