- Records
- Only sources selected by hand.
- New chats
- Not added automatically.
- Choose for
- A known set of channels or groups. No fixed chat capacity has been qualified.
Modes, scenarios and evidence levels
One journal. Four collection modes. Eight verification levels.
TgWitness records what the connected account observes. A third party can verify the record’s integrity against an independently trusted key.
- Telegram
Account-visible updates
- Collector
Linked records, each signed
- Verifier
Trusted key + retained boundary
h₁ → h₂ → h₃ · Ed25519Read each observation together with its source identifiers and acquisition record.Choose the observation scope
Three scopes and an investigation preset. Exclusions and enabled source types still apply.
- Records
- Folder inclusions and categories, minus exclusions and archived chats when configured.
- New chats
- Matching active chats; folder changes within an hour.
- Choose for
- An analyst already maintains a case folder. Confirm collection on a dedicated account.
- Records
- Account-visible chats, including private conversations and bots, within selected types.
- New chats
- Added when the first update arrives.
- Choose for
- A dedicated observation account, including an account participating in a case.
- Records
- All source types, own actions, source profiles and the latest 200 visible messages of newly discovered sources.
- New chats
- A new chat or bot gets a profile and a history snapshot.
- Choose for
- Join a team or interact with a bot through the panel. Review and save the preset.
These cards are a local comparison, not live collector controls. They do not change an account.
Read the detailsWhat is recorded
Only delivered or explicitly requested observations enter the record. Unknown attribution stays unknown.
The panel applies these switches per workspace. Turning one off keeps existing records; turning it back on does not reconstruct missed events.
Event matrix: saved material and remaining unknowns
| Category | Saved |
|---|---|
| Message | Text, IDs, sender metadata, reply context and original update envelope. |
| Edit | Every observed version, without overwriting earlier ones. |
| Deletion | Notice plus previously saved text, if available. |
| Unscoped deletion | Account-level notice; unknown peer remains explicit. |
| Reaction | Delivered counters and visible recent identities. |
| Membership | Delivered service messages and participant updates. |
| Attachment | Original-version descriptor, saved bytes, SHA-256 and attempt outcomes. |
| History snapshot | Currently visible messages, marked as history observations. |
| Own actions | Outgoing messages/edits and matching reply-keyboard button_press metadata. |
| Bot buttons | Callback, URL, web-app and request metadata retained with the message. |
Default attachment limits
- Photos
- 20 MiB
- Video
- 100 MiB
- Files
- 50 MiB
- Animations
- 20 MiB
- Video notes
- 50 MiB
- Voice
- 20 MiB
- Audio
- 50 MiB
- Stickers
- 5 MiB
Use the authorization you have
Each account has its own workspace, journal, signing key, route and queue.
Phone + code
Enter 2FA when enabled.
QR code
Scan from an authorized device; 2FA may still be required.
Telethon .session
Import the account’s session file.
Pyrogram .session
Import the supported Pyrogram session format.
TData ZIP
One supported Desktop account; local passcode if set.
StringSession text
Paste a Telethon StringSession.
.session + .json
Select the session and matching companion metadata.
Auth key HEX + DC ID
Import account authorization with its data-center identifier.
Direct · SOCKS5 · HTTP CONNECT · MTProxyMTProxy is experimental; built-in public MTProxy lists are available. A failed proxy route does not fall back to a direct connection.
Two workspaces on one machine are not two independent witnesses.
Account formatsAct from the panel
Send or reply, press a current bot button, save a link preview, then explicitly join a chat or start a bot with its start parameter.
interaction.previewinteraction.requestedinteraction.resultPreview, request and result receipts are signed. Before a button press, the server fetches the message again and rejects a changed keyboard. Returned callback text and URLs remain recorded context.
Read the detailsRecovery and continuity
Gaps are shown, not hidden.
Resume the saved position
After restart, Telegram is asked for missed updates. Finite retention and expired differences can leave gaps.
Recheck visible messages
Defaults: priority sources every 15 minutes, others every 6 hours. Outcomes include message.recovered and message.missing_on_recheck.
Read coverage.json
Observation periods, gaps with reasons and unobserved IDs accompany the signed export. A missing-on-recheck record is not a deletion notice.
Seven levels. Different questions.
Each mechanism answers a bounded question. Configure external services separately and retain their trust anchors outside the collector.
-
Record
SHA-256 chain + Ed25519 per event; the first previous_hash is 64 zeroes.
Third party checks Ordering and signatures under the pinned collector key.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 -
Container
manifest.json lists file hashes; manifest.sig signs it. media.saved binds attachment bytes to an event.
Third party checks The supplied files agree with the signed manifest and media receipts.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 -
Retained boundary
Checkpoint at startup, every 5 minutes by default, and orderly stop. Keep a copy elsewhere.
Third party checks The later export agrees with an earlier retained length and head; rollback can be detected.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json -
External time
Evidence mode sends a checkpoint SHA-256 to RFC 3161 authorities (FreeTSA, DigiCert) and OpenTimestamps calendars.
Third party checks A verified TSA response dates those bytes; a confirmed OpenTimestamps proof anchors them to Bitcoin.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca trusted-ca.pem ots upgrade checkpoint.ots ots verify checkpoint.ots -
Independent witness
Separate host, scoped read-only endpoint, fresh challenge, its own key/journal and TGW1 channel posts.
Third party checks Earlier accepted heads; statuses ok, key_changed, rollback, fork, invalid and no_response.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/WITNESS_CHANNEL -
Off-site replica
S3-compatible copy encrypted with AES-256-GCM; Object Lock when the bucket supports it.
Third party checks Restore publishes files only after journal, checkpoint and preserved-media verification succeeds.
Verification command
python -m tgwitness.replica restore --key-file KEY.json --out EMPTY_DIR -
Run provenance
Signed run receipt: source hashes, dependency versions and process context. Self-reported.
Third party checks What the signing collector reported about its own execution.
Verification command
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256
Local SHA-256 experiment
Try changing record 2
The next record keeps the previously saved link. Changing the text changes record 2’s calculated hash.
h1Starts with 64 zeroesh2Includes the saved h1h3Includes the saved h2Static example: h2 covers “Meet at 11:00”. Changing that text changes h2; record 3 still references the saved h2.
Inspect the full digests
- Saved record 2 hash
SHA-256(e₂)- Recalculated record 2 hash
SHA-256(e₂)
Choose a route through the evidence
Fictional situations. Start collection before the relevant event; preserve the boundaries and gaps alongside the content.
A channel changes payment details
- Mode → events
- Chosen chats → messages, edits, deletions.
- Output
- Observed post versions and attachments by hash.
- Verification
- Signed ZIP + retained checkpoint + verified TSA response.
Messages disappear after an incident
- Mode → events
- Folder or whole account → all event categories.
- Output
- Saved originals, deletion notices and coverage with gaps.
- Verification
- Signed ZIP + independent witness journal.
Investigate a shop bot
- Mode → events
- Investigation preset → buttons, link previews and explicit bot start.
- Output
- Signed interaction receipts, returned callbacks and saved profiles.
- Verification
- Signed ZIP; verify any dossier against the ZIP.
A participant changes names across chats
- Mode → events
- Any scope → observed sender/profile metadata.
- Output
- Name/username history by numeric ID, “also in” links and extracted leads.
- Verification
- Dossier JSON checked against the signed ZIP.
Long-running observation with an off-site copy
- Mode → events
- Any scope → Evidence mode and an S3 replica with supported Object Lock.
- Output
- Encrypted copy, retained checkpoints and timestamp responses.
- Verification
- Restore with the exported key, then verify without the original server.
Hand over a checkable package
Supply the signed original, an independently retained key fingerprint, the relevant checkpoint and the verification result.
- Signed ZIP
- JSONL
- CSV
- HTML
- Checkpoint
- Run receipt
- Chat export: chat.json / chat.html
- Dossier JSON
- Password-protected AES-256 ZIP
- Separate exports for multiple accounts
- Streaming CLI: 5 GiB default limit
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint checkpoint.json --require evidenceObtain the verifier from a trusted copy, not from the archive being checked.
Read the detailsCompare the delivered artifact
Basic artifacts without added signing, timestamp or witness systems. Scripts and loggers vary by implementation; “partial” means limited to captured or visible material.
| Approach | Edits / deletions | Record signature | External time | Independent witness | Coverage / gaps | Verification without author |
|---|---|---|---|---|---|---|
| Telegram Desktop export | Partial | No | No | No | No | No |
| Telethon snapshot script | Partial | No | No | No | No | No |
| Deletion logger: text log | Partial | No | No | No | No | No |
| Screenshots / web capture | Partial | No | No | No | No | No |
| TgWitness with configured extras | Partial | Yes | Yes | Yes | Partial | Yes |