# Telegram Media Downloader (`maximedupre/telegram-media-downloader`) Actor Download public Telegram photos, videos, and documents from post URLs, channels, groups, or @handles. Get media URLs, post text, dates, views, thumbnails, and source links in a clean Apify dataset. - **URL**: https://apify.com/maximedupre/telegram-media-downloader.md - **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community) - **Categories:** Social media, Videos, Automation - **Stats:** 6 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $4.45 / 1,000 telegram media items This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ### Get Telegram media URLs fast Telegram Media Downloader gets direct media URLs and post data from public [Telegram](https://telegram.org/) posts, channels, and groups. Add Telegram post links, channel links, `t.me/s` archive links, or `@handles`, then export photos, videos, documents, post text, dates, views, source links, and thumbnails to an Apify dataset. Use it when you need a clean Telegram media scraper for content review, research, backup, media tracking, or social media work. You do not need a Telegram login, cookies, or an API key. The Actor works with public Telegram pages only. ### What this Telegram media downloader does - Downloads public Telegram media links from single post URLs. - Scans recent public posts from channel or group targets. - Saves one dataset row per media item, so photos and videos are easy to sort, filter, and export. - Gets post text, post URL, channel handle, author name, date, views, media type, file extension, thumbnail URL, and scrape status. - Lets you filter for all media, videos, photos, or documents. - Can save clear status rows for private, missing, or empty targets so you can see what happened. ### Who it is for - Researchers who need Telegram post media with source links. - Social media teams that need Telegram videos or images in CSV, JSON, Excel, or through the Apify API. - Content teams that want to check recent media from public Telegram channels. - Developers who need simple Telegram media extraction for a workflow, webhook, or integration. ### How to run it 1. Paste one or more Telegram targets in **Telegram targets**. 2. For channel or group targets, set **Post limit per channel**. 3. Set **Total media item limit** if you want a small test run. 4. Choose media types: all media, videos, photos, or documents. 5. Start the Actor and open the dataset. For a quick first run, keep the default target and a small media limit. Post URLs process only that post. Channel and group URLs scan recent public posts up to your post limit. ### Input | Field | What to enter | | ----- | ------------- | | `targets` | Public Telegram post URLs, channel URLs, group URLs, `t.me/s` archive URLs, or `@handles`. | | `maxPostsPerChannel` | How many recent posts to inspect for each channel or group target. | | `maxMediaItems` | Optional cap for saved media rows across the run. | | `mediaTypes` | `all`, `video`, `photo`, or `document`. | | `includePostText` | Save visible post text with each media row. | | `includeThumbnails` | Save thumbnail URLs when Telegram shows them. | | `skipDuplicateMedia` | Skip the same media URL if it appears more than once. | | `includeFailedTargets` | Save status rows for targets that cannot return media. | ### Output Each media item is saved as its own row. This makes the output easy to use in spreadsheets, APIs, and automation tools. ```json { "rowType": "media", "target": "https://t.me/example/123", "postUrl": "https://t.me/example/123", "postId": "123", "channelHandle": "example", "authorName": "Example Channel", "postText": "Post text shown by Telegram", "postDate": "2026-05-20T10:00:00+00:00", "viewsText": "1.2K", "mediaUrl": "https://cdn4.telesco.pe/file/video.mp4", "mediaType": "video", "extension": "mp4", "thumbnailUrl": "https://cdn4.telesco.pe/file/thumb.jpg", "status": "ok" } ```` Rows can also have `rowType: "target-status"` when a target is private, missing, unsupported, or has no matching media and **Include failed targets** is turned on. ### Pricing This Actor uses pay-per-event pricing. You pay for each `telegram-media-item` saved to the dataset. The public price is `$4.45 per 1,000 media items`, plus the standard small Actor start charge shown by Apify before you run it. ### Limits and access This Actor works with public Telegram posts, channels, and groups. It does not use Telegram accounts, cookies, or API keys. Private Telegram links, deleted posts, and login-only content are not supported. Telegram may show less data for some posts. In those cases, the Actor saves the fields Telegram exposes and leaves the rest empty. ### FAQ #### Can I download media from private Telegram channels? No. This Actor is for public Telegram pages only. Private channels, private groups, and `/c/` links are skipped. #### Can I use channel handles instead of full URLs? Yes. You can use `@handle`, `https://t.me/handle`, or `https://t.me/s/handle`. #### Does it return files or media URLs? It returns direct media URLs and metadata in the dataset. You can export the rows or use the URLs in your own workflow. #### Can I get only Telegram videos? Yes. Set **Media types** to **Videos**. #### Why do some fields come back empty? Telegram does not show every field on every public page. For example, a photo may not have a quality value, and some posts may not show a timestamp field. ### Support Open an issue on the Actor page if a public Telegram target does not work as expected. Include the target URL, your input settings, and what output you expected. # Actor input Schema ## `targets` (type: `array`): Paste public Telegram post URLs, channel URLs, group URLs, t.me/s archive URLs, or @handles. Post URLs process one post; channel and group targets scan recent public posts. ## `maxPostsPerChannel` (type: `integer`): How many recent posts to check for each channel or group target. Post URL targets always process only that post. ## `maxMediaItems` (type: `integer`): Optional cap for saved media rows across the run. Use a small value for a low-cost test. ## `mediaTypes` (type: `array`): Save all media, or keep only videos, photos, or documents. ## `includePostText` (type: `boolean`): Save visible Telegram post text with each media row. ## `includeThumbnails` (type: `boolean`): Save thumbnail URLs when Telegram shows them. ## `skipDuplicateMedia` (type: `boolean`): Avoid saving the same media URL more than once. ## `includeFailedTargets` (type: `boolean`): Save a status row when a target is private, missing, unsupported, or has no matching media. ## Actor input object example ```json { "targets": [ "https://t.me/csifeducacionmadrid/2508", "https://t.me/s/csifeducacionmadrid" ], "maxPostsPerChannel": 10, "mediaTypes": [ "all" ], "includePostText": true, "includeThumbnails": true, "skipDuplicateMedia": true, "includeFailedTargets": true } ``` # Actor output Schema ## `results` (type: `string`): Open the dataset with Telegram media rows and any requested target status rows. # 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 = { "targets": [ "https://t.me/csifeducacionmadrid/2508", "https://t.me/s/csifeducacionmadrid" ] }; // Run the Actor and wait for it to finish const run = await client.actor("maximedupre/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 = { "targets": [ "https://t.me/csifeducacionmadrid/2508", "https://t.me/s/csifeducacionmadrid", ] } # Run the Actor and wait for it to finish run = client.actor("maximedupre/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 '{ "targets": [ "https://t.me/csifeducacionmadrid/2508", "https://t.me/s/csifeducacionmadrid" ] }' | apify call maximedupre/telegram-media-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=maximedupre/telegram-media-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Media Downloader", "description": "Download public Telegram photos, videos, and documents from post URLs, channels, groups, or @handles. Get media URLs, post text, dates, views, thumbnails, and source links in a clean Apify dataset.", "version": "0.0", "x-build-id": "uSV7c1p9JFaJaA73q" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/maximedupre~telegram-media-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-maximedupre-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/maximedupre~telegram-media-downloader/runs": { "post": { "operationId": "runs-sync-maximedupre-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/maximedupre~telegram-media-downloader/run-sync": { "post": { "operationId": "run-sync-maximedupre-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": [ "targets" ], "properties": { "targets": { "title": "Telegram targets", "minItems": 1, "maxItems": 500, "type": "array", "description": "Paste public Telegram post URLs, channel URLs, group URLs, t.me/s archive URLs, or @handles. Post URLs process one post; channel and group targets scan recent public posts.", "items": { "type": "string", "minLength": 1 } }, "maxPostsPerChannel": { "title": "Post limit per channel", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many recent posts to check for each channel or group target. Post URL targets always process only that post.", "default": 10 }, "maxMediaItems": { "title": "Total media item limit", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Optional cap for saved media rows across the run. Use a small value for a low-cost test." }, "mediaTypes": { "title": "Media types", "uniqueItems": true, "type": "array", "description": "Save all media, or keep only videos, photos, or documents.", "items": { "type": "string", "enum": [ "all", "video", "photo", "document" ], "enumTitles": [ "All media", "Videos", "Photos", "Documents" ] }, "default": [ "all" ] }, "includePostText": { "title": "Include post text", "type": "boolean", "description": "Save visible Telegram post text with each media row.", "default": true }, "includeThumbnails": { "title": "Include thumbnails", "type": "boolean", "description": "Save thumbnail URLs when Telegram shows them.", "default": true }, "skipDuplicateMedia": { "title": "Skip duplicate media", "type": "boolean", "description": "Avoid saving the same media URL more than once.", "default": true }, "includeFailedTargets": { "title": "Include failed targets", "type": "boolean", "description": "Save a status row when a target is private, missing, unsupported, or has no matching media.", "default": 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 } } } } } } } } } } ```