# Telegram Media Downloader (`automation-lab/telegram-media-downloader`) Actor Extract public Telegram channel/post media URLs, metadata, timestamps, views, and optional KVS downloads without login. - **URL**: https://apify.com/automation-lab/telegram-media-downloader.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media - **Stats:** 6 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Telegram Media Downloader Extract media URLs, message metadata, and optional downloadable files from public Telegram channels and public Telegram posts. Telegram Media Downloader is an Apify Actor for researchers, analysts, journalists, OSINT teams, and developers who need repeatable public Telegram media collection without maintaining custom parsers. It works with public `t.me/s/` archive pages and public `t.me//` post URLs. It does not log in, bypass private channels, or attempt to access Telegram content that is not publicly visible on the web. ### What does Telegram Media Downloader do? This Actor reads public Telegram web HTML and saves one dataset item per message. It extracts: - Channel handle and title - Message ID and canonical Telegram URL - Message text - Publish timestamp - View count when Telegram exposes it - Media type list - Source media URLs - Detailed media objects - Optional key-value-store download references - Skip reasons for unsupported or private pages ### Who is it for? #### OSINT and trust-and-safety analysts Archive public Telegram evidence with message URLs, timestamps, text, and attached media references. #### Journalists and researchers Collect public channel posts and media for reproducible research datasets. #### Brand monitoring teams Track public impersonation, scam, or announcement channels and export the media evidence. #### Developers and data engineers Use Apify datasets, API clients, webhooks, and integrations to pipe Telegram message media into downstream workflows. ### Why use this Telegram media extractor? - HTTP-first and lightweight: no browser needed for public Telegram HTML. - Public-only by design: no account credentials, cookies, or login bypass. - Export-friendly: every message becomes a stable dataset row. - Media-aware: photos, videos, documents, audio, and unknown CDN files are grouped per message. - Optional downloads: persist media during the same run when you need Apify storage copies. - Automation-ready: works with Apify API, schedules, webhooks, and integrations. ### Supported Telegram URLs Use public Telegram links such as: ```text https://t.me/s/telegram https://t.me/telegram/429 ```` The Actor accepts multiple start URLs in one run. ### Unsupported Telegram URLs The Actor intentionally skips: - Private channels - Invite-only group links - Login-only pages - Deleted posts - Pages blocked by Telegram access controls - Telegram account session/cookie workflows This keeps the Actor compliant with public-web extraction and avoids access-control bypass. ### Input options | Field | Type | Description | | --- | --- | --- | | `startUrls` | array | Public Telegram archive or post URLs. | | `maxMessages` | integer | Maximum message rows to save. | | `downloadFiles` | boolean | Save media files to key-value store when enabled. | | `mediaTypes` | array | Keep selected media types. | | `minDate` | string | Optional ISO earliest publish date. | | `maxDate` | string | Optional ISO latest publish date. | ### Example input ```json { "startUrls": [ { "url": "https://t.me/s/telegram" } ], "maxMessages": 100, "downloadFiles": false, "mediaTypes": ["photo", "video", "document", "audio"] } ``` ### Output data Each dataset item represents one public Telegram message. | Field | Description | | --- | --- | | `channelHandle` | Telegram public channel handle. | | `channelTitle` | Display name when available. | | `messageId` | Numeric Telegram message ID. | | `messageUrl` | Canonical message URL. | | `sourceUrl` | Input URL that produced the row. | | `text` | Message text. | | `publishedAt` | Message publish timestamp. | | `views` | Public view count when present. | | `mediaTypes` | Unique media types found on the message. | | `mediaCount` | Number of media objects saved in the row. | | `mediaUrls` | Direct source/CDN URLs detected in the public HTML. | | `media` | Detailed media objects with type, URL, extension, thumbnail, and KVS references. | | `downloaded` | Whether at least one file was downloaded to KVS. | | `skippedReason` | Why a source produced no public message. | | `scrapedAt` | Extraction timestamp. | ### Example output item ```json { "channelHandle": "telegram", "channelTitle": "Telegram News", "messageId": 429, "messageUrl": "https://t.me/telegram/429", "text": "Member Tags...", "publishedAt": "2026-03-02T17:33:34+00:00", "views": 1570000, "mediaTypes": ["video"], "mediaCount": 1, "mediaUrls": ["https://cdn1.telesco.pe/file/example.mp4?..."], "downloaded": false } ``` ### How much does it cost to download Telegram media? This Actor uses pay-per-event pricing. You are charged a small run start event and a per-message item event. Final live pricing is shown on the Apify Store pricing tab and may include tiered discounts. For cost control: - Start with `downloadFiles=false` if URLs are enough. - Keep `maxMessages` modest during testing. - Enable downloads only when you need stored file copies. - Use date filters to avoid collecting older posts you do not need. ### How to run the Actor 1. Open the Actor on Apify. 2. Paste public Telegram channel archive or post URLs. 3. Set `maxMessages`. 4. Choose media types. 5. Decide whether to download files to key-value store. 6. Start the run. 7. Export results from the dataset as JSON, CSV, Excel, XML, RSS, or HTML. ### Tips for best results - Prefer `https://t.me/s/` for channel archive collection. - Use single post URLs when you only need one message. - Keep media downloads off for discovery runs. - Re-run on schedules for public channels that post frequently. - Store the `messageUrl` in downstream systems so evidence remains traceable. ### Integrations Use Telegram Media Downloader with: - Apify datasets for CSV/Excel exports - Google Sheets exports - Webhooks for monitoring workflows - Make and Zapier automations - Data warehouses via Apify API - Slack/Discord alerts for new public media evidence ### API usage: Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/telegram-media-downloader').call({ startUrls: [{ url: 'https://t.me/s/telegram' }], maxMessages: 100, downloadFiles: false }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` ### API usage: Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/telegram-media-downloader').call(run_input={ 'startUrls': [{'url': 'https://t.me/s/telegram'}], 'maxMessages': 100, 'downloadFiles': False, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items[0]) ``` ### API usage: cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~telegram-media-downloader/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"startUrls":[{"url":"https://t.me/s/telegram"}],"maxMessages":100}' ``` ### MCP usage Use the Apify MCP server with: ```text https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader ``` Add it to Claude Code: ```bash claude mcp add apify-telegram-media https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader ``` Claude Desktop JSON config example: ```json { "mcpServers": { "apify-telegram-media": { "url": "https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader" } } } ``` Example prompts: - "Run Telegram Media Downloader for this public channel and summarize posts with videos." - "Extract public Telegram media URLs from this message and return CSV-ready rows." - "Monitor this public Telegram archive weekly and alert me when new documents appear." ### Public-only legality note This Actor is designed for public Telegram pages that anyone can access in a browser without logging in. You are responsible for using the extracted data lawfully, respecting copyright, privacy, and platform rules, and avoiding collection of private or restricted content. ### FAQ #### Can this Actor access private Telegram channels? No. It only extracts content visible on public Telegram web pages without login. #### Should I enable file downloads? Enable `downloadFiles` when you need durable Apify storage copies. Keep it off when CDN URLs and metadata are enough. ### Troubleshooting: no rows returned Check that the URL is public and uses `t.me`. If the channel requires joining, logging in, an invite link, or an app-only flow, the Actor cannot access it. ### Troubleshooting: media URL expired Telegram CDN URLs can be temporary. If you need durable copies, enable `downloadFiles` so the Actor stores media files in the run key-value store during extraction. ### Related scrapers Related Automation Lab actors: - https://apify.com/automation-lab/telegram-media-downloader - https://apify.com/automation-lab/threads-post-media-downloader - https://apify.com/automation-lab/tumblr-media-downloader ### Changelog #### 0.1 Initial public Telegram channel/post media extraction with optional KVS downloads. ### Limits The Actor reads public Telegram web pages and paginates public channel archives. It does not use the Telegram API and does not authenticate. ### Data quality notes Telegram can change public HTML markup. If a message has unusual media markup, the Actor still saves text and metadata when available and leaves media arrays empty if no public URL is found. ### Privacy and compliance Do not use this Actor to collect or redistribute private content. Keep datasets only as long as needed for your workflow. ### Support If a public Telegram URL does not work, share the public URL, run ID, and expected result so the extractor can be adjusted to Telegram's current markup. # Actor input Schema ## `startUrls` (type: `array`): Public t.me URLs to scrape. Use channel archives like https://t.me/s/telegram or public post URLs like https://t.me/telegram/429. Private channels and login-only posts are not supported. ## `maxMessages` (type: `integer`): Maximum Telegram message records to save across all start URLs. ## `downloadFiles` (type: `boolean`): When enabled, media files are downloaded during the run and saved to Apify key-value store. Leave disabled if you only need CDN/source URLs. ## `mediaTypes` (type: `array`): Filter media attached to messages. Message metadata is still saved even if no selected media type is found. ## `minDate` (type: `string`): Optional ISO date/time. Messages older than this are skipped after extraction. ## `maxDate` (type: `string`): Optional ISO date/time. Messages newer than this are skipped after extraction. ## Actor input object example ```json { "startUrls": [ { "url": "https://t.me/s/telegram" } ], "maxMessages": 20, "downloadFiles": false, "mediaTypes": [ "photo", "video", "document", "audio" ] } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://t.me/s/telegram" } ], "maxMessages": 20, "downloadFiles": false, "mediaTypes": [ "photo", "video", "document", "audio" ] }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/telegram-media-downloader").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://t.me/s/telegram" }], "maxMessages": 20, "downloadFiles": False, "mediaTypes": [ "photo", "video", "document", "audio", ], } # Run the Actor and wait for it to finish run = client.actor("automation-lab/telegram-media-downloader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ { "url": "https://t.me/s/telegram" } ], "maxMessages": 20, "downloadFiles": false, "mediaTypes": [ "photo", "video", "document", "audio" ] }' | apify call automation-lab/telegram-media-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Media Downloader", "description": "Extract public Telegram channel/post media URLs, metadata, timestamps, views, and optional KVS downloads without login.", "version": "0.1", "x-build-id": "cGMxD3npwUmSsQXOd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~telegram-media-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-telegram-media-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~telegram-media-downloader/runs": { "post": { "operationId": "runs-sync-automation-lab-telegram-media-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~telegram-media-downloader/run-sync": { "post": { "operationId": "run-sync-automation-lab-telegram-media-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "startUrls" ], "properties": { "startUrls": { "title": "Telegram URLs", "type": "array", "description": "Public t.me URLs to scrape. Use channel archives like https://t.me/s/telegram or public post URLs like https://t.me/telegram/429. Private channels and login-only posts are not supported.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxMessages": { "title": "Maximum messages", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum Telegram message records to save across all start URLs.", "default": 20 }, "downloadFiles": { "title": "Download media files to key-value store", "type": "boolean", "description": "When enabled, media files are downloaded during the run and saved to Apify key-value store. Leave disabled if you only need CDN/source URLs.", "default": false }, "mediaTypes": { "title": "Media types to keep", "uniqueItems": true, "type": "array", "description": "Filter media attached to messages. Message metadata is still saved even if no selected media type is found.", "items": { "type": "string", "enum": [ "photo", "video", "document", "audio", "link", "unknown" ], "enumTitles": [ "Photos", "Videos", "Documents", "Audio", "Links", "Unknown" ] }, "default": [ "photo", "video", "document", "audio", "link", "unknown" ] }, "minDate": { "title": "Earliest message date", "type": "string", "description": "Optional ISO date/time. Messages older than this are skipped after extraction." }, "maxDate": { "title": "Latest message date", "type": "string", "description": "Optional ISO date/time. Messages newer than this are skipped after extraction." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```