
Dump a Telegram bot. Browse it like Telegram Web. Forensic CLI tool with web interface
Easy dumping of all Telegram bot stuff.
Input: only bot token.
Output: bot name & info, all chats text history & media, bot's users info & photos.
This is a Python implementation.
π Fast Golang version by ScBoln.
π Full documentation: https://telegram-bot-dumper.readthedocs.io
A Telegram-Web-like browser UI for a dump: chat list, full message history with inline media, user profiles with a photo carousel, and global search across every conversation at once. Live mode supported: it runs the dumper in the background and streams new messages to the browser in real time.
Open a conversation and choose Download chat to save its history, media, and
photos as dump_<bot_id>_<chat_id>.zip. The archive keeps the <bot_id>/<chat_id>/
directory structure and excludes other chats and bot-level files.
Use case β pentesting a leaked bot token. Telegram bot tokens turn up constantly on an engagement β hard-coded in a mobile/desktop app, committed to a repo, or sitting in a CI log, config file, or client-side bundle. On its own a token looks like a low-severity finding; loading it here shows the real blast radius. For an internal bot (support desk, IT/DevOps helper, AI assistant) that is every employee conversation with it β internal hostnames, VPN profiles, credentials, and infrastructure details β browsable and searchable, so you can scope the impact and evidence the finding in your report.

docker run --rm -p 127.0.0.1:8010:8010 -v "$PWD:/data" soxoj/telegram-bot-dumper-web
docker compose up --build # builds and serves on http://127.0.0.1:8010
pip install -r requirements.txt
python webapp/server.py # serves dumps from the repository folder on :8010
./run-viewer.sh # live mode + dumping new bots, API_ID/API_HASH from .env
Open http://127.0.0.1:8010 and paste the bot token to open its dump: it must match the token saved in that dump's bot.json. Read-only viewing needs no API credentials. Live mode additionally needs API_ID/API_HASH from my.telegram.org, passed via the environment β never baked into the image:
# one-off container
docker run --rm -p 127.0.0.1:8010:8010 -v "$PWD:/data" \
-e API_ID=123456 -e API_HASH=abc... soxoj/telegram-bot-dumper-web
# or with docker compose: put them in a local .env (see .env.example)
cp .env.example .env && $EDITOR .env && docker compose up
PORT and HOST env vars override the defaults (8010, 127.0.0.1).
By default the viewer only opens bots that already have a dump. Start it with --allow-new-dumps (ALLOW_NEW_DUMPS=1 in Docker) and a token with no dump yet is checked with Telegram, gets its folder and bot.json, and live mode dumps its whole history straight into the browser. This needs API_ID/API_HASH.
Anyone who can open the page can then make your server dump any bot under your API_ID, so the viewer refuses to start with this flag on a non-loopback HOST. In Docker HOST is always 0.0.0.0 inside the container, so add ALLOW_PUBLIC=1 (--allow-public) and keep the port on loopback yourself:
docker run --rm -p 127.0.0.1:8010:8010 -v "$PWD:/data" \
-e API_ID=123456 -e API_HASH=abc... -e ALLOW_NEW_DUMPS=1 -e ALLOW_PUBLIC=1 \
soxoj/telegram-bot-dumper-web
--down / --start-from-id).--listen-only): receive new messages in real time and offer to dump history downwards from the first observed id.[from:USER][group:CHAT]. Outgoing bot DMs are tagged with [to:USER].--listen-only will dump them in real time. With privacy mode enabled (the default) the bot only sees commands, mentions, and replies.requirements.txt for the pinned version)API_ID and API_HASHpip install -r requirements.txt
# Telegram API credentials from https://my.telegram.org (read from the environment)
export API_ID=123456
export API_HASH=abc...
Walks ids 1..β upwards in batches of 200, downloading every message, all media, and all user profile photos. By default, the dumper keeps listening for new incoming messages after the dump finishes. To exit immediately after history dumping (ideal for scripts and cron jobs), pass --no-listen.
./dumper.py --token 12345678:ABCe2rPVteUWZ7wLeCqCb3CH3ilUY_fLabc
For an active bot the upward walk hits a long stretch of pruned (deleted/expired) old ids and gives up. Walking down from the most recent id is much more productive. --down auto-probes the upper bound (powers of 10 up to 10βΉ) and starts from the highest non-empty id it finds:
./dumper.py --token TOKEN --down
Note. Telegram does not retain bot message history forever. Empirically, only the last few hundred thousand messages remain accessible β in our tests a busy bot exposed roughly the last 500K messages before
messages.getMessagesstarted returning onlyMessageEmptyfor older ids. If your bot has historically processed more traffic than that, the older history is simply gone server-side and no flag will recover it.
If you already know a recent message id (e.g. one you saw in real time), you can skip the probe and start exactly from it:
./dumper.py --token TOKEN --start-from-id 11922524
Don't dump anything; just watch what arrives. On the first incoming message the script will offer to start a downward dump from that id:
./dumper.py --token TOKEN --listen-only
Useful when you only need a roster of who has talked to the bot β no zips, no jpegs, no per-chat *_history.txt.
./dumper.py --token TOKEN --down --users-csv --no-photos --no-media --no-history
Output: <bot_id>/users.csv with columns id, username, first_name, last_name, phone, lang_code, bot, premium, verified, scam, fake.
The downward walk saves its next batch boundary to <bot_id>/last_message_id.txt.
If the run is interrupted, continue in the existing dump folder without probing again:
./dumper.py --token TOKEN --resume
Use the same --output directory as the original run, if one was set. Saved chat
history and the session file are kept. A missing or invalid checkpoint produces
an error before connecting. --resume cannot be combined with --listen-only
or --start-from-id; it implies a downward walk.