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

extract_telegram_macos.ipynb

@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

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.

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.