TgWitness
English
EnglishРусскийУкраїнськаEspañolPortuguês (Brasil)Türkçeالعربيةفارسیاردوहिन्दीBahasa IndonesiaTiếng Việt简体中文FrançaisDeutschItalianoO‘zbekcha한국어繁體中文Bahasa MelayuPolski日本語ไทยעבריתবাংলা
Open source / v0.7.0

Messages change.
Keep what
you saw.

Capture Telegram messages, preserve their changes, and export a signed record.

Open demo Setup guide

The demo uses fictional data. No Telegram sign-in required.

GitHub Actions capture (preview) S3 off-site copy: setup and recovery
A MESSAGE, THROUGH TIME#0042
Northstar · ResearchFictional source / message 42
  1. Message observed

    The briefing starts at 14:00.

  2. Edit preserved

    The briefing starts at 15:00.

    Previous version retained
  3. Deletion notice

    Captured content stays in your journal.

Three observations. One history.EXAMPLE

The message disappears. The captured history remains.

01 THE WORKSPACE

Every captured change.
Right where you need it.

Browse the interface with fictional demonstration data.

TgWitness / Saved chatsYOUR OBSERVATION WORKSPACE
Saved Telegram conversations in the dark theme, with captured edits and deleted messages kept in context
01 / Saved chats A familiar conversation view, with captured edits and deletion notices alongside the messages.
TgWitness / JournalLOCAL WORKSPACE
Journal with observed messages, edits, deletion notices and coverage events
02 / Journal A searchable timeline of what your account observed, including interruptions.
TgWitness / Edit historyLOCAL WORKSPACE
Detail drawer comparing the captured previous and edited versions of a message
03 / Edit history Compare captured versions without overwriting the earlier observation.
TgWitness / Signed exportsLOCAL WORKSPACE
Export workspace offering a signed ZIP, JSONL, CSV and an offline HTML report
04 / Signed exports Take the journal with you, with a manifest and an independent verifier.
01 / CAPTURE

You choose the scope.

Chosen chats, a Telegram folder or the whole account. A separate workspace for each account.

Compare collection modes
02 / PRESERVE

Changes add to the story.

Captured versions, deletion notices and observation gaps stay in the journal.

See the event matrix
03 / HAND OVER

A record that travels.

Signed ZIP, preserved files and an offline report. Optional password protection.

Export and verify

HOW THE RECORD HOLDS TOGETHER

Change one byte.
The chain tells you.

Each event links to the previous hash and carries an Ed25519 signature.

Captured events link to previous hashes, carry signatures and travel in a verifiable export.
Changing a captured record changes its hash and breaks verification of the linked record.
A separately retained checkpoint lets a recipient compare the exported journal with an earlier observation.

See what each verification mechanism establishes, and where its limits remain.

Explore eight evidence levels

BUILT FOR REVIEW

Ready for
another pair
of eyes.

Hand over observations, files and an offline HTML report in one signed bundle.

Read the evidence model
tgwitness-evidence.zipSIGNED BUNDLE
  • 01
    Original observationsJSONL records + CSV table
  • 02
    Readable contextOffline HTML report + preserved media
  • 03
    Independent verificationSigned manifest + standalone verifier

Signatures detect tampering relative to a trusted key. They do not prove Telegram origin or guarantee complete capture. Journal content and media need encrypted storage provided by you.

STORAGE, CONTINUITY AND VERIFICATION

S3 copies.
External checks.

Keep encrypted copies and add independent checks.

EXPORTS → OFF-SITE COPY

Off by default

Copy everything to S3-compatible storage

Journal, files, timestamped checkpoints and chat exports — encrypted before upload to AWS S3 or compatible storage.

Storage settings and recovery
Client-side encryption
AES-256-GCM encrypts objects on this machine. The provider receives encrypted objects.
Scheduled or manual copies
Copy now, or choose an interval from 1 to 1,440 minutes. Check progress in the panel.
Object Lock
Choose retention days and a mode when the bucket supports it. The panel reports whether retention was confirmed on an uploaded object.
Verified recovery
Download the encryption key and keep it separately. Restore on another machine; files are published only after verification.
Complete Off-site copy panel: endpoint, region, bucket, access keys, schedule, Object Lock and recovery key controls
The complete panel with advanced options expanded. No storage credentials are shown.
Journal and mediaAES-256-GCMS3-compatible storage
Configure S3 and restore a copy Read the verification details

Does not do It does not restore without the exported decryption key or replace an independent witness.

Notifications · Apprise

Problem alerts, chat changes and daily summaries via Apprise: messengers, email or your own JSON webhook.

Does not do It does not send message text unless you enable excerpts.

Configure notification destinations

External timestamps

Timestamp checkpoint hashes with RFC 3161 and OpenTimestamps.

Does not do It does not treat a pending calendar receipt as a confirmed Bitcoin timestamp.

Check timestamp proofs

Independent witness

A separate host keeps signed observations and can publish TGW1 checkpoints.

Does not do It does not make two workspaces on one collector host into independent witnesses.

Set up a witness

Recovery and visible gaps

Resume after restart. Rechecks and coverage.json show recovered messages and gaps.

Does not do It does not reconstruct every missed edit or vanished message.

Inspect continuity and gaps

ON YOUR MACHINE

Your first workspace starts here.

Explore the demo first. Connect a dedicated account when you’re ready.
Windows, Linux, macOS, or Docker.

Read the setup guide
Take a look before you connect.

Try the fictional workspace without a Telegram account.

Open the online demo →

Windows scripts\Demo.cmdLinux / macOS sh start.sh --demo
Local installation commands
STEP 01

Get the source.

Download the source ZIP and extract it, or clone the repository:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

Source launch needs Python 3.11+. The Windows launcher offers installation if Python is missing.

Browse releases

No Python on Windows? Download the portable package, extract it and double-click TgWitness.cmd.

STEP 02

Choose how to run.

Double-click Start.cmd, or run in PowerShell:

.\Start.cmd

Just exploring? Double-click scripts\Demo.cmd for an isolated demo. No Telegram login needed.

With Python 3.11+ and venv available:

sh start.sh

To open the fictional journal instead, run sh start.sh --demo.

With Docker running and Compose 2.20+ installed:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

The second command shows your private panel token. Keep it on your machine.

Open 127.0.0.1:8787 after launch.

For source installs, the token is in data/live/panel-token.txt. Telegram sign-in can use the built-in API settings or your own pair from my.telegram.org. Full setup guide ↗

TgWitness 0.7.0 What’s new → · Features and known limits →

ONE TASK AT A TIME

Clear instructions.
A useful next step.

Explore the guides ↗

Modes, scenarios and evidence levels

Four collection modes. Eight verification levels. Find the workflow for your case.

01

Connect an account

Phone, QR, and supported session imports.

02

Choose a proxy

Public MTProxy lists or your own route.

03

Set up a witness bot

Signed checkpoints in your Telegram channel.

04

Export and verify

Share captured history and check its integrity.

Work the archive.

Load history, review AI sources, connect an MCP client, recognize saved media and send signed webhooks.

Available from current source. The 0.7.0 portable preview predates these tools.

Explore the workflow

Before you start.

Does this page connect to Telegram?

No. This is a static project page with fictional examples and screenshots. The actual application runs on your computer or server; sign-in happens there.

Can it recover messages deleted before capture?

No. TgWitness retains content your account observed while collection was running. A later history snapshot cannot reconstruct missed edits or deleted messages.

Is my whole journal encrypted?

Account credentials and signing secrets are stored in an encrypted vault. Local messages and attachments need an encrypted disk or volume. Exports can optionally use a password-protected AES-256 ZIP.

Is this affiliated with Telegram?

No. TgWitness is an independent project using Telethon, distributed under the MIT License. You authorize your own accounts, using the built-in API settings or your own API pair.

PROJECT NOTICE / LICENCE

Operator incompatibility.

Taylor Wessing PartG mbB — German core, Hamburg office.

Our statement as the authors of TgWitness. It adds no condition to the MIT License. Read the complete notice and its source record.

Read the complete notice Original text

YOUR NEXT STEP

Explore first.
Set up when ready.

Open demo Setup guide