TGWITNESS / REFERENCE
Telegram Collection & Evidence Technical Reference
Every document of the project, rendered here with its diagrams. The guides are the short path; these pages hold every detail.
Set up
TgWitness: start, scale and evidence
Install with one command or capture on GitHub Actions. Understand investigation options, published scale and what an archive verifies.
02Quick start
Every way to install and launch TgWitness: Windows package, Python, Docker and the synthetic demo, with first checks.
03Install, verify and update
Install with one command, check signatures and hashes, update and remove an installation.
04First setup and settings
The setup wizard, goals, interface levels, connection routes and settings shared by an account group.
05Accounts and session formats
Sign in by phone, QR code or auth key, import Telethon, Pyrogram or Telegram Desktop sessions, and run several accounts.
06Access and permissions
Issue scoped access to accounts and chats, choose permissions, limit sessions and IP addresses, and withdraw access.
07Connection, proxies and data protection
Authentication, automatic proxy pools, IP modes, fallback policy, external requests and secret storage.
08Deployment
Run TgWitness as a service on Windows, Linux, macOS or Docker, behind HTTPS, with backups and updates.
09High-assurance deployment
A sealed 24/7 server on Hetzner or Phala Cloud, Gateway DNS and the checks a third party can repeat.
Collect
Panel guide
Every screen of the panel: chats, journal, sources, exports, Extras, protection modes and the code check.
11How collection works
Observation scope, live updates, rechecks, attachments, own actions and what a gap means, record by record.
12Secret Chats: setup and recording
Install the Secret Chat protocol extra, enable it per account and record the chats TgWitness creates or accepts.
13Load source history
Load past messages from enabled sources, pause and resume, and verify a signed progress report.
14Workflows and operations
Daily operation of the panel: modes, monitoring categories, parameters, notifications, exports, backup and capacity.
15Investigation mode
Whole-account investigations across channels, groups, private chats and bots, from scope to a verified case package.
16Features and scope
The current collection model, multi-account workflows, exports and operational boundaries of TgWitness.
Archive & integrations
Case Board reference
Bookmarks, exact highlights, action slices, discussions, scoped access and the signed annotation history used by Case Board.
18Archive analysis
Search saved messages, review AI inputs and keep analytical reports with their source references.
19Full-text search
Find saved messages by word forms, exact phrases, domains and @usernames, best matches first, with the index bound to the signed journal.
20Read-only MCP
Connect an MCP client to selected workspaces and chats with expiring, revocable access.
21Command line
Search, read context, count activity and export saved messages from scripts and agents, with --json output, stable exit codes and scoped read-only tokens.
22Local OCR and transcription
Recognize captured images and audio with a local worker; keep derived text linked to its source file.
23Outgoing webhooks
Send scoped events to HTTPS receivers with HMAC signatures, retries and delivery status.
24Public showcase
Publish saved messages of selected public channels and signed snapshots through expiring, revocable links.
Evidence
How the evidence works
Hash chain, signatures, checkpoints and witnesses explained with the exact formulas the verifier uses.
26Report configuration and verification
Report filters, eight designs, contents presets, saved change histories and the assessment included in signed exports.
27Account export
Export what an account can read now: scope, resumable jobs, a signed archive and minimized sharing copies.
28Evidence format
Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification.
29Translating reports for court
Which file is the original, what to file with a certified translation and the terms translators keep.
30Independent witness
Run a witness with its own key and bot, publish signed checkpoints to a channel and check exports against it.
31Timestamps
RFC 3161 timestamps for signed checkpoints: what is sent to the authority and how a response is verified.
32Storage and recovery
Backups, moving older files to your cloud, copies under Object Lock and recovery on a new machine.
Security & project
Security and data handling
Threat model, access model, secrets at rest, network exposure, session imports and how to report a vulnerability.
34Architecture
Components of the collector, panel, journal, workers and witness, and how data moves between them.
35What has been tested
The live Telegram test, automated checks, browser checks and the next qualification runs.
36Licence and architectural incompatibility notice
TgWitness is MIT-licensed for everyone, and why it is architecturally incompatible with the Taylor Wessing workflow.
37Operator incompatibility notice
Our operator notice on Taylor Wessing and its source record.
38Changelog
Every change by version, including the changes not yet released.