Telegram Channel Scraper (Store README - EN)

Status: APPROVED Store copy; published on 2026-09-13.

Available on Apify Store. Widget mode needs no login; MTProto mode uses the publisher's own account pool. Final-build extraction, PPE charging, and spend-limit proofs pass.

1. Value proposition

Turn public Telegram channels into clean structured data — message texts, views, reactions, media flags, channel headers — with new-message monitoring between runs. Widget mode needs no login, API key, or browser. Optional MTProto mode adds comments, forwards, members, polls, stories and channel discovery.

2. What the Actor does / 3. For whom / 4. Snapshot-monitor

• Snapshot: read the listed channels (paged history where available); one channel row plus one message row per post.
• Monitor: same read against the stored baseline plus change_event rows for new messages (message_added).
• For news digests, brand/channel monitoring, research datasets, and feeding RAG pipelines with channel content.

5. Key features / 6. Responsible use / 7. Input guide / 8. Output schema

• Static widget pages (t.me/s/<channel>) parsed into text (+ opt-in raw HTML), links, hashtags, mentions, emails published in posts, sender + author with profile URLs, views, reactions, photo URLs (albums included), direct video file URLs with durations, document names/sizes, stickers, voice durations, polls with per-option results, rich link previews, channel avatar, media flags, dates.
• Channel profile: subscribers, verification, scam/fake badges, photo/video/ file/link totals, related channels (forwards + description links), optional linked discussion group with member counts, plus engagement analytics over the collected window (average/median/max views, average reactions, posts per day, engagement rate).
• Date windows (absolute or relative like "7 days"), keyword search filter, minimum-views filter, media-only / text-only modes, history paging, per-channel caps, profile-only mode (no history fetch).
• Polite by design: throttled (default 2 s), max 3 concurrent, timeouts, byte caps, 25-page safety cap per channel.
• Honest coverage: complete/partial + structured warnings[]; source and optional-feature failures are surfaced, and missing feeds are classified (CHANNEL_NOT_FOUND / CHANNEL_PREVIEW_DISABLED / CHANNEL_IS_GROUP / CHANNEL_IS_USER), never silent empty runs.

MTProto mode (owner account pool)

Set authMode: "mtproto" to read through the Telegram API instead of widget pages: discussion comments with authors, forward/repost counters, reply counters, real poll votes (closed/quiz/solution included), media metadata (dimensions, durations, document names, sticker emoji), participant counts, capped discussion participant export, Telegram's own similar channels, global topic discovery, exact post URLs, service events, sender ids, rich-text entities, TTL timers, forward origin tracing, active channel stories. Needs the owner pool (TG_SESSION_*, live source only); accounts rotate automatically on flood waits and quarantine on bans. Read-only calls — no joins, invites or writes.

• Responsible use: public channels only; you are accountable for how you use collected posts. See RESPONSIBLE_USE.md.
• Input: channels or channelObjects (stable ids), mode, maxPosts, includeText, limits, baselineKey. Output: channel + message + change_event rows; fields in .actor/dataset_schema.json.

9. Examples / 10. Monitoring / 11. Coverage / 12. Cost

• Example input: { "mode": "snapshot", "channels": ["durov"], "maxPosts": 25 }.
• Monitor example: same input with "mode": "monitor"; first run creates the baseline, later runs add change_event rows only for newly observed messages.
• Coverage: complete/partial + warnings[] for detected source, budget, cap, and optional-feature failures.
• Store pricing: pay-per-event - $0.00030 per unique message and $0.001 per monitor change event. apify-actor-start is synthetic and never charged manually. Channel/member/story rows are free; monitor re-runs bill only new messages. Active cloud proof is tracked in PRICING_DRAFT.md.

13. Scheduling / 14. API examples / 15. Views / 16. FAQ

• Schedule via Apify Schedules (hourly/daily) for digest mode.
• API: standard Apify run + dataset endpoints; envelope carries recordType, canonicalId, queryId, fetchedAt.
• Dataset views: records (all rows), messageFields, changeFields.
• Do I need login or an API key? No for widget mode — public pages only. authMode: "mtproto" uses the publisher's own pool for comments/forwards. Private channels? Not readable by design (CHANNEL_NOT_FOUND). How far back? History paging per channel up to the cap.

17. AI assistants (MCP)

Call this actor from Claude, ChatGPT or any agent framework through the Apify MCP server (https://mcp.apify.com). Agent guidance:

• Default to widget mode (no login, fastest, cheapest): monitoring, keyword search, lead extraction, analytics.
• Switch to authMode: "mtproto" only when the task needs discussion comments, forward counters, exact polls, members or similar channels.
• Prefer messagePreview: true for summarization tasks (one line per post, small context), full text for RAG ingestion.
• Prefer includePosts: false + resolveDiscussion: true to validate a channel list cheaply before a deep run.
• Example prompts: "pull the last 50 posts from @durov with views and reactions", "find crypto channels talking about staking and list their subscriber counts" (discover + MTProto), "watch @tginfo for new posts mentioning airdrop" (mode: "monitor" + searchKeywords on a Schedule).

18. Troubleshooting / 19. Support / 20. Privacy-security / 21. Changelog link

• partial coverage: see warnings[] for per-channel causes.
• Empty text on a row: media-only post (flagged via hasPhoto/hasVideo).
• Support: message Viremo Labs through Apify Console or the support email on the actor website (response goal: three business days).
• Privacy: public channel and linked public-discussion data only. Owner pool credentials stay secret and are never written to output.