TGWITNESS / REFERENCE

The complete reference

Every document of the project, rendered here with its diagrams. The guides are the short path; these pages hold every detail.

Set up

Quick start

Every way to install and launch TgWitness: Windows package, Python, Docker and the synthetic demo, with first checks.

Accounts and session formats

Access and permissions

Issue scoped access to accounts and chats, choose permissions, limit sessions and IP addresses, and withdraw access.

Connection, proxies and data protection

Authentication, automatic proxy pools, IP modes, fallback policy, external requests and secret storage.

Deployment

Run TgWitness as a service on Windows, Linux, macOS or Docker, behind HTTPS, with backups and updates.

Collect

How collection works

Observation scope, live updates, rechecks, attachments, own actions and what a gap means, record by record.

Load source history

Load past messages from enabled sources, pause and resume, and verify a signed progress report.

Workflows and operations

Daily operation of the panel: modes, monitoring categories, parameters, notifications, exports, backup and capacity.

Investigation mode

Whole-account investigations across channels, groups, private chats and bots, from scope to a verified case package.

Features and limits

What TgWitness implements today, what the Telegram platform limits and what remains future work.

Archive & integrations

Archive analysis

Search saved messages, review AI inputs and keep analytical reports with their source references.

Read-only MCP

Connect an MCP client to selected workspaces and chats with expiring, revocable access.

Local OCR and transcription

Recognize captured images and audio with a local worker; keep derived text linked to its source file.

Outgoing webhooks

Send scoped events to HTTPS receivers with HMAC signatures, retries and delivery status.

Evidence

How the evidence works

Hash chain, signatures, checkpoints and witnesses explained with the exact formulas the verifier uses.

Evidence format

Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification.

Independent witness

Run a witness with its own key and bot, publish signed checkpoints to a channel and check exports against it.

Timestamps

RFC 3161 timestamps for signed checkpoints: what is sent to the authority and how a response is verified.