stek29/extract_telegram_macos.ipynb

Last active July 10, 2026 06:04

Star (60) You must be signed in to star a gist
Fork (16) You must be signed in to fork a gist

Select an option

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/stek29/8a7ac0e673818917525ec4031d77a713.js"></script>
Save stek29/8a7ac0e673818917525ec4031d77a713 to your computer and use it in GitHub Desktop.

Download ZIP

Extract Telegram messages from db_sqlite PostBox – made for Telegram for macOS, but should work with Telegram for iOS

Raw

extract_telegram_macos.ipynb

Sorry, something went wrong. Reload?

Sorry, we cannot display this file.

Sorry, this file is invalid so it cannot be displayed.

soar commented Dec 2, 2025

It did the job for me to recover some accidentally deleted messages. Thank you!

soakes commented Feb 4, 2026 •

edited

Loading

Hey @stek29,

Thank you for the original research and examples — it saved me a headache today. A family member accidentally removed a chat, but we managed to keep a Mac offline long enough to recover the local cache. Your work made it possible to build a clean, user‑friendly tool that exports Telegram (macOS) chats to HTML, Markdown, or CSV.

I’ve published it here to help others in the same situation:
https://github.com/soakes/telegram-message-exporter

You’re credited in the README. If you see anything worth improving, feel free to open an issue or PR.

Thanks again — this was hugely helpful.

stek29 commented Feb 5, 2026

Author

Hey @soakes, that's amazing, thank you for sharing!

Just in case I'd like to clarify that I absolutely do not mind since this gist didn't state any license.

A minor suggestion is not to call the app "Telegram Desktop" since Telegram Desktop is the name of the cross-platform Qt app (named Telegram Lite in App Store for some reason) to avoid confusion — the native Telegram macOS app is different from Telegram Desktop.

soakes commented Feb 5, 2026 •

edited

Loading

Hey @soakes, that's amazing, thank you for sharing!

Just in case I'd like to clarify that I absolutely do not mind since this gist didn't state any license.

A minor suggestion is not to call the app "Telegram Desktop" since Telegram Desktop is the name of the cross-platform Qt app (named Telegram Lite in App Store for some reason) to avoid confusion — the native Telegram macOS app is different from Telegram Desktop.

Hi @stek29

Great catch!

Will rename it later today.

Any ideas what we shell call it?

In brew its just called telegram, in the app its just called the same.

Open to suggestions for app name and repo name.

I will also adjust the documentation to make sure its clear which version its for.

Update
I have just made some adjustments, see what you think.
https://github.com/soakes/telegram-message-exporter/pull/4/changes

carmolim commented Apr 30, 2026

I cant find the .tempkeyEncrypted file inside my Telegram app folder:

don't know if i use the "correct" app.

soakes commented Apr 30, 2026 •

edited

Loading

I cant find the .tempkeyEncrypted file inside my Telegram app folder: don't know if i use the "correct" app.

Hi @carmolim,

I believe the App Store version stores its data in a different location.

For reference, I tested this using the Homebrew version of Telegram:

❯ brew list | grep telegram
telegram

Update

I have updated the README to make the setup and usage instructions clearer.

Hope that helps.

carmolim commented May 1, 2026 •

edited

Loading

I found it, I opened it on vscode and by mistake hit save CTRL + S on the wrong tab and messed up with the .tempkeyEncrypted file 😭

imoyakin commented May 15, 2026 •

edited

Loading

I cant find the .tempkeyEncrypted file inside my Telegram app folder

cp ～/Library/'Group Containers'/6N38VWS5BX.ru.keepcoder.Telegram/appstore/.tempkeyEncrypted anywhere where you want to put the file

soakes commented May 15, 2026

I cant find the .tempkeyEncrypted file inside my Telegram app folder

cp ～/Library/'Group Containers'/6N38VWS5BX.ru.keepcoder.Telegram/appstore/.tempkeyEncrypted anywhere where you want to put the file

If you don't see it here then your using a different version:

 ❯ TELEGRAM_STABLE="$HOME/Library/Group Containers/6N38VWS5BX.ru.keepcoder.Telegram/stable"
ls -la "$TELEGRAM_STABLE"
total 16
drwxr-xr-x 13 soakes staff  416 May 15 06:23 .
drwx------  5 soakes staff  160 Apr  1 10:30 ..
-rw-r--r--  1 soakes staff  602 Mar 31 14:55 .com.apple.containermanagerd.metadata.plist
-rw-r--r--  1 soakes staff   64 Mar 31 14:55 .tempkeyEncrypted
drwxr-xr-x  6 soakes staff  192 Apr  2 17:14 account-5018265511298720455
drwxr-xr-x  6 soakes staff  192 Mar 31 14:55 accounts-metadata
-rw-r--r--  1 soakes staff 2192 Apr 22 09:31 accounts-shared-data
-rw-r--r--  1 soakes staff   21 May 15 06:23 crashhandler
drwx------  6 soakes staff  192 Mar 31 14:55 Library
drwxr-xr-x 22 soakes staff  704 May 15 04:03 logs
drwxr-xr-x  3 soakes staff   96 Mar 31 16:20 temp
drwxr-xr-x 64 soakes staff 2048 May 15 00:56 trlottie-animations
drwxr-xr-x 18 soakes staff  576 Mar 31 14:55 Wallpapers

stek29 commented Jun 6, 2026 •

edited

Loading

Author

@soakes I needed to export some chats and I didn't have enough time to do proper contributions with a PR, I've just forked the project and tasked codex with updating the project for media exports, forwards and support for newer actions and stuff like that, giving it this gist and iOS sources.

I also needed to work on a huge db (~13GB) and to export only some chats, so I've added some optimisations for streaming and filtering in sqlite instead of doing full scans like current references do.

thanks for the project, would be nice if you would be able to incorporate some stuff from my fork into yours.

https://github.com/stek29/telegram-message-exporter

soakes commented Jun 6, 2026

Hey @stek29, thanks for the kind words — and for putting this work together.

The media exports, forwarding support, newer action handling, and SQLite streaming/filtering optimisations all sound very useful, especially for larger databases. I’ll take a look through your fork and see what can reasonably be incorporated back into this project.

Thanks again for sharing it.

soakes commented Jun 6, 2026

Postbox Media and Forward Export Review

Hi @stek29,

Thanks again for the work and research on Postbox media and forwarded-message support. I have put together a PR that brings those ideas into this repository in a reviewable branch.

PR: soakes/telegram-message-exporter#5

Branch: feature/media-forwards-postbox

Rather than merging the fork directly, I selectively reimplemented the useful parts so we could keep the existing CLI behaviour, avoid unrelated README/repo URL changes, and add tests around the new parsing/export paths.

What Changed

Added Postbox schema constants for known Telegram media, action, and message-attribute types.
Added forwarded-message metadata decoding and export rendering.
Added best-effort media decoding for embedded and referenced Postbox media entries.
Added cached media export through a new --media-dir option.
Added automatic detection of the sibling Telegram postbox/media directory when possible.
Added media rendering in Markdown, HTML, and CSV outputs.
Preserved the existing --me-name option for outgoing speaker labels.
Added a --debug option for SQL key ranges and query plans.
Improved Postbox export performance by using peer key-range scans instead of full-table scans for targeted exports.
Fixed Postbox --contact lookup so filtered exports can resolve peer names correctly.
Kept date filtering after Postbox key decoding so newer or unknown namespaces are not silently skipped.
Made unknown media/action payloads best-effort so one unsupported Telegram object does not abort the whole export.

CSV and Render Behaviour

Existing CSV columns are preserved and metadata is appended rather than replacing or reordering existing fields.
Attachments are exported as JSON metadata in CSV.
Forward metadata is exported as JSON metadata in CSV.
Markdown and HTML show forwarded-from details and include links or embeds for copied media where possible.

How To Try It

Fetch the branch: git fetch origin
Check it out: git checkout feature/media-forwards-postbox
Install locally: python -m pip install -e .
Export with explicit media directory: telegram-exporter export --db /path/to/plaintext/db_sqlite --peer-id 123456789 --format html --out chat.html --media-dir /path/to/account/postbox/media
Export with media auto-detection: telegram-exporter export --db /path/to/account/postbox/db/db_sqlite --peer-id 123456789 --format html --out chat.html

If the database path is inside postbox/db/ and the sibling postbox/media/ directory exists, the tool should pick it up automatically.

Verification Already Done

black --check src/telegram_message_exporter tests telegram_exporter.py .github/scripts/bump_version.py
ruff check src/telegram_message_exporter tests telegram_exporter.py .github/scripts/bump_version.py
pylint src/telegram_message_exporter telegram_exporter.py
python -m pytest -q, currently 14 passed
python telegram_exporter.py --help && python telegram_exporter.py export --help
GitHub CI is passing on Python 3.10, 3.11, 3.12, and 3.13.

Review Request

Could you please check out the branch and try it against your Telegram data, especially exports with forwarded messages and cached media?

The main things to confirm are:

Forwarded-message metadata looks correct.
Photos/files/stickers/audio/video are copied or represented sensibly where cached media exists.
Existing text-only exports still behave as before.
--me-name still labels outgoing messages the way you expect.
--contact and --peer-id both work for your Postbox database.

If you are happy with the branch, I will merge the PR.

stek29/extract_telegram_macos.ipynb

Select an option

No results found

Select an option