Because documentation is cool.
The dedicated docs site is almost ready. In the meantime the FAQs below should cover the most common questions.
Because, you know, it's only just been released.
Trawlr requires Docker and Docker Compose, at least 4GB of RAM and enough disk space for your media downloads. The platform should run on any Linux server, WSL2, or macOS (it's been tested on Windows 11, Ubuntu LTS and deployed with Dokploy). You'll also need a valid Telegram API credentials from my.telegram.org. The required services are included in the docker compose file.
The default docker-compose.yml starts the eight required services:
Yes. Trawlr supports connecting multiple Telegram accounts simultaneously. Accounts are linked via the web UI under the Accounts section. You'll need the phone number, api_id, and api_hash for each account. These operate in Telegram's user account context.
The listener service is a long-running async process that maintains a persistent connection to Telegram. It captures events immediately as they occur and publishes them to RabbitMQ, where they are picked up by the processor for processing and storage.
FloodWait is a Telegram rate limit response. When a FloodWaitError occurs the affected account pauses for the cooldown period specified by Telegram. This does not affect receiving real time events. The account's FloodWait status is tracked in the database so the dashboard reflects when an account is temporarily rate-limited. To minimise FloodWait errors, distribute your high volume across multiple accounts.
Each downloaded file stores its SHA256 hash. If the same file is shared across multiple channels, Trawlr detects the duplicate and stores a reference to the original rather than saving another copy. This can reduce disk usage on instances monitoring channels that reshare the same media. Deduplication also uses Telegram's file_unique_id for cross-account deduplication. This feature can be toggled on or off in Settings.
Yes. You can enable automatic downloading for photos, videos and other files independently for each source. Your source priority settings determine its position in the download queue and you can set the number of concurrent download slots per account (up to 10).
Failed downloads are automatically retried up to 3 times with exponential backoff (unless you configure otherwise). If a download task gets stuck due to a container restart or otherwise, the scheduler runs a periodic recovery task that detects downloads stuck for more than 4 hours and resets them for retry. You can monitor download status and failures from the Downloads page in the dashboard.
Trawlr uses a structured query language similar to EQL/JQL. You can combine free-text search with field-based filters. Examples include:
text:[your text] - full-text search across message contentchannel:[name] - filter by source channel or groupsender:[username] - filter by message senderurl:[https://example.com] or domain:[example.com] - find messages containing the specified URL/Domainhas_media:[true/false] - only messages with attached mediatype:[photo/video/file] - filter for specific media typesdeleted:[true/false] - filter out deleted messages/li>
created:>7d - relative date filters also support absolute dates such as created:2026-01-01Operators include AND (implicit between terms), OR, NOT / - negation, and quoted "exact phrases".
Trawlr generates seven types of interactive network visualisations:
Trawlr saves media as a GUID (random unique identifier) by default. Trawlr also supports Timestamp (based on message date), Message ID (Telegram's message identifier), and File ID (Telegram's internal file identifier). All files retain their original extension regardless of the naming format chosen.
Check the getting started guide for a full walkthrough, or open an issue on GitHub.