# TgWitness Features & Telegram Collection Scope

Canonical page: https://phishdestroy.io/tgwitness/docs/reference/features/

Review implemented TgWitness collection, multi-account workflows and signed exports, with the platform support and qualification of each feature.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/llms.txt)

The current collection model, multi-account workflows, exports and operational boundaries of TgWitness.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Project reference](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Project reference](https://phishdestroy.io/tgwitness/assets/chapter-project.svg?v=f8e31208f561)

TgWitness preserves Telegram conversations accessible to connected accounts, records observed changes and prepares verifiable exports. This reference describes the collection model, current workflows and their boundaries.

**On this page**

- [Standalone application](https://phishdestroy.io/tgwitness/docs/reference/features/#standalone-application)
- [Shared investigations](https://phishdestroy.io/tgwitness/docs/reference/features/#shared-investigations)
- [Archive tools](https://phishdestroy.io/tgwitness/docs/reference/features/#archive-tools)
- [Optional extras](https://phishdestroy.io/tgwitness/docs/reference/features/#optional-extras)
- [Protocol and private sources](https://phishdestroy.io/tgwitness/docs/reference/features/#protocol-and-private-sources)
- [Multiple accounts](https://phishdestroy.io/tgwitness/docs/reference/features/#multiple-accounts)
- [Capture and attribution](https://phishdestroy.io/tgwitness/docs/reference/features/#capture-and-attribution)
- [Capacity and Telegram limits](https://phishdestroy.io/tgwitness/docs/reference/features/#capacity-and-telegram-limits)
- [Reliability and recovery](https://phishdestroy.io/tgwitness/docs/reference/features/#reliability-and-recovery)
- [Evidence model](https://phishdestroy.io/tgwitness/docs/reference/features/#evidence-model)
- [Export, deployment and handoff](https://phishdestroy.io/tgwitness/docs/reference/features/#export-deployment-and-handoff)
- [Stable release criteria](https://phishdestroy.io/tgwitness/docs/reference/features/#stable-release-criteria)

## Standalone application

TgWitness has its own installation, data directory, and release lifecycle. The bundled web interface handles setup and review; exported records can be used independently.

The operator connects their accounts, chooses sources visible to each, and obtains a saved observation journal. The panel exposes content, saved changes, observation provenance and known gaps. Another investigator can verify the exported material.

The panel distinguishes account authorization, access to a source, collector activity and recorded coverage. Review those states together when assessing an interval with few messages or a connection problem.

## Shared investigations

An administrator can issue [access tokens](https://phishdestroy.io/tgwitness/docs/reference/access/) scoped to workspaces and individual chats, with per-action permissions, IP restrictions, expiry, sign-in limits and session control. A read-only reviewer can inspect a case without receiving Telegram authorization or the main panel key. Chat-limited access stays separate from account-wide settings and full-journal exports.

Automatic MTProxy maintains working Telegram routes from four public sources or an operator catalog. [IP modes](https://phishdestroy.io/tgwitness/docs/reference/connection/#ip-modes) determine whether failure must wait for another proxy or may use an explicitly permitted direct route. External HTTP requests have a separate route and off switch.

## Archive tools

[History acquisition](https://phishdestroy.io/tgwitness/docs/reference/history/), [archive search and analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/), [read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/), [local OCR/transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/) and [outgoing webhooks](https://phishdestroy.io/tgwitness/docs/reference/webhooks/) have been included since 0.7.1. Analytical reports and recognized text stay separate from captured events.

[Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/) adds source-linked bookmarks, quotes, notes and collections within a workspace. The [report constructor](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) selects material, sections and one of eight designs for supported HTML/PDF exports.

## Optional extras

Everyday setup is account → sources → observation. **More tools → Extras** is a separate destination for independent capture, storage, goal and protection level, notifications, evidence and backups, an always-on server, a Telegram witness bot and a code check. Each states its availability and requirements before showing settings. Choosing a card opens instructions; it does not enroll or start a service.

Bot setup has three steps: create read-only access, choose publication settings, and launch on the witness host. Network and publication options, existing connections and verification commands are disclosed on demand. Downloaded configuration is distinct from a running witness. Switching extras retains the draft; account changes and locking clear the temporary token and form. The built-in guide includes launch instructions. [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md), opened from Exports, launches a pinned collector from your fork, captures one chat and produces an encrypted handoff with workflow provenance.

## Protocol and private sources

**MTProto is Telegram's protocol; Telethon is the Python library TgWitness uses to speak MTProto.** They are not alternative connection methods. Collection uses MTProto; the optional witness publishes signed checks through the Bot API.

Each workspace has its own authorized client and account update stream. TgWitness selects observations from configured sources and makes separate explicit requests for functions such as history snapshots and media downloads.

A private source needs no public username. Telegram peer type and numeric ID are the identifiers; titles and usernames can change. Access depends on existing membership and permissions. TgWitness does not automatically join sources or bypass join approval. An access hash from another account is not a universal access token.

The collection model must account for pre-join hidden history, participant/admin roles, session revocation, removal or changed permissions, group-to-supergroup migration, topics/forums, linked discussions, channel identities and unavailable attachments. Not every combination has been qualified live.

Source visibility is checked at collector start. Missing a source from the bounded dialog result means **access unconfirmed**, not proven removal. One unavailable source does not prevent observing other accessible sources. Never put invitation links or real sessions in public fixtures.

## Multiple accounts

The panel supports any number of **workspaces**, each with its own:

- Authorization, encrypted vault and connection route.
- SQLite journal and Ed25519 signing identity.
- Selected sources, media queue and capture settings.
- Observation state, errors, checkpoints and exports.

Switching the displayed workspace does not stop another collector. Duplicate account authorization across workspaces is rejected. A journal already bound to one Telegram account cannot be reassigned to another; reconnecting the same account is allowed. This preserves account identity and the relevant message-ID scope.

The application sets no fixed workspace count. Each workspace runs its own collector tasks for connection monitoring, media downloads, rechecks and new-chat intake within a shared Python process and event loop. Throughput depends on the workload. For process isolation, use separate installations, ports and data directories.

Assign each account sources it can access. Different accounts may observe the same group, but their observations remain separate and retain their origin. Two accounts on one operator-controlled machine are not two independent witnesses. **Export group** bundles the separately signed workspace ZIPs with a signed file list containing their workspace IDs, hashes and signing-key fingerprints. Each journal retains its own boundary. Build a combined cross-workspace timeline in case notes or analysis tools, retaining those source references.

## Capture and attribution

Sources provides per-account switches for new messages, edits, deletions, reactions and membership. Presets retain either all categories or messages/edits/deletions. The policy applies to the workspace's selected groups, survives restart, and is signed with before/after changes. Defaults preserve all categories. Turning a category off does not remove old records; turning it back on does not reconstruct missed events. Operational records, other group service events and explicit history snapshots are separate. Captured Telegram objects may retain embedded metadata regardless of the separate-update switches. There are no per-group category overrides yet.

| Material | Captured now | Boundary |
| --- | --- | --- |
| Message | Text, peer/message IDs, sender metadata, replies and original update envelope | Preserved as an account-visible observation signed by the collector |
| Edit | New observed version, earlier captured versions, reception time and supplied edit date | Message updates and available admin-log entries retain their respective attribution fields |
| Deletion | Telegram notification, reception time and previously captured content | Actor and source action time are retained when supplied by a separate admin-log record |
| Account-level deletion notice | Original notice; resolved records include the saved chat and correlation method | Requires exactly one previously saved private-chat or ordinary-group match in scope; other IDs stay `deletion.unscoped`. Channel and supergroup IDs are excluded from this correlation |
| Reaction | Delivered counters and visible recent identities | A complete available reactor list requires separate queries; channels may hide identities |
| Membership | Service messages and delivered participant updates | Visibility depends on role and chat type; membership is reported from delivered events |
| Admin actions | Relevant delivered updates and an admin-log snapshot in channel/supergroup chat exports | The export reads the log when available to the exporting admin account |
| Attachment | Original version descriptor, downloaded bytes/SHA-256 and attempt outcomes | The original version stays; a later version is never substituted |
| History | Explicit snapshot of current visible messages | Live recording keeps earlier versions and deletion notices |
| Collector process | Start/stop, heartbeat, errors, settings, scope and signed run receipt | Local inventory; GitHub and TDX add [independent environment checks](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) |

The interface names the account supplied in the source event and retains observed names and usernames. When the event omits its actor, the report leaves that field unspecified.

## Capacity and Telegram limits

Capacity is sized per deployment. It depends on peak events per second, attachment volume and sizes, additional RPCs, active accounts, disk latency/free space, network conditions, Telegram limits, acceptable lag and queue depth.

Telegram distinguishes passive delivery from active short polling. Its update documentation describes additional `updates.getChannelDifference` calls for open channels/supergroups and recommends at most **ten simultaneously short-polled sources**. This applies to short polling; the number of selected groups is set separately.

| Mode | Purpose | Status |
| --- | --- | --- |
| Standard observation | Record delivered updates from selected sources | Implemented |
| Priority rechecks | Starred sources use their own configurable interval and take precedence in each bounded recheck pass | Implemented with history and message queries |

The priority star controls these rechecks. Additional `updates.getChannelDifference` short polling is not exposed as a separate user mode.

Arbitrary high-frequency polling, ignoring FloodWait or assuming linear capacity from extra accounts is not a valid sizing model. Default limits are the first 1,000 listed dialogs, up to 500 messages per history snapshot, 1–2,000 MiB per collected file by type, and 4 GiB uncompressed signed ZIP content; each is changed per workspace, file sizes under **More tools → Sources → Recording** and the others under **More tools → Parameters**. Exports have no fixed event-count cap. Browser fallback is bounded to 128 MiB by default; the streaming CLI has a configurable transfer limit, 5 GiB by default.

## Reliability and recovery

Implemented behavior includes SQLite WAL/synchronous transactions; atomic message and media-job writes; persistent jobs and retry delays; original-version descriptors; bounded retries; persisted media FloodWait; media downloads outside the text event's network wait; stable-prefix exports while later writes continue; atomic settings and audit records; preservation of working authorization after failed replacement login; isolation of a damaged additional workspace; explicit reconnect attempts; distinct authorization-loss reporting; and wall-clock change detection using a monotonic clock.

Account and channel pts/qts/seq are saved and resumed after a restart, and observed chats are rechecked periodically; see [evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#durable-collection-and-process-receipts-02). Saving the position periodically is not an atomic, lossless acknowledgement of journal acceptance.

Every process start records the previous head and offline boundary. Current history is not treated as gap repair. Telegram's difference retention is finite; `differenceTooLong` cannot reconstruct all vanished content. Irrecoverable gaps must remain explicit even if a later history snapshot succeeds.

## Evidence model

Each event records a sequence, local UTC observation time, source time when supplied, kind, source, actor when supplied, original payload, previous hash and signature. Message observations also retain collector account/run context.

The signed process receipt contains a random run ID; TgWitness/Python/OS/dependency versions; source-file SHA-256 values and aggregate fingerprint; initial account, scope and settings; UTC/monotonic readings; and the preceding journal head. Settings changes, start/stop and errors enter the same journal. Checkpoints are retained at startup, every five minutes while observing (changeable), and on orderly stop. A retained local checkpoint can detect rollback to an earlier journal prefix.

| Mechanism | What it establishes |
| --- | --- |
| File SHA-256 | Bytes match a known digest |
| Event hash chain | Record ordering/linkage relative to a known boundary |
| Ed25519 | Signature under a particular key |
| Independently retained checkpoint | Later material agrees with the retained boundary |
| Program-file measurement | Collector self-report about measured files |
| Valid independent TSA response | Existence of particular bytes by the TSA time under explicit trust assumptions |

RFC 3161 request preparation and response verification are implemented without OpenSSL. Evidence mode also submits checkpoint hashes to configured timestamp services. Retain and verify the authority's response to establish an independent time anchor. See [TIMESTAMP.md](https://phishdestroy.io/tgwitness/docs/reference/timestamp/).

Retain checkpoints independently, control access to signing keys, keep transfer records and verify exports with trusted software. The [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) explains how those checks complement one another and which trust assumptions apply.

## Export, deployment and handoff

A signed ZIP contains original JSONL, CSV, HTML, preserved attachments, hashes, a signed manifest and a convenience verifier. It covers one workspace and a fixed full journal prefix. Panel search filters do not silently remove records. Secret keys, tokens and Telegram sessions are excluded; original observations can still contain personal information and Telegram metadata.

Retain the ZIP digest, trusted fingerprint, checkpoint, process receipt and handoff record separately. Use a verifier from a trusted installation, rather than trusting executable code solely because it appears in the examined ZIP.

The browser interface ships locally without Node.js, CDNs or external fonts. One operator token controls the installation. Remote access needs HTTPS or an SSH tunnel. Native Python and container definitions are supplied, with service examples under [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md); executed platform checks are listed separately.

The default workspace uses the data root; additional workspaces use `profiles/<id>/`. Backup requires a stopped process and the complete data/key set. Evidence ZIPs are not application backups. Secrets can use an external master key for a new data directory; journal/media encryption is provided by the operator's disk/volume. See [CONNECTION-SECURITY.md](https://phishdestroy.io/tgwitness/docs/reference/connection/) and [OPERATIONS.md](https://phishdestroy.io/tgwitness/docs/reference/operations/).

## Stable release criteria

Before a stable release, qualify:

1. Real private groups, supergroups, forums and channels with member/admin roles and hidden/visible history, including login/2FA, revocation and access loss.
2. Controlled edits, deletions, reactions, membership and media against known actions.
3. Process/host crashes, disk failures/full disk, expired file references, FloodWait, network loss, corrupted files and database rollback.
4. Sustained multi-account use with measured lag, queues, memory and disk, including quiet and noisy sources together.
5. Interruption between MTProto state advancement and journal acceptance.
6. Clean installation on the intended OS/container matrix and verified backup restore.
7. Independent review of security, signatures and attribution/evidence claims.

Scoped panel access is described in [access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/). Since version 0.6, TgWitness supports the bounded single-account TData and account-file import described in [ACCOUNTS.md](https://phishdestroy.io/tgwitness/docs/reference/accounts/). Review Telegram API terms before publication. Research references and platform findings are in [RESEARCH.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/RESEARCH.md).
