# Telegram Media Downloader — Photos, Videos & Files, No Login (`khadinakbar/telegram-media-downloader`) Actor Download photos, videos, voice notes, and stickers from public Telegram channels. Returns direct downloadable media URLs plus optional file save to Apify storage. No API key or login required. MCP-ready. - **URL**: https://apify.com/khadinakbar/telegram-media-downloader.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, MCP servers, Automation - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 media item extracteds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 **Download photos, videos, voice notes, and stickers from public Telegram channels — direct downloadable media URLs, with an optional one-click save to storage. No login, no API key, no phone number.** Point it at any public Telegram channel and get back a clean, structured list of every media item: the **direct CDN URL** you can download, the media type, dimensions, duration, file name/size, the caption it was posted with, and a link back to the source message. Flip on **Download files to storage** and the actor also fetches the bytes and saves each file to Apify storage, handing you a permanent download URL. Built for OSINT researchers, content archivists, ML-dataset builders, and marketers who want the *files* from a channel — not just the text. MCP-ready for AI agents. --- ### What you get | Field | Description | |---|---| | `media_type` | `photo`, `video`, `roundvideo`, `voice`, `sticker`, or `document` | | `media_url` | Direct downloadable CDN URL of the media file | | `thumbnail_url` | Poster/preview image (mainly videos) | | `file_name` / `file_size` | Original name and human-readable size (documents) | | `duration` | Playback length for videos and voice notes (`m:ss`) | | `caption` | Text the media was posted with | | `posted_at` | ISO 8601 timestamp of the source message | | `message_url` | Permanent link to the source post | | `requires_telegram_app` | `true` when the preview exposes no direct file (large videos, documents) | | `apify_download_url` | Permanent Apify storage URL of the saved file (download mode) | One record is emitted **per media item** — a 10-photo album becomes 10 rows. --- ### When to use this actor - **Archive a channel's media** — bulk-collect every photo and video a public channel has posted. - **Build image/video datasets** — pull a media corpus for ML training from open channels. - **Competitor / brand monitoring** — grab the creative assets a competitor's channel publishes. - **OSINT & research** — capture media evidence with source links and timestamps. **When NOT to use it:** for message text, reactions, links, and emails, use the sibling **[telegram-channel-scraper](https://apify.com/khadinakbar/telegram-channel-scraper)**. This actor is media-first. It also cannot reach private/invite-only channels or channels with public web preview disabled — those need a Telegram API (MTProto/bot) tool. --- ### Pricing (pay per event) | Event | Price | |---|---| | Actor start | $0.003 (per GB RAM, once per run) | | **Media item extracted** | **$0.005** per item (URL + metadata) | | File downloaded to storage | $0.005 per saved file (only when download mode is on) | A typical 50-item URL-only run costs **about $0.25 + start**. Turning on file download roughly doubles the per-item cost because the bytes are fetched and stored. Both pay-per-event and usage-based billing are available — pick whichever fits your job at run time. --- ### Input ```json { "channels": ["telegram", "durov"], "maxMediaPerChannel": 50, "mediaTypes": ["photo", "video", "roundvideo", "voice", "document"], "downloadFiles": false, "maxFileSizeMb": 25, "oldestMediaDate": "2024-01-01" } ```` - **channels** *(required)* — usernames, `@handles`, or `t.me` URLs. They're normalized automatically. - **maxMediaPerChannel** — cap per channel (default 50). Counts individual media. - **mediaTypes** — subset of `photo`, `video`, `roundvideo`, `voice`, `sticker`, `document`. `sticker` is off by default. - **downloadFiles** — when `true`, fetch the bytes and save each file to storage, returning `apify_download_url`. - **maxFileSizeMb** — skip downloading any single file larger than this (default 25 MB). Only applies in download mode. - **oldestMediaDate** — `YYYY-MM-DD` floor; pagination stops once older media is reached. #### Tip: which channels work? A channel works if its public web preview is on. Open `https://t.me/s/CHANNELNAME` in a browser — if you see posts, the actor can read it. If it's blank, the owner disabled public preview, and the actor returns a clear `channel_error` record explaining why (never a silent empty result). *** ### How it works The actor reads Telegram's **public web preview** at `t.me/s/` — the same server-rendered pages Telegram serves for link previews and search engines. No login, cookies, or API credentials are involved. It paginates backward through a channel's history (`?before=`), extracts the direct CDN URL for each media item, and optionally downloads the file. Requests run through Apify datacenter proxies by default; switch to residential only if you hit blocks. #### Honest limitations The public preview exposes **direct download URLs for photos, previewable videos/GIFs, voice notes, and stickers**. Large videos and document/file attachments render as preview cards only — the file itself is gated behind the Telegram app. Those items still appear in your results with full metadata and `requires_telegram_app: true`, so nothing is silently dropped. *** ### Output example ```json { "record_type": "media", "channel_username": "telegram", "message_id": "395", "message_url": "https://t.me/telegram/395", "posted_at": "2026-03-28T12:00:00+00:00", "media_type": "photo", "media_url": "https://cdn5.cdn-telegram.org/file/abc123.jpg", "thumbnail_url": null, "duration": null, "caption": "New feature rolling out today 🚀", "requires_telegram_app": false, "apify_download_url": null, "media_index": 0, "source_url": "https://t.me/s/telegram", "scraped_at": "2026-06-30T14:22:05.123Z" } ``` Two dataset views are provided: **Media** (browse every item) and **Downloaded files** (only items saved to storage). *** ### Use via API / MCP This actor is exposed in the Apify MCP server as `apify--telegram-media-downloader`, so AI agents (Claude, ChatGPT, Gemini) can call it directly: pass a channel, get structured media back. It's also callable from the standard Apify API and SDKs (JavaScript, Python). ```bash apify call khadinakbar/telegram-media-downloader \ --input='{"channels":["telegram"],"maxMediaPerChannel":20}' ``` *** ### Related actors - **[telegram-channel-scraper](https://apify.com/khadinakbar/telegram-channel-scraper)** — messages, view counts, reactions, links, and emails from public channels. *** ### Legal & compliance This actor collects only **publicly available** data from Telegram's public web preview — no login, no private content, no circumvention of access controls. You are responsible for using the output in compliance with Telegram's Terms of Service, applicable copyright, and data-protection laws (including GDPR/CCPA where relevant). Do not download or redistribute copyrighted media without permission. Use for lawful research, archival, and analysis only. # Actor input Schema ## `channels` (type: `array`): Public Telegram channels to pull media from. Accepts plain usernames, @handles, or full URLs (e.g. 'durov', '@telegram', 'https://t.me/telegram') — they are normalized automatically. Each channel must have its public web preview enabled (open https://t.me/s/USERNAME in a browser to check). NOT for private/invite-only channels or single message links. ## `maxMediaPerChannel` (type: `integer`): Maximum number of media items (photos, videos, etc.) to collect per channel before stopping. Counts individual media — an album of 10 photos counts as 10. Defaults to 50; set higher for bulk archival. Each collected item is billed at the media-extracted rate. ## `mediaTypes` (type: `array`): Which media types to collect. Allowed values: 'photo', 'video', 'roundvideo', 'voice', 'sticker', 'document'. Defaults to photo, video, roundvideo, voice, and document. Pass a subset to filter (e.g. \['photo'] for images only); 'sticker' is excluded by default because channels post many. ## `oldestMediaDate` (type: `string`): Only collect media from messages posted on or after this date. Use ISO format 'YYYY-MM-DD' (e.g. '2024-01-01'). Leave empty to collect the most recent media with no date floor. Pagination stops once messages older than this date are reached. ## `downloadFiles` (type: `boolean`): When true, the actor fetches each media file's bytes and saves them to this run's key-value store, returning a permanent Apify download URL in 'apify\_download\_url'. When false (default), only the direct media URL is returned (cheaper, faster). Files without a direct preview URL (large videos, documents) cannot be downloaded and are flagged. ## `maxFileSizeMb` (type: `integer`): Skip downloading any single file larger than this size, in megabytes, to protect compute and storage budget. Only applies when 'Download files to storage' is enabled. Defaults to 25 MB. Items skipped for size still appear in the dataset with their direct media URL. ## `proxyConfiguration` (type: `object`): Proxy settings used to reach Telegram. Defaults to Apify datacenter proxies, which are sufficient for the public t.me web preview. Use residential proxies only if datacenter IPs get blocked. Leave as default for normal use. ## Actor input object example ```json { "channels": [ "telegram", "durov" ], "maxMediaPerChannel": 50, "mediaTypes": [ "photo", "video", "roundvideo", "voice", "document" ], "oldestMediaDate": "2024-01-01", "downloadFiles": false, "maxFileSizeMb": 25, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `record_type` (type: `string`): 'media' for a media item, 'channel\_error', or 'run\_summary'. ## `channel_username` (type: `string`): Telegram channel username without the @ symbol. ## `posted_at` (type: `string`): ISO 8601 timestamp of the source message. ## `media_type` (type: `string`): photo, video, roundvideo, voice, sticker, or document. ## `media_url` (type: `string`): Direct downloadable CDN URL of the media file. ## `thumbnail_url` (type: `string`): Preview/poster image URL. ## `file_name` (type: `string`): Original file name for documents. ## `file_size` (type: `string`): Human-readable file size. ## `duration` (type: `string`): Playback length for videos and voice notes. ## `apify_download_url` (type: `string`): Permanent Apify storage URL of the saved file (downloadFiles mode). ## `message_url` (type: `string`): Permanent link to the source message on Telegram web. ## `channel_url` (type: `string`): Direct link to the Telegram channel. # 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 = { "channels": [ "telegram" ], "maxMediaPerChannel": 50, "mediaTypes": [ "photo", "video", "roundvideo", "voice", "document" ], "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/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 = { "channels": ["telegram"], "maxMediaPerChannel": 50, "mediaTypes": [ "photo", "video", "roundvideo", "voice", "document", ], "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/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 '{ "channels": [ "telegram" ], "maxMediaPerChannel": 50, "mediaTypes": [ "photo", "video", "roundvideo", "voice", "document" ], "proxyConfiguration": { "useApifyProxy": true } }' | apify call khadinakbar/telegram-media-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/telegram-media-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Media Downloader — Photos, Videos & Files, No Login", "description": "Download photos, videos, voice notes, and stickers from public Telegram channels. Returns direct downloadable media URLs plus optional file save to Apify storage. No API key or login required. MCP-ready.", "version": "0.1", "x-build-id": "43I6WkNr7tS26fSHg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~telegram-media-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~telegram-media-downloader/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~telegram-media-downloader/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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": [ "channels" ], "properties": { "channels": { "title": "Telegram channels", "type": "array", "description": "Public Telegram channels to pull media from. Accepts plain usernames, @handles, or full URLs (e.g. 'durov', '@telegram', 'https://t.me/telegram') — they are normalized automatically. Each channel must have its public web preview enabled (open https://t.me/s/USERNAME in a browser to check). NOT for private/invite-only channels or single message links.", "items": { "type": "string" } }, "maxMediaPerChannel": { "title": "Max media items per channel", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of media items (photos, videos, etc.) to collect per channel before stopping. Counts individual media — an album of 10 photos counts as 10. Defaults to 50; set higher for bulk archival. Each collected item is billed at the media-extracted rate.", "default": 50 }, "mediaTypes": { "title": "Media types to include", "type": "array", "description": "Which media types to collect. Allowed values: 'photo', 'video', 'roundvideo', 'voice', 'sticker', 'document'. Defaults to photo, video, roundvideo, voice, and document. Pass a subset to filter (e.g. ['photo'] for images only); 'sticker' is excluded by default because channels post many.", "default": [ "photo", "video", "roundvideo", "voice", "document" ], "items": { "type": "string" } }, "oldestMediaDate": { "title": "Oldest media date", "type": "string", "description": "Only collect media from messages posted on or after this date. Use ISO format 'YYYY-MM-DD' (e.g. '2024-01-01'). Leave empty to collect the most recent media with no date floor. Pagination stops once messages older than this date are reached." }, "downloadFiles": { "title": "Download files to storage", "type": "boolean", "description": "When true, the actor fetches each media file's bytes and saves them to this run's key-value store, returning a permanent Apify download URL in 'apify_download_url'. When false (default), only the direct media URL is returned (cheaper, faster). Files without a direct preview URL (large videos, documents) cannot be downloaded and are flagged.", "default": false }, "maxFileSizeMb": { "title": "Max file size to download (MB)", "minimum": 1, "maximum": 500, "type": "integer", "description": "Skip downloading any single file larger than this size, in megabytes, to protect compute and storage budget. Only applies when 'Download files to storage' is enabled. Defaults to 25 MB. Items skipped for size still appear in the dataset with their direct media URL.", "default": 25 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings used to reach Telegram. Defaults to Apify datacenter proxies, which are sufficient for the public t.me web preview. Use residential proxies only if datacenter IPs get blocked. Leave as default for normal use.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```