Repository / docs/EPHEMERAL-MEDIA.md
Self-destructing media in the API journal
TgWitness / Documentation · Collection
The API collector saves available photos, videos, voice messages and files with
ttl_seconds through a dedicated priority-zero worker. It starts independently
of ordinary attachments and the messages-first history setting. The default
Include self-destructing media from excluded types setting bypasses type and duration
exclusions, while retaining configured file-size ceilings, disk reserves, serial
Telegram RPCs and full FloodWait deadlines. It does not turn metadata-only or
hash-only capture into a file download. Turn the setting off to apply ordinary
type rules.
When it sets a rule aside, the signed message records it in
media_capture.rule_override: the rule (type_not_collected, duration_limit) and the
limits that still applied.
The signed message observation retains the original Telegram media descriptor,
TTL and availability. A positive TTL is distinguished from Telegram's
0x7FFFFFFF view-once value; a chat's ttl_period is recorded as the chat's
auto-delete setting. The saved file is content-addressed by
SHA-256, with its size and reference to the signed message observation.
media.savedwithephemeral_media.outcome=savedmeans bytes were preserved.- An absent or empty photo/document with a positive TTL produces
media.skippedwithoutcome=unavailableandavailability=unavailable_at_observation. This records the self-destructing-media marker supplied by Telegram, not why the file disappeared or whether anyone viewed it. - Policy exclusions, unknown/excessive size, download errors and cancellation retain an explicit not-saved outcome and a warning that Telegram may not offer the media again. Transient failures retain the normal retry outcome.
- Offline intervals remain
coverage.gaprecords. They do not invent unseen media, its content or its time of delivery.
Downloads use the original observed descriptor without an initial message recheck. If Telegram rejects an expired file reference, a refresh must identify the same attachment; an absent or changed attachment is never substituted.
The API client's request boundary rejects message-history, message-content, discussion, mention, reaction and story read acknowledgments, including wrapped and batched requests. This does not control another signed-in device or the official Web/Desktop client. Neither a preserved file nor the absence of a collector read receipt proves that the human recipient viewed or did not view it. Reports explicitly retain that distinction.
This priority worker belongs to live monitoring and the single-chat journal. Account-wide exports retain their separate configured attachment processing; official-client capture remains limited to what the official UI exposes. Retrieval works while Telegram still serves the media.
Telegram documents the independent content read acknowledgment and history read acknowledgment, and the optional media/TTL fields for photos and documents.