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/<channel> archive pages and public t.me/<channel>/<messageId> 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. By default it saves one compatible dataset item per message; optional outputMode: "media" saves one independently usable row per selected attachment.

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 downloads with working API URLs, status, MIME type, and byte size
• Per-file download errors without losing other attachments
• Source-level skip/error rows for inaccessible, deleted, private, or unsupported public URLs

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: choose stable message rows or one flat row per media attachment.
• Media-aware: photos, videos (including round videos), documents, audio/voice notes, and unknown CDN files are classified from public markup.
• Optional downloads: persist media during the same run and receive a non-secret run-storage URL plus per-file status.
• Automation-ready: works with Apify API, schedules, webhooks, and integrations.

Supported Telegram URLs

Use public Telegram links such as:

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. This independent Actor is not affiliated with, endorsed by, or operated by Telegram.

Input options

Field	Type	Description
startUrls	array	Public Telegram archive or post URLs.
maxMessages	integer	Maximum messages to process. Media mode can produce multiple rows per message.
outputMode	string	messages (default) or media for one row per selected attachment.
downloadFiles	boolean	Save media files to key-value store and return download metadata.
mediaTypes	array	Keep selected photo, video, document, audio, or unknown attachments.
minDate	string	Optional ISO earliest publish date; older archive pages stop pagination.
maxDate	string	Optional ISO latest publish date. Invalid/reversed dates fail before requests.

Example input

{
  "startUrls": [
    { "url": "https://t.me/s/telegram" }
  ],
  "maxMessages": 100,
  "outputMode": "media",
  "downloadFiles": false,
  "mediaTypes": ["photo", "video", "document", "audio"]
}

Output data

In the default messages mode, each dataset item represents one public Telegram message and preserves the original top-level fields. In media mode, each selected attachment becomes a row with inherited message provenance; messages with no selected media produce no media row. Source errors remain explicit source_error rows so batches can continue.

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 deterministic position/ID, type, URL, optional Telegram metadata, and download result.
mediaIndex, mediaId	Deterministic attachment position and stable <channel>/<message>/<position> identity (media mode).
mediaType, mediaUrl	Flat attachment type and source URL (media mode).
downloadStatus	not_requested, downloaded, or failed per attachment.
downloadUrl, kvKey, kvUrl	Non-secret run KVS API URL and storage identity after a successful download. kvUrl is retained for compatibility and now contains the usable URL.
mimeType, byteSize, downloadError	Response metadata or a safe per-file failure reason.
downloaded	Whether the row/message contains at least one downloaded file.
skippedReason	Why a source produced no accessible public message.
scrapedAt	Extraction timestamp.

Example output item

{
  "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,
  "recordType": "media",
  "mediaTypes": ["video"],
  "mediaCount": 1,
  "mediaUrls": ["https://cdn1.telesco.pe/file/example.mp4?..."],
  "media": [{
    "type": "video",
    "url": "https://cdn1.telesco.pe/file/example.mp4?...",
    "mediaIndex": 1,
    "mediaId": "telegram/429/1",
    "downloadStatus": "not_requested",
    "downloaded": false
  }],
  "mediaIndex": 1,
  "mediaId": "telegram/429/1",
  "mediaType": "video",
  "mediaUrl": "https://cdn1.telesco.pe/file/example.mp4?...",
  "downloadStatus": "not_requested",
  "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-dataset-item event. Message mode produces one billable item per saved message/source error; media mode produces one per selected attachment (plus any source-error row). 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/<channel> 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

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

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

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:

https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader

Add it to Claude Code:

$claude mcp add --transport http apify-telegram-media https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader

Claude Desktop JSON config example:

{
  "mcpServers": {
    "apify-telegram-media": {
      "url": "https://mcp.apify.com/?tools=automation-lab/telegram-media-downloader"
    }
  }
}

For Cursor, add the same server URL under Settings → Tools & Integrations → MCP. For VS Code, add it through the MCP: Add Server command and select HTTP.

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. Returned downloadUrl/kvUrl values are non-secret Apify API record URLs; availability follows the run key-value store's access and retention settings in your Apify account.

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.2

Added optional media-per-row output, actionable download metadata and URLs, richer voice/round-video classification, strict date validation, bounded pagination, and resilient source-level errors.

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.