TgWitness / Documentation

What has been tested →

Reference / Collect

Telegram Investigation Mode & Account Scope

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

TgWitness / Documentation

Investigation

Follow a case across channels, groups, private chats and bots, from initial acquisition to a cited timeline and verifiable handoff. The interactive website version is at /docs/cases/; preview instructions.

On this page

Worked case: a destination changes across four conversations#

An announcement points to a bot. An operations group discusses a new payment destination, and the bot's keyboard displays it. The announcement is edited, a private follow-up repeats the destination, and a group message disappears.

The questions are: what was observed before and after the change, which Telegram accounts posted each item, where the destination appeared, which attachment bytes were preserved, and what intervals remain unknown?

All names, IDs, times and journal references in this example are fictional. The workflow uses current features; the case map is an illustration, not an automatic graph generated by the application.

Flow diagramChannels → Workspace journal; Groups → Workspace journal; Private chats → Workspace journal; Bots → Workspace journal; Workspace journal → Search all sources; Workspace journal → People profiles with record references; Workspace journal → Saved versions and attachment receipts; Search all sources → Analyst timeline and source register; People profiles with record references → Analyst timeline and source register; Saved versions and attachment receipts → Analyst timeline and source register; Workspace journal → Signed evidence ZIP; Analyst timeline and source register → Case handoff with separately verified artifacts; Signed evidence ZIP → Case handoff with separately verified artifactsChannelsGroupsPrivate chatsBotsWorkspace journalSearch all sourcesPeople profiles withrecord referencesSaved versions andattachment receiptsSigned evidence ZIPAnalyst timeline andsource registerCase handoff withseparately verifiedartifacts
Diagram as text
  1. Channels → Workspace journal
  2. Groups → Workspace journal
  3. Private chats → Workspace journal
  4. Bots → Workspace journal
  5. Workspace journal → Search all sources
  6. Workspace journal → People profiles with record references
  7. Workspace journal → Saved versions and attachment receipts
  8. Search all sources → Analyst timeline and source register
  9. People profiles with record references → Analyst timeline and source register
  10. Saved versions and attachment receipts → Analyst timeline and source register
  11. Workspace journal → Signed evidence ZIP
  12. Analyst timeline and source register → Case handoff with separately verified artifacts
  13. Signed evidence ZIP → Case handoff with separately verified artifacts

1. Define the case and collect the whole account#

  1. Connect the collecting account in its own workspace. In Case Board or your case register, record the case reference, account ID, workspace and observation start. Retain the trusted signing-key fingerprint independently.
  2. For a dedicated collecting account, open More tools → Sources → Scope → Investigation mode. The preset selects Whole account, channels/groups/private chats/bots, own actions, source profiles and the latest 200 visible messages for newly discovered sources. Review it, press Save scope, and complete the scope confirmation. Main accounts use selected chats or a folder; whole-account collection is available to accounts marked for investigation.
  3. Load chats and compare the sources with the account's dialog list. Check exclusions. More tools → Parameters → Chats read from the account's list defaults to 1,000 and allows up to 20,000. Sources beyond the list limit are added when they become active. Record what was actually enumerated.
  4. In More tools → Sources → Recording, select All visible activity and save the monitoring settings. Review attachment types/limits and free disk space.
  5. Start observation. Validate a controlled new message, edit and deletion, then retain the test references and any failures.

Whole-account scope records account-visible activity within the saved settings, in the chats the account has joined. Secret Chats are recorded by the Secret Chat module, and existing conversations are backfilled through History. See collection scope.

2. Inventory every source and acquire historical context#

Keep a source register with one row per chat:

Field Record
Identity Workspace, account ID, numeric chat ID, title and type
Visibility Membership/role, access confirmed or unconfirmed, exclusions
Live capture Start time, selected event types and later policy changes
Journal history Snapshot requested/completed, limit, time and record references
Full history Signed per-chat export filename, boundary and completion/failure
Attachments Completed media receipts, hashes, sizes and skipped/failed outcomes
Coverage Outages, incomplete intake, FloodWait, unavailable messages and other gaps

Use the right acquisition for each source:

  • Load full history in More tools → Sources → Chats in scope loads available past messages from enabled sources into the workspace journal. It supports pause/resume and a signed progress report. See history acquisition.
  • History snapshot saves recent visible messages into the observation journal. Its default maximum is 500; More tools → Parameters → Largest history snapshot can raise that to 10,000. These are current history observations, not reconstructed edits.
  • Exports → Capture or export one chat → Export full chat, or Chats → Export chat, fetches the currently visible history of one chat into a separate signed chat.json / chat.html bundle. Repeat for the case's sources and retain each result.
  • When a new chat or bot appears can save its profile and up to 1,000 recent messages; Investigation mode selects 200. Existing chats do not receive that intake retroactively when the mode is enabled.
  • Download visible attachments preserves bytes under the configured policy. Require a completed media.saved receipt with SHA-256 and byte count. A queued job, thumbnail or filename is not the preserved attachment.

A full chat export does not populate the journal or people profiles with all its messages. Use Load full history or bounded journal snapshots for history you need to analyze inside TgWitness. Review the enabled source list before starting a history run. Neither route recovers material Telegram no longer returns.

3. Preserve the evolving case and deliberate interactions#

Star active case chats as priority sources. Review recheck intervals, continued catch-up and media outcomes. Keep the collector observing while using the account. Use Chats → Profile → Save profile now to retain source metadata such as descriptions and bot commands. This is separate from people profiles derived from saved messages.

Where the case involves following a source or interacting with a bot:

  1. Open Telegram link → Save preview records the supplied link and returned preview before an action.
  2. Join / open and observe performs the join/open, and sends a bot's start parameter when supplied. A join request awaiting approval is recorded as pending.
  3. Panel-issued text replies and supported button presses retain interaction.requested and interaction.result. Callback receipts can retain returned popup text, alert state and URL.

Those are real account actions. Callback presses in another Telegram app are not visible to the collector, although resulting messages or edits may be. The mini-client does not perform web-app, payment, phone or location workflows. For exact behavior, see panel interactions.

4. Connect observations across chats#

In Journal, select All sources and search recorded content. Open matching records and retain the workspace, chat, message ID, sequence and record hash.

In a relevant chat, open People → Turn on profiles and inspect a person:

  • Names/usernames observed over time and the numeric Telegram ID.
  • Reply relationships with source-record references.
  • Also in… other chats in this workspace journal where that ID wrote.
  • Activity, edits/deletions and mentioned wallets, phones, usernames and links.
  • Saved avatar metadata and similar cached avatars, with their separate origin.

Open the cited records before using a derived profile in a finding. Profiles cover people with saved messages, not every member of the group. More tools → Parameters → Records cited per fact limits the reference list, not the underlying activity count. Mentions and avatar similarity are leads; ownership and identity rest on numeric IDs and attributed senders.

The signed dossier separates encoder hints from forwarded and reused files into clients.forwarded and clients.reused. Such files do not contribute to clients.observed or the media_timing.pre_existing list. A reused file means the same Telegram document ID was observed in a different message earlier in this journal, within the reader's permitted chats. Its first observed record is cited; another observation or edit of the same message is not a reuse.

The dossier's paid_reactions section retains the latest available Stars leaderboard for each listed message, with source records and anonymous flags. These are snapshot counts, not sums of additional payments or a complete list of people who reacted. A snapshot without a leaderboard supplies no replacement list. The section reports omitted messages when its display limit is reached.

Watchlists and indicator exports inspect button labels, URLs, copy text, inline queries and callback bytes that decode as valid UTF-8. Invalid or oversized callback encodings are skipped by text extraction; the original bytes remain in the saved record. Existing watchlists need a rescan to inspect older records with these additional fields. Inspection does not press the button.

In the worked example:

Link Records Supported observation
Same sender account Group #146 and private follow-up #205 Both supply Telegram sender ID 71001
Same destination #146, bot keyboard #173, channel edit #188, private message #205 All contain pay.example.invalid/new; a repeated destination links the material
Same saved file Completed media receipts #151 and #209 The full SHA-256 values agree for the preserved bytes
Channel attribution #101 and #188 Do not attribute a channel post to user 71001 without an attributed sender

Compare attachment hashes and their associated message references, and keep account timelines grouped by the Telegram IDs supplied in those records.

Keep the team's working notes on Case Board: bookmark the records you rely on, such as #146, #188 and #205, highlight the exact destination string, and save a slice of every recorded action between two records or in a time range. Notes and statuses retain the team's review in their own signed history, separately identifiable from the source observations.

5. Build the cross-chat timeline#

Use saved versions in Chats and their Journal record #… links. In Journal, combine All sources with Edits, Deletions and Coverage. Keep both source_at, where supplied, and observed_at.

Illustrative observation time Reference Observation
09:00 Channel #101 Original destination captured
09:12 Group #146; media #151 New destination posted; file download completed
09:16 Bot #173 Keyboard points to the new destination
09:20 Channel #188 Announcement edited; both saved versions remain
09:24 Private #205; media #209 Same sender ID repeats destination; same file bytes preserved
09:28 Group #231 Deletion notice received; deleter and exact deletion time unknown

Other records occur between these example references. Sequence numbers order observations; history snapshots can contain older source dates and arrive later than live events. Distinguish snapshots, recovered messages, deletion notices and missing-on-recheck outcomes. Mark coverage gaps as unknown intervals. Later history acquisition does not retroactively establish uninterrupted observation.

6. Add account perspectives without losing their origin#

Use a separate workspace for every distinct account and repeat its inventory. Keep account ID, role, signing-key fingerprint and source references with every comparison. Message numbers are not global identifiers across chats/accounts.

Case Board keeps source-linked notes and collections within each workspace. The group screen reviews account status together and can bundle separate workspace exports. Correlate those sources in your case notes or analysis tools; each journal retains its own origin and signing key. A global search or merged cross-workspace timeline is not generated. Multi-account export of one channel/supergroup acquires that chat's history using the eligible accounts.

For longer work, retain boundaries with an independent witness. Use controlled delivery checks to qualify each account's capture path and visibility.

Media recurrence and forwarding sources#

Evidence reports compare Telegram document IDs and SHA-256 hashes from saved-file records separately. They show distinct messages, chats and the first and last retained occurrence, with an expandable observation timeline in HTML. Repeated snapshots or edits of the same message do not increase an occurrence count for the same key. A different file in an edited message retains its own occurrence.

"First observed" follows journal sequence within the report selection. It does not claim the earliest publication on Telegram. Document IDs identify Telegram documents; SHA-256 compares saved bytes. Matching 64-bit dHashes of different saved images are shown as visual leads; this comparison uses equal hashes, not a nearest-neighbor search. Image bytes must match their saved SHA-256 before dHash analysis; files over 64 MiB and images over 40 million pixels are skipped.

Forward-source summaries count distinct destination messages. Header peer IDs, hidden names, post-author signatures and Saved Messages context stay separate. People-profile JSON includes each sender's sources; channel posts also appear in the chat-level summary. A named source without a peer ID is a text grouping, not an identified person. Imported-chat headers remain marked as imported.

Non-compact evidence ZIPs include media-repeats.json, forward-sources.json and observed-sources.gexf, protected by the archive manifest. The GEXF 1.3 graph has typed forwarded_from and recommended edges. Arrows run from the observed chat to the referenced peer. Recommendation weights count retained recommendation observations; forward weights count distinct messages. Hidden names and imported headers do not create identity edges. No graph operation resolves profiles or calls Telegram. Edge metadata includes source sequences and hashes.

The summaries follow the report's selection; the evidence ZIP still contains the complete signed journal. A selection containing only message events compares document IDs; saved-byte and image comparisons require saved-file events in the selected stream. The current cloud-message selection excludes media.saved. Limits are explicit: 200,000 retained key/message occurrences per analysis, 100,000 media keys, 20 report groups, 100 chronology references per group and 1,000 exported graph edges. When a comparison cap is reached, results show omitted occurrences and counts become lower bounds. Chronology and graph display limits are reported separately. Compact ZIPs omit these derived summaries. The signed source records remain unchanged.

7. Assemble and verify the case handoff#

Keep these together in an analyst-assembled case directory:

Material Purpose
Case notes and source register Question, collection policy, access/role, findings, alternate explanations and gaps
Timeline Both times and workspace/chat/message/sequence references for each entry
Case Board export and slices, if used Source-linked bookmarks, quotes, team notes, collections, revision history and selected records checked against the evidence ZIP
Signed evidence ZIP per workspace Complete recorded journal, manifest and included preserved media; panel filters do not narrow the journal export
Separately signed people-profile files Derived references checked against the matching workspace evidence
Signed full chat exports Current visible-history acquisition, separate from the observation journal
Trusted fingerprints, TSA root certificates and earlier checkpoints Key identity, external time of the last record and retained journal boundaries
Witness artifacts, if configured Separate journal, signed posts and witness fingerprint
Verification results and delivered-file hashes What was checked, which bytes were transferred and to whom

From a trusted installation, with filenames and each workspace's actual fingerprint:

python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidence
python -m tgwitness.verify profiles-operations.json --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --evidence evidence.zip
python -m tgwitness.verify history-channel.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256
python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256

--require evidence exits with code 2 unless the fingerprint matches and external time from a third party covers the last record; the checkpoint is a supporting check.

Retain the actual verification results and original artifacts. Export workspace notes from Case Board alongside the cited source material. Assemble cross-workspace findings in the top-level case directory; each TgWitness artifact has its own signature and verification procedure.

Adapt the investigation#

Case Trace Deliver
Bot-driven order/payment dispute Entry announcement → saved link preview → bot start parameter → message and keyboard versions → panel callback receipts → private/group follow-up Observed offer/response timeline and verified sources; payment confirmation comes from the payment record
Removed messages after an incident All affected chats → saved originals/edits → deletion or missing-on-recheck outcomes → preserved media → coverage and other account perspectives Preserved versions and explicit unknown intervals; no invented deletion actor
A participant changes names across chats Numeric sender ID → name/username history → replies → other observed chats → cited destinations/files A Telegram-account activity timeline with links to its source records

Collection reference · People-profile verification · Evidence handoff · Completed validation