From account connection to a verifiable journal

• Phone

  Your number, the login code and, if set, your two-step verification password.

• QR code

  Scan it with a Telegram app that is already signed in.

• .session.json.zip

  Files

  A session file, TData ZIP or session text, plus its JSON if you have one.

• 9f2c 41ab e07d 5c13 a8f0 33d9 7b6e 0c42 9f2c 41ab e07d 5c13 a8f0 33d9 7b6e 0c42DC 2

  Auth key

  The complete 512-character hex key with its DC ID, from 1 to 5.

Supported formats

Phone number, code, and optional two-step verification

Sign in directly in Account. Telegram chooses how the code is delivered; SMS is not guaranteed.

QR login

Select QR code, press Show QR code and confirm in an already-authorized Telegram app under Settings → Devices → Link Desktop Device. Enter two-step verification if requested. Expired codes can be regenerated.

Telethon StringSession

Paste an authorized session string or load a plain-text .tgwitness-session or .txt file, up to 4 KiB.

Telethon SQLite .session

Load a closed, consistent schema 7/8 file directly. The optional Telethon-only CLI converter also accepts files up to 64 MiB.

Pyrogram SQLite .session

Load a schema 2/3 production user session. The panel detects its contents; renaming a file is not conversion.

Telegram Desktop TData ZIP

Quit Telegram Desktop, then ZIP only key_datas and the 16-character file ending in s beside it (usually D877F783D5D3EF8Cs) from the tdata folder; the whole folder with its cache is usually too large. Supply the Desktop local passcode if one is set. One account per archive; legacy layouts, multi-account folders, and encrypted ZIP containers are unsupported.

Session + JSON pair

Accounts are often supplied as name.session plus name.json. Select both together: the JSON supplies app_id/app_hash; other fields such as phone, device or a stored 2FA password are ignored, and TgWitness asks for 2FA when Telegram requires it.

Account JSON

Supported fields include api_id/app_id, api_hash/app_hash, Telethon StringSession, or complete 512-character Auth Key HEX with dc_id. A companion JSON may contain only API metadata; load it with a session or use phone/QR login.

Other formats

TDLib, Pyrogram StringSession, CSV/JSON bulk account lists, and bots are unsupported. Add each account in its own workspace.

Limits at a glance

• 4
  files per connection
• 8 MiB
  in total
• 64 KiB
  per JSON object
• 4 KiB
  per session text file
• 32 MiB
  TData ZIP, expanded
• 64 MiB
  SQLite via the CLI converter

{
  "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS",
  "dc_id": 2
}

• Demo mode

  scripts\Demo.cmd opens a local fictional workspace without copying a token. Real workspaces still need their panel token because the panel controls account authorizations and private records. This is separate from Telegram login.

• Monitoring settings

  Monitoring settings apply to the selected sources in the current account, survive restart, and record signed before/after changes. Keep new messages enabled for comparison context. Re-enabling a category does not recover missed events. Explicit history snapshots and operational diagnostics remain separate.

• Several accounts

  Add accounts with the + button beside the account selector or through Workspaces. Other collectors keep running when you switch views.

python -m tgwitness.sessions account.session --out account.tgwitness-session

1. Choose the workspace and scope. Each workspace belongs to one Telegram account and has its own sources, settings, journal, queue, and signing key. Add as many workspaces as you need.

2. Save the collection policy. Select new messages, edits, deletions, reactions, and membership events as needed. Settings apply to the workspace's selected sources. Re-enabling a category does not recover missed events.

3. Start observation. Updates from the active account client become separate signed records. An edit adds a version; a deletion notice does not erase text already captured. Unknown editors and deletion actors stay unknown.

4. Review outcomes and gaps. Attachments download separately when enabled. A queued attachment is not yet preserved. An explicit history snapshot saves current visible messages and cannot reconstruct missed changes.

What keeps collecting

• Pause observationCollection stops
• LockCollection continues
• Close the tabCollection continues
• Switch workspaceOnly the view changes
• Stop the Python processAll workspaces stop
• RestartMissed updates are requested

• Hide IP waits for a working proxy; direct fallback requires a mode that permits it
• Public MTProxy lists are built in
• Saved proxy passwords and secrets are never shown again
• Application routes do not configure a system VPN

1. Download

   Exports provides ZIP, JSONL, CSV, HTML, a checkpoint and a signed run receipt. Exports cover a full journal prefix for the selected workspace, regardless of search filters.

   Browsers with file-streaming support ask you to choose a destination first and write data as it arrives. Other browsers buffer at most 128 MiB. For larger files, use the streaming CLI while the server is running:

   python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

   Other workspaces, remote servers and limits

   For another workspace, add --profile PROFILE_ID. The ID appears at the top of Exports → Workspace ID. See all command options with:

   python -m tgwitness.download --help

   The token is sent in an HTTP header, not in the URL or command arguments. For a remote server, add --url https://your-server. The default transfer limit is 5 GiB, configurable with --max-mib. Signed ZIP content has a separate 4 GiB uncompressed limit. Existing output files are not overwritten.

2. Verify

   Verify using a trusted copy of the program:

   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json

3. Keep the fingerprint

   A signature establishes integrity relative to the trusted key, not Telegram origin. Retain the fingerprint and checkpoint independently. An RFC 3161 request alone is not a trusted timestamp; obtain and verify the authority's reply.

• Vault mode

  Storage protection shows the vault mode. Sessions and secrets are encrypted. Messages, attachments and exports require protected storage such as an encrypted disk/volume. An evidence ZIP is not an encrypted application backup.

• External master key

  New installations may use an external master key through TGWITNESS_VAULT_KEY_FILE. Do not delete vault.key or replace an existing installation's key: doing so can destroy access to sessions and signing keys.

• Backups

  For backup, stop the process cleanly and preserve the whole data directory, all workspaces and required keys. Temporary exports use each workspace's temporary-exports/; interrupted export files are cleaned on the next startup.

From the project directory, run:

$ python start.py --setup-only
$ python start.py --check
[PASS] python · fastapi · telethon · cryptography
[PASS] signing_backend: Ed25519 sign/verify available
[PASS] storage: Write probe passed
[PASS] listen_address: Address and port available at check time
Ready to attempt startup.
$ python start.py

• What the check tests

  The check tests dependencies, signing support, disk writes, the address/port and key configuration without Telegram login. An occupied port may mean another instance is running. Choose another --port or stop the previous process.

• Commands need the project environment

  Auxiliary python -m tgwitness… commands need the project environment: replace python with .venv\Scripts\python.exe on Windows or .venv/bin/python on Linux/macOS, or activate .venv first.

• Pause, lock and downtime

  Pause observation stops collection. Lock only closes browser access. Closing the tab does not stop the process. Events may be missed during downtime; a current-history snapshot cannot reconstruct every deletion or intermediate edit.

• Server deployment

  Server examples are included under deploy/, with full instructions in docs/DEPLOYMENT.md. Platform qualification and live Telegram acceptance are documented separately; TgWitness does not guarantee universal compatibility or complete capture.

1. Create read-only access for the selected account and save its access file.
2. Choose your channel and check interval, then save the configuration.
3. Install TgWitness on the witness host, add your BotFather token and follow the launch commands in step 3.

After launch, check the first signed post in your channel. The host runs the checks; the bot publishes their result. Another host and operator make the witness more independent.

VERIFIED CODE

Know which software made the record.

In Extras, open Verified code from GitHub and enter your fork or the official repository with a release tag or commit. TgWitness compares every program file with that commit and saves the result in the signed journal, so an export shows which public code was running. No GitHub token is needed.

1. Fork the repository on GitHub and review the code, or use the official one.
2. Enter the repository and a release tag or commit: a commit cannot change later, a branch can.
3. Check again after every update; the badge shows when the running code is no longer the checked one.

A GitHub token grants repository access; it does not prove that the running server is unchanged. Build verification and independent witnesses provide different checks. No GitHub token is needed on this page.

Many expect standard geographic or political blocks, such as OFAC lists or regional bans against Russia. TgWitness enforces none of them: it is released under the MIT License for everyone, in every country.

The only incompatibility we name is Taylor Wessing and anyone who believes their words or authority stand above mathematics: those who enable or defend corporatocracy, privatized or commercial justice, plutocracy, kleptocracy and institutional corruption. Truth is available to all, except to those who think their signature under a lie turns it into reality.

This is our position as the authors of TgWitness, not a licence condition. Read our full notice