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.

3–5 minute overview · fictional examples · current implementation

  1. Telegram

    Account-visible updates

  2. Collector

    Linked records, each signed

  3. 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
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.
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 details

What is recorded

Only delivered or explicitly requested observations enter the record. Unknown attribution stays unknown.

Capture switches · local illustration

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
CategorySaved
MessageText, IDs, sender metadata, reply context and original update envelope.
EditEvery observed version, without overwriting earlier ones.
DeletionNotice plus previously saved text, if available.
Unscoped deletionAccount-level notice; unknown peer remains explicit.
ReactionDelivered counters and visible recent identities.
MembershipDelivered service messages and participant updates.
AttachmentOriginal-version descriptor, saved bytes, SHA-256 and attempt outcomes.
History snapshotCurrently visible messages, marked as history observations.
Own actionsOutgoing messages/edits and matching reply-keyboard button_press metadata.
Bot buttonsCallback, 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
Read the details

Use the authorization you have

Each account has its own workspace, journal, signing key, route and queue.

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 formats

Act 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.result

Preview, 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 details

Recovery 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.

Read the details

Seven levels. Different questions.

Each mechanism answers a bounded question. Configure external services separately and retain their trust anchors outside the collector.

  1. 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
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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.

Record 1h1Starts with 64 zeroes
Record 2h2Includes the saved h1
Record 3h3Includes the saved h2

Static 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₂)
This sample calculates hashes, not signatures. The real verifier checks every signature and link against the trusted key.
Read the details

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.
Read the details

Hand over a checkable package

Supply the signed original, an independently retained key fingerprint, the relevant checkpoint and the verification result.

python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint checkpoint.json --require evidence

Obtain the verifier from a trusted copy, not from the archive being checked.

Read the details

Compare 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.

ApproachEdits / deletionsRecord signatureExternal timeIndependent witnessCoverage / gapsVerification without author
Telegram Desktop exportPartialNoNoNoNoNo
Telethon snapshot scriptPartialNoNoNoNoNo
Deletion logger: text logPartialNoNoNoNoNo
Screenshots / web capturePartialNoNoNoNoNo
TgWitness with configured extrasPartialYesYesYesPartialYes
Read the details