TgWitness Panel: Chats, Journal & Exports

TgWitness / Documentation · Getting started

First setup and settings · Accounts · Export and verify · Case reports

What each screen does, what it writes to the signed journal and where the detailed guide is. The panel shows one workspace at a time: one Telegram account with its own sources, journal and signing key. The selector at the top of the sidebar switches workspaces. The address carries the workspace (?ws=…); while the address, the selector and the loaded account disagree, actions stay blocked.

Use Compare collection methods to choose between live observation, full history, fresh account/chat exports and saved-record handover. The Exports page includes the same comparison above its download controls.

On this page

• Find your way
• Start here
• Chats
• Journal
• Sources
• Exports
• Settings, accounts and connection
• Extras
• Protection modes
• More tools

Find your way#

Daily sections are at the top of the sidebar, Accounts is under Workspace, and everything else is under More tools & settings. The Interface level switch in the top bar decides how many sections appear:

Simple calls Start here, Journal and Exports Home, Changes and Archives. A level only hides sections. A hidden feature keeps working, and the server checks every permission on its own. Level, language, theme and time zone are saved per operator and workspace; see settings.

The top bar also has:

• Go to a section (Ctrl+K, or ⌘K on a Mac): find a chat, a parameter or a journal record by #number. Arrow keys move, Enter opens, Esc closes.
• Notifications: problems and chat changes worked out from the journal. Mark all as read clears the counter and Notification rules opens the rules. Delivery to Telegram, Discord or email is set up in Extras → Notifications.
• The connection indicator for this workspace. Collector health under the top bar splits it into the Telegram connection, event intake, sources and the attachment queue.
• Lock: closes the panel in this browser. Collection keeps running on the server.
• The protection mode next to the version number; see protection modes.

The demo workspace contains fictional messages and never connects to Telegram. Actions that would change a real workspace are refused there.

Start here#

Choose a task. Export my account downloads what the account can read now. Follow an investigation records new messages, observed edits and deletion notices from the chats you choose. The setup card shows the three steps: connect the account, choose sources, start observation. The goal question stays on this page until you answer or skip it. A new workspace opens the first setup instead.

Chats#

Saved conversations, read-only by default.

• Search the list by name or ID. Choose adds or removes watched chats. Open Telegram link takes a username or invite link and saves a preview to the journal. Join / open and observe then joins the chat and adds it to your sources; opening a bot sends it /start.
• The chat header counts messages deleted, text kept, deleted before saving and not found on recheck. The chat list and notifications use the same definitions. A deleted message is red and keeps its saved text; an edited message keeps every saved version. Each deletion says what is known: when it was seen, that Telegram does not report who deleted it, or that only the notice arrived.
• Load history brings the last 100, 250 or 500 messages into this view and the journal. To load every enabled source, use Sources → Full history.
• Export chat downloads the whole visible history as a signed chat.json and chat.html. Several connected accounts can share the work: each downloads its own range of message numbers and signs its part, and the account that starts the export signs the archive. See export one chat.
• People lists everyone with saved messages in this chat. People profiles are off by default because they are personal data about third parties. When they are on for a chat, a profile shows name and username history, Telegram flags, avatar hashes, activity, who replies to whom, other observed chats, and mentioned wallets, phones, usernames and links. Every fact points to its record. Export profiles saves a signed file, optionally in a password ZIP; turning profiles off deletes the profile file. See people profiles.
• Save profile now records a snapshot of the chat or bot profile: description, members, invite link, bot commands.

Read-only, sending and secrets#

Two switches above the messages protect the account and the reader:

• Read-only is on when a chat opens. Turn it off to send messages or press bot buttons. Each action asks Send as @account? or Press this bot button as @account?, tells you that chat members see it and that it goes into the signed journal. Do not ask again for 10 minutes in this chat skips the question for a while. Sending is off for the Evidence for a case goal, in the panel and in the API.
• Mask secrets hides what looks like a password, a login code, an API key or hash, a bot token, a session string, a private key, a JWT or a payment card number (card numbers are checked with the Luhn sum). Show reveals one value; the reveal is recorded in the journal. Turning masking off for this browser is recorded too. Only the display changes: the original records and every export keep the full text.

Journal#

Every record the workspace has signed, newest first.

• Overview counts observed messages, recorded edits, deletion notices and selected sources.
• Event timeline filters by event type (all, edits, deletions, reactions, membership, coverage), by text and by source. Load earlier events pages back.
• Open a record to see its details, hash and payload. Link to this record is an address that opens the same record. Possible secrets are masked in this preview; exports keep the original.
• The journal is append-only: nothing in the panel edits or deletes a record. Check it with Exports → Verify journal or python -m tgwitness.verify; see export and verify.

Sources#

Which conversations this workspace records, and what it keeps from them. Changes apply to future activity; saved records stay.

Refresh chat list reads the account's chats and folders. It does not download messages.

Scope#

• What this account records: Chosen chats (only the chats you add), Telegram folder (one of the account's folders, including chats added to it later) or Whole account (every chat, and every new chat, group, private chat or bot as it appears). Investigation mode is for a dedicated account: it records everything the account sees, its own messages and button presses, and saves each new chat's profile and earlier visible messages straight away. The dedicated account guide explains why never to use your main account.
• Source types limit folder and whole-account modes to channels, groups, private chats and bots. Own actions adds the account's own messages, edits and reply-keyboard presses.
• When a new chat or bot appears: save its profile and up to the chosen number of its latest visible messages.

Limits: the published cloud collector does not receive Secret Chats. The separate Pseudo-secret interface and its demo are documented with their development status and outstanding defects. Nothing is recorded while TgWitness is not running; after a restart it catches up only what Telegram still returns, and the report shows the gap. Chats beyond the chat list limit (1,000 dialogs unless changed in Parameters) are added when they next become active. Inline bot buttons pressed in another app are invisible; the bot's reply is recorded.

Chats in scope#

Filter by status (Enabled, Paused, Priority, Excluded, Unconfirmed access, Ignored) and type, then act on a selection: enable, pause, mark or remove priority, exclude from scope or remove. The status badge only shows the state; actions are in each row's menu with a line on what they do. Pausing and excluding ask for confirmation, also in bulk. Removing a source asks for its name and deletes its people profiles; its saved records stay in the journal.

A source the account's chat list does not show is receiving updates, not in the chat list while records keep arriving, otherwise access unconfirmed. Available chats adds chats with Add selected or Add all matching.

Full history#

Loads the available history of every enabled source into Chats and the journal. Progress survives a restart; attachments follow your media settings. See source history.

Recording#

• Choose which changes to preserve: new messages, edits, deletion notices, visible reactions, joins and leaves. A preset changes the form; Save recording settings applies it. Turning a category back on does not recover missed events.
• Preserve media when available: download attachments up to a size per file, set per type from 1 to 2,000 MiB, and limit video length in seconds (0 means no limit). Every download attempt gets a recorded outcome.
• Recheck: priority chats every few minutes, other chats rarely, so the account stays clear of Telegram's FloodWait limits. 0 turns a group off. Mark priority chats with the star in the list; chats per pass and the pause between chats are in Parameters. See collection.

Exports#

Downloads prepares files; Build report chooses how reports look.

• Encrypt the downloads above with a password (12 characters or more) saves an AES-256 ZIP that 7-Zip or WinRAR opens. The signed file inside is unchanged. The password is not stored.
• Prepared exports keeps up to 20 files within 2 GiB, plus the latest one, for repeat downloads, each with its SHA-256. Preparing a file does not prove delivery.
• When the browser refuses its save dialog, the panel falls back to an ordinary download.
• Your signing identity shows the key fingerprint. Save checkpoint and Download signed run receipt give you records to keep outside the collector. Prepare timestamp request builds an RFC 3161 request without contacting any service.

Settings, accounts and connection#

• Settings: goal, connection, what to record and the interface. See first setup and settings.
• Accounts: every workspace with its state, sources, events and attachment queue. Filter by Needs attention, Collecting, Offline or paused or Not connected, pause or resume a selection, import account files in bulk and manage groups. See accounts.
• Account: sign-in and the connection route of this account. Direct, a WireGuard profile, your own proxy, the public MTProto pool or WARP; prepare and check a route, then apply it to this account, a group or all accounts. See connection and proxies and proxies.

Extras#

Optional: an account and sources are enough to start collecting. Only the option you choose opens its settings, and nothing is connected automatically. The Protection level card at the top shows the protection mode.

Goal and protection level#

Four questions:

1. What is it for? A personal record, an investigation, or evidence for a case.
2. How much will you observe? A few chats (up to about 50), many chats (up to about 500) or whole accounts. This sets the chat list limit to 1,000, 3,000 or 20,000.
3. Photos and files? Text only, photos and short media (photos 20 MB, videos 100 MB), or everything (videos and documents up to 1 GB each). Everything with whole accounts also keeps 4 GiB of disk free.
4. Where will it run? This computer, or a server that is always on.

The suggestion lists independent timestamps, drand and Telegram's device list, each with a line on what it adds. Timestamps start every 60, 30 or 10 minutes for a personal record, an investigation or evidence; drand and the device list need timestamps. Apply changes only these, the attachment policy and the two parameters above. Each change is a journal record, plus setup.applied. Notifications, an off-site copy, a server, Gateway DNS, the code check and a witness are offered as next steps with their own forms.

Two scales are computed from what is set, not from the goal:

80% or more reads maximum, 50% high, 25% moderate, below that basic. Reliability currently counts an always-on server from the answer to question 4, before any server is checked.

Notifications#

Notifications go through Apprise to Telegram, Discord, Slack, ntfy, email, Matrix and 100+ other services. Pick a service, fill in one or two fields and send a test, or paste Apprise addresses directly.

• Problems: disk almost full, account signed out, collection, copy or timestamp errors. On a sealed server, an opened SSH port or a login is a problem too.
• Changes: deleted, edited and missing messages in observed chats, grouped into one notification per check (every minute unless changed in Parameters).
• Completed tasks: history, exports and storage copies.
• Daily summary at the chosen hour, server time.

Notifications carry chat names and counts. Message excerpts are off by default; with them on, message text leaves this machine.

Your operator bot is a bot of your own from @BotFather that answers /status and /stats, and optionally /pause, /resume and /copy. Only the listed chat and Telegram user IDs can use it; conversation text stays in the workspace. Use a separate bot if another application already receives its commands. See notifications and operator bot.

Evidence and backups#

• Independent timestamps send only the SHA-256 of each signed checkpoint to RFC 3161 authorities and OpenTimestamps calendars, every 5 to 1,440 minutes. Anchor now runs a pass. See timestamps.
• More witnesses, each off until chosen: the newest drand round, Telegram's list of signed-in devices without IP addresses, and Cloudflare Gateway's log of the server's DNS queries. See optional records.
• Encrypted backup copies the journal, files, checkpoints and chat exports to S3-compatible storage (Wasabi, Amazon S3, Backblaze B2, Cloudflare R2, MinIO). Everything is encrypted on this machine first. Download encryption key and keep it apart: without it the copy cannot be read. Object Lock in Governance or Compliance mode keeps objects from deletion for a set number of days. See off-site copy.

Code check#

Checks whether the installed program matches a published version.

1. Enter a GitHub repository (the official one is filled in) and a tag, branch or commit.
2. Check now asks GitHub's API, through this workspace's route for outside requests, for that commit's file list. It compares the git blob ID of every measured program file with the commit. A Windows checkout with converted line endings still matches.
3. The result lists changed, extra and missing files (up to 50 of each) and is saved as a source.checked journal record.

The result counts as current only while the running program files are unchanged: check again after an update. No token is needed and only public repositories work; chats and credentials are not uploaded. A match identifies the code on disk. It is not hardware attestation; for that, see Phala Cloud.

Protection modes#

The switcher next to the version number shows the chosen mode and how many of the 18 protection layers are active, for example 🟠 Witnessed 9/18. Change mode in Extras → Protection level opens the choice. A mode describes a target and lists what is still missing; recording, signing and saved settings are the same in every mode.

The layers: every record signed and chained; a signed run receipt; attachments saved with SHA-256; signed checkpoints; rechecks; problem alerts; read-only witness access; a witness checking on schedule; RFC 3161 timestamps; OpenTimestamps proofs; a verified latest timestamp; an encrypted off-site copy; case details in reports; a matching code check; Telegram never seeing this machine's IP; outside requests through a proxy; Object Lock on the copy; a sealed server with provider records. A layer that is off has Set up, which opens its form. Choosing a lower mode asks for confirmation and deletes nothing.

More tools#

Extras → Independent capture: connect a separate browser or AyuGram recorder, pin its signing key, select capture options, start/pause, take snapshots and download verified signed archives. Each recorder has its own manual login, route, journal and key. Both connections start disabled. See the English Independent capture guide.

• Ask the archive: search saved observations, review the sources, then decide whether to send them to an AI model. See archive analysis and local OCR and transcription.
• Parameters: limits and pace of collection, rechecks, downloads, profiles, notifications and exports. Search by name, show Only changed values and prepare defaults as a draft with Restore defaults…. Save parameters applies the values from their next use, and each change is a journal record.
• Access: separate tokens for reviewers, analysts and operators, limited to chosen workspaces, chats and rights. See access.
• System log: what this process did since it started (connections, proxy changes, sign-ins, refusals, settings changes) with IP addresses hidden. Follow new lines keeps the newest line in view. Messages stay in the journal only.
• Integrations: the AI provider, read-only MCP connections and signed webhooks.
• Case Board: private team notes, bookmarks and slices next to the evidence. See Case Board.
• GitHub Actions capture in Exports: one chat captured from your fork. See sealed capture.