Telegram Channel Content & Media Scraper

📦 Telegram Channel Content & Media Scraper

🎬 Download photos, videos and posts from any public Telegram channel — in one click.

Paste up to 25 public channels and in a few minutes you get:

• All photos, videos, audio and files from the posts — as links, or downloaded to storage with direct download URLs
• Only the media you need: choose Photos only, Videos only, Audio only or Files only
• File details for every file: type, file name, size in MB, width × height, video and audio duration
• The post itself: text, date, views, reactions, forwards, hashtags, mentions and links
• A table you can export to Excel, CSV or JSON, or send to Google Sheets, Make or Zapier

No Telegram account, API key or phone number needed — just enter channel names and click Start.

Who it's for: content managers and media teams archiving channels, researchers and AI teams building image, video and text datasets, news and content aggregators.

🆕 Updated on October 16, 2026: new Media type filter (photos / videos / audio / files) and a mediaFiles field with details of every file. Nothing changed in existing fields or defaults.

💰 $10 per 1,000 posts — that's it. No monthly fee, no run fee, no extra charge for downloading media. Service records, skipped posts, errors and queue time are free. Details below in Pricing.

---

🆕 What's new (2026-10-16)

• ✅ Media type filter (mediaFilter): All media (default, as before), Photos only, Videos only, Audio and voice only, Files only (PDF, ZIP, etc.). Posts without such files are skipped and not charged
• ✅ mediaFiles on every post — one entry per file: type, fileName, mimeType, sizeMB, width, height, durationSec, url, downloaded
• ✅ RUN_SUMMARY now shows mediaFilter and skippedByMediaFilter
• ✅ Output tab: Type, File types and Media links columns
• ✅ Existing fields, defaults and pricing unchanged — your automations keep working

---

💰 Pricing

What	Price
Post	$10.00 / 1,000 posts
Downloading media	Free
Platform usage	Included

No monthly fee and no run fee.

You are never charged for:

• service records: "no posts found", channel errors, rate-limit notices, skipped channels;
• posts skipped by the Media type filter or by Media only;
• time in the queue, queue timeouts and failed connections to Telegram.

With groupAlbums: true, an album is one post — you pay once per album, not once per photo.

Since October 13, 2026, you pay only for real posts: service records, which used to be charged, are now free.

Set Max cost per run in the run options to cap your spending — the Actor stops cleanly when the limit is reached.

---

✅ What This Actor Does

• Connects to Telegram automatically (no credentials needed from your side)
• Parses public channels (by username or t.me link), up to 25 channels per run
• For each post:
  • Media: photos, videos, GIFs, audio and voice messages, documents — as t.me links, or downloaded with direct URLs (.jpg, .mp4, .pdf, etc.), with file details in mediaFiles
  • Content: text, date, post URL, views, reactions (with emoji breakdown + total)
  • Forwards: detects native Telegram forwards and exposes the source (isForward, forwardFromType, forwardFromId, forwardFromName, forwardChannelPost, forwardPostAuthor, forwardDate)
  • Hashtags & mentions (Unicode-aware — supports Cyrillic, e.g. #вакансия)
  • Links, edit date, reply chain (replyToMsgId, replyToPostUrl)
• For each channel: title, description, subscriber count
• Handles:
  • Albums — one record per message by default, or one record per album with groupAlbums
  • Large files — files over maxMediaSizeMB stay as links instead of being downloaded
  • Telegram FloodWait limits gracefully (with an explanatory record in the dataset)
  • Cross-run conflicts via a per-session queue (see "Queue Behavior" below)
• Channels you've scraped before are remembered, so repeat runs are faster and avoid Telegram lookup limits
• Starts from the most recent post and works backwards

---

🧾 Input

You don't need to enter any credentials — they're already preconfigured.

Field	Type	Required	Default	Description
channels	string	✅	—	Channel usernames or links, separated by commas or new lines (e.g. @channel1, https://t.me/channel2)
maxPosts	number	❌	10	Max number of Telegram messages per channel (1–200)
daysRange	number	❌	3	Number of days to look back from today (1–30)
includeText	boolean	❌	true	Whether to include post text in the output
mediaOnly	boolean	❌	false	If true, skip posts that have no photos, videos or files
mediaFilter	string	❌	all	all, photo, video, audio or document. Returns only posts with this type of file, and lists (or downloads) only those files. GIFs and stickers count only under all
downloadMedia	boolean	❌	false	If true, download media files into the run's Key-Value Store
maxMediaSizeMB	number	❌	50	Files larger than this stay as t.me links (not downloaded). 0 = no limit
groupAlbums	boolean	❌	false	If true, merge an album into one record: all files in mediaUrls, all message ids in groupedPostIds. With merging on you may get fewer records than maxPosts, because maxPosts counts Telegram messages

📌 Example input — download all videos from the last week

{
  "channels": "@channel1, https://t.me/channel2",
  "maxPosts": 100,
  "daysRange": 7,
  "mediaFilter": "video",
  "downloadMedia": true,
  "maxMediaSizeMB": 200,
  "groupAlbums": true
}

💡 The filter works within maxPosts and daysRange. Videos only with maxPosts: 20 returns the videos among the last 20 messages, not 20 videos. To find more, raise maxPosts.

⚠️ Channel limits per run. Up to 25 channels per run, of which up to 10 new channels (not scraped by this Actor before). Previously scraped channels are remembered and don't need a Telegram lookup, so they don't count toward the 10. Channels over the limit are listed in the run status and saved as type: "skipped" records — just run them again.

---

▶️ How to Run

1. Open the Actor in Apify Console
2. Fill in the input fields — pick a Media type if you need only photos, videos, audio or files
3. Turn on Download media if you want the files themselves, not just links
4. Click Save, then Start
5. Results are on the Output tab:
   • Posts — all posts with media links and file details
   • Downloaded media files — when downloadMedia is on
   • Run summary

---

📤 Output

Each Telegram message (or each album, with groupAlbums: true) is saved as a separate record in the default dataset (JSON format). Every record has a type field:

type	Meaning
post	A post with content
no_posts	Channel has no matching posts in the selected period
skipped	Channel postponed (per-run limit or temporary Telegram limit) — run it again
telegram_rate_limit	Telegram asked to slow down; includes waitSeconds
channel_error	Channel not found, private, or another error

Only post records are charged. To get only content, filter by type = "post".

{
  "type": "post",
  "channel": "@channel_name",
  "channelLink": "https://t.me/channel_name",
  "channelTitle": "Channel Display Name",
  "channelDescription": "Channel about / bio text",
  "postId": 552,
  "postUrl": "https://t.me/channel_name/552",
  "date": "2026-10-11T14:52:40.000Z",
  "views": 969222,
  "subscribers": 10357013,
  "text": "Example post content with #hashtag and @mention",
  "reactions": [
    { "emoji": "👍", "count": 42 },
    { "emoji": "❤️", "count": 18 }
  ],
  "totalReactions": 60,
  "links": ["https://example.com"],
  "hasMedia": true,
  "mediaUrls": [
    "https://api.apify.com/v2/key-value-stores/<storeId>/records/channel_name_552.mp4?disableRedirect=1"
  ],
  "mediaTypes": ["mp4"],
  "mediaFiles": [
    {
      "type": "video",
      "fileName": "IMG_6025.MP4",
      "mimeType": "video/mp4",
      "sizeMB": 27.71,
      "width": 1080,
      "height": 1080,
      "durationSec": 75.95,
      "postId": 552,
      "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/channel_name_552.mp4?disableRedirect=1",
      "downloaded": true
    }
  ],
  "groupedPostIds": [552],
  "isForward": false,
  "forwardFromType": "",
  "forwardFromId": "",
  "forwardFromName": "",
  "forwardChannelPost": 0,
  "forwardPostAuthor": "",
  "forwardDate": "",
  "hashtags": ["#hashtag"],
  "mentions": ["@mention"],
  "editDate": "",
  "replyToMsgId": 0,
  "replyToPostUrl": ""
}

mediaFiles — file details

Field	Meaning
type	photo, video, gif, audio, sticker or document. Telegram marks silent looping videos as gif
fileName	Original file name, if the file has one (photos usually don't)
mimeType	For example image/jpeg, video/mp4, application/pdf
sizeMB	File size in MB
width, height	In pixels, for photos and videos
durationSec	Length of videos and audio, in seconds
url	Direct download URL if the file was downloaded, otherwise the t.me link
downloaded	true if the file is saved in the run's Key-Value Store

Run summary (RUN_SUMMARY)

{
  "posts": 2,
  "channelsProcessed": 3,
  "mediaDownloaded": 2,
  "mediaSkippedLarge": 0,
  "postponedChannels": [],
  "failedChannels": [],
  "costLimitReached": false,
  "mediaFilter": "video",
  "skippedByMediaFilter": 40
}

---

⏳ Queue Behavior (Important for parallel users)

The Actor uses a shared Telegram session preconfigured by the author. Telegram allows only one active connection per session at any time — if multiple users run the Actor simultaneously, the second connection would get AUTH_KEY_DUPLICATED.

To prevent this, the Actor uses a cross-run lock: parallel runs are automatically queued and processed one at a time.

What this means in practice:

• If no one else is running the Actor → starts immediately
• If another user is currently scraping → your run waits in queue, and the run status shows how long you've been waiting
• A typical wait is a few minutes (depends on what the previous run is doing)
• Maximum queue wait is 15 minutes, after which the run fails with a clear message. You are not charged for waiting

---

🛡️ Telegram Rate Limit Handling

If Telegram returns a FloodWait on contacts.ResolveUsername (too many lookups of new channel usernames in a short period), the Actor:

1. Stops looking up new channels for the rest of this run, to protect the session
2. Keeps processing channels you've scraped before — they don't need a lookup
3. Adds a telegram_rate_limit record with the wait duration (waitSeconds) and a clear explanation
4. Retry the skipped channels after the indicated time (often 10–11 hours)

For any other very long FloodWait (1 hour or more), the run stops early to protect the session and reports it in the dataset and run status.

---

🛠 Use Cases

• Media archiving — save all photos and videos of a channel before they disappear
• AI and ML datasets — collect images, videos and captions, filtered by type, with size and resolution for each file
• Content repurposing — get the videos or images you need from your own or partner channels
• News and content aggregation — pull posts and media from many channels into one feed
• Document collection — download PDFs and other files shared in channels

---

📜 Changelog

2026-10-16

• ✅ New Media type filter (mediaFilter): all / photo / video / audio / document; posts without such files are skipped and not charged
• ✅ New mediaFiles field with details of every file (type, file name, MIME type, size, width, height, duration, URL, downloaded)
• ✅ RUN_SUMMARY: mediaFilter, skippedByMediaFilter
• ✅ Output tab: Type, File types and Media links columns
• ✅ Existing fields, defaults and pricing unchanged

2026-10-13

• ✅ Fairer billing is live: same $10 / 1,000 posts, service records are no longer charged

2026-09-29

• ✅ Billing announced for 2026-10-13: same $10 / 1,000 posts, service records no longer charged
• ✅ Channel cache: previously scraped channels skip contacts.ResolveUsername (the main cause of FloodWait); each channel is now resolved once per run instead of twice
• ✅ Up to 25 channels per run, max 10 new ones; channels over the limit are reported as type: "skipped" instead of being silently dropped
• ✅ FloodWait on new-channel lookups no longer stops already-known channels
• ✅ Run status messages: queue waiting time, progress per channel, final summary
• ✅ RUN_SUMMARY record in the Key-Value Store
• ✅ type field on every record (post, no_posts, skipped, telegram_rate_limit, channel_error)
• ✅ channels accepts t.me links (incl. /s/ and post links) and new-line separation; duplicates removed
• ✅ New groupAlbums option (off by default) and groupedPostIds field
• ✅ New maxMediaSizeMB option (default 50 MB)
• ✅ Link previews no longer counted as media (hasMedia, mediaUrls)
• ✅ Respects the Max cost per run limit
• ✅ Clearer error messages for invalid, private and non-channel usernames

2026-05-03

• ✅ Added channel metadata (channelTitle, channelDescription)
• ✅ Added forwards detection (7 new forward* fields)
• ✅ Added hashtags + mentions extraction
• ✅ Added editDate and reply chain fields (replyToMsgId, replyToPostUrl)
• ✅ Cross-run lock now uses author-scoped Apify token, so the queue works for all users (not only the Actor owner)
• ✅ Replaced silent exit handling with explicit Actor.fail() so errors are visible in run status
• ✅ Added 15-second timeout on Telegram getMe() to prevent multi-minute hangs on dead sessions
• ✅ Disabled autoReconnect to fail fast and surface real errors

2025-12-05

• ✅ Added explicit handling and logging for Telegram contacts.ResolveUsername FloodWait errors
• ✅ When Telegram returns a FloodWait, the Actor now stops processing further channels in that run and adds a telegram_rate_limit record to the dataset with a human-readable explanation
• ✅ Limited the number of channels processed per run to 10 to reduce the risk of hitting global FloodWait on the shared Telegram session
• ✅ Updated input description to recommend no more than 10 channels per run and documented this behavior in the README

2025-10-10

• ✅ Fixed AUTH_KEY_DUPLICATED by adding a per-session lock (prevents concurrent reuse of the same Telegram auth key)
• ✅ Improved error messages for session conflicts
• ✅ Internal stability tweaks for Telegram requests and media downloads

---

❓ Troubleshooting

Empty results / type: "no_posts"

• Increase daysRange to 7..14 — the channel may not have posts in the default 3-day window
• Increase maxPosts to 20..50
• Make sure the channel is public and the username is correct

"No posts with video files found…" with a Media type filter

• The channel had no such files among the checked posts. Raise maxPosts or daysRange

A video is missing with Videos only

• Telegram may mark it as a GIF (silent looping video). Use All media and filter by mediaFiles.type

A file is a t.me link instead of a download URL

• It's larger than maxMediaSizeMB (default 50 MB). Raise the limit or set 0 for no limit

type: "skipped" records / channels "not processed" in the run status

• The run hit the per-run channel limits — run again with just those channels

type: "channel_error"

• The channel may be private, deleted, a user or bot rather than a channel, or an invite link (t.me/+...), which isn't supported

Run waits 5+ minutes in queue

• Another user is currently using the Actor; this is normal under load
• Retry in a few minutes when the queue clears

telegram_rate_limit record in dataset

• Telegram applied a FloodWait — wait the indicated number of hours before retrying the skipped channels
• Channels you've scraped before are not affected

Run failed with AUTH_KEY_DUPLICATED

• Should not happen with the built-in queue, but if it does — wait 10 minutes and retry

---

⚠️ Telegram Albums

Telegram delivers an album (several photos/videos with one caption) as several separate messages, one file each, with the caption on one of them.

By default (groupAlbums: false) the Actor returns them as Telegram delivers them — one record per message. They share the same date and have consecutive postId values.

With groupAlbums: true the Actor merges them into one record — and you pay for one post:

• text — the album's caption
• mediaUrls / mediaTypes / mediaFiles — all files of the album
• groupedPostIds — ids of all messages in the album
• postId / postUrl — the first message of the album

---

🔐 License & Usage

This Actor is a proprietary paid product.

• ❗ It is not open source
• 📦 It is licensed for private and commercial use by users of this Actor
• 🛑 Any unauthorized copying, reselling, or redistribution is strictly prohibited
• 🧑‍💻 All activity is logged for abuse prevention and fair use enforcement

To report a bug, please open an issue — I respond quickly.

---

Made with 💙 for Telegram research & automation.