Telegram Chat Scraper

Affiliate disclosure: Some Apify links below include the aiagentapi referral parameter. AgentX may receive referral attribution when you use those links; your Actor price does not change.

Telegram Chat Scraper exports messages from a username-addressable Telegram channel or group into a 23-field Apify dataset. It captures text, sender labels, timestamps, source engagement counts, replies, forwards, reactions, topics, service actions, links, hashtags, and optional stored media.

• Three required inputs select a public username target, media scope, and a message request from 10 to 1,000,000.
• An optional UTC or relative start date limits the historical window; there is no end-date input.
• Every returned message follows the same documented 23-field top-level contract.
• Input, dataset, output, and key-value store schemas validate for this release.

Run a 10-message text-only test · Open the API page

At configured FREE-tier event prices, one start plus 10 returned text-only messages has a $0.01540 fixed-event subtotal, before variable actor_usage. Telegram access, message visibility, source rate limits, runtime, storage, and live prices can change. Media-heavy or very large requests can exceed practical time, disk, transfer, or storage limits; start with text only and set a maximum total charge.

Why Choose This API

This Actor is designed for a known public Telegram channel or group that can be addressed by username. It walks messages from an optional start point toward the present and stores each available message as a structured dataset row. The result can be exported, scheduled, sent through a webhook, or consumed by another approved workflow.

The record contract keeps content and context together. Message text, sender label, source timestamps, visible counts, reply linkage, forwarded-source details, reactions, forum topic names, service actions, extracted URLs, hashtags, and optional media links occupy predictable fields.

It is not a private-chat bypass, join-link client, member exporter, identity verifier, sentiment model, archive guarantee, or moderation tool. The managed Telegram account must be able to resolve the username target. Deleted, inaccessible, protected, transiently unavailable, or unsupported records can be omitted.

Quick Start

Open the input form, keep the default public target, select text, request 10 messages, and leave the optional date empty. Text-only mode avoids file downloads while you verify access and dataset shape.

Use this shared example:

{
  "telegram_url": "https://t.me/aipost",
  "download_medias": "text",
  "max_results": 10
}

After the run, inspect the default dataset rather than relying only on terminal status. Confirm that the item count is nonzero, review timestamps and message IDs, follow extracted URLs, and retain the run ID. A completed cloud run without expected rows is not a successful data outcome and should be investigated before scaling or scheduling.

Next, add a small start_date or test image on a short window. Avoid combining a large message limit, a long historical range, and all media in the first run.

Input Configuration

telegram_url is required. Accepted forms are a username, @username, or a standard t.me/username or telegram.me/username URL. Public preview URLs with /s/username are normalized. Invite links, joinchat links, t.me/+... links, arbitrary web hosts, and blank targets are rejected.

download_medias is required and accepts text, image, or all. text stores no message files. image downloads Telegram photo media. all downloads photos and Telegram document-based media when available. Other media classes may still return no file URL.

max_results is required and accepts 10 through 1,000,000 in the public schema. The runtime caps free users at 10 messages. Paying users can request more, but the ceiling is not a recommendation or completion guarantee.

start_date is optional. It accepts YYYY-MM-DD in UTC or a relative value such as 7 days, 2 weeks, 1 month, or 1 year. Relative months and years are approximated as 30 and 365 days. Messages are requested from that point toward the present; no end-date field is exposed.

Output Schema

Each dataset row has 23 top-level fields:

• Provenance: processor, processed_at.
• Core message: id, type, date, text, sender.
• Message state: silent, pinned, edit_date.
• Source engagement: view_count, reply_count, forward_count, reactions.
• Relationships and grouping: reply_to, album_id, topic_name, forward_info.
• Extracted content: urls, hashtags, media_url.
• Service events: service_type, service_info.

This representative text-only row contains every key. Values show the contract, not a guaranteed live message:

{
  "processor": "https://apify.com/agentx/telegram-chat-scraper?fpr=aiagentapi",
  "processed_at": "2026-07-24T06:50:00+00:00",
  "id": 12345,
  "type": "Regular",
  "date": "2026-07-23T21:30:00+00:00",
  "text": "Example Telegram message with https://example.com #update",
  "sender": "@example_sender",
  "silent": false,
  "pinned": false,
  "view_count": 250,
  "reply_count": 3,
  "forward_count": 7,
  "reply_to": null,
  "album_id": null,
  "topic_name": null,
  "edit_date": null,
  "urls": [
    "https://example.com"
  ],
  "hashtags": [
    "#update"
  ],
  "service_type": null,
  "service_info": null,
  "forward_info": null,
  "reactions": {
    "👍": 4
  },
  "media_url": ""
}

sender is the best available label and can be an @username, first name, numeric identifier, post-author label, or null; it is not proof of identity. Source counts and reactions represent what Telegram exposed at processing time. An empty media_url can mean media was disabled, unsupported, absent, failed to download, or failed to store.

Media and Storage

Downloaded files are uploaded to the run's Apify key-value store, and the resulting URL is placed in media_url. Dataset rows remain the primary structured output; stored files are a separate resource with their own retention, transfer, and access considerations.

image selects photos only. all adds Telegram document-based media, which can include common document, video, audio, or other file representations. It does not promise every attachment type, preview, thumbnail, external webpage asset, or expired media reference.

There is no input for maximum file size, total downloaded bytes, allowed extension, or MIME type. For safety and predictable cost, use a short date window and low message count before enabling media. Treat downloaded files as untrusted content and scan them before opening or forwarding.

API and MCP Integration

The synchronous HTTP example below uses the shared text-only input. Replace YOUR_TOKEN and keep it in a secret store:

curl -X POST "https://api.apify.com/v2/acts/CTS2Fv7KyZuiQeSJ8/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"telegram_url":"https://t.me/aipost","download_medias":"text","max_results":10}'

Configure an MCP client using the Apify MCP documentation:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?token=YOUR_TOKEN"
    }
  }
}

Then call the Actor with the same scenario:

{
  "actor": "agentx/telegram-chat-scraper",
  "input": {
    "telegram_url": "https://t.me/aipost",
    "download_medias": "text",
    "max_results": 10
  }
}

For larger jobs, start asynchronously, poll the run, then check the default dataset item count. Use webhooks only after a small regression proves that SUCCEEDED also produced expected rows. Apply an independent maximum total charge and avoid automatic retries of media-heavy inputs.

Pricing

Pricing combines usage and output events. apify-actor-start is $0.01000. actor_usage is $0.00001 per usage event and varies with runtime, proxy, and storage consumption. Message prices are FREE $0.00054, BRONZE $0.00052, SILVER $0.00050, and GOLD or higher $0.00049. Media prices are FREE $0.00100, BRONZE $0.00097, SILVER $0.00093, and GOLD or higher $0.00090.

FREE-tier example	Fixed-event calculation	Subtotal before actor_usage
10 text-only messages	$0.01000 + 10 × $0.00054	$0.01540
10 messages with 3 stored media files	$0.01000 + 10 × $0.00054 + 3 × $0.00100	$0.01840

Actual charges depend on events, resource use, account tier, and live platform behavior. Confirm the published pricing page before budgeting. Message and date limits do not cap media bytes or replace maxTotalChargeUsd.

Use Cases

Public channel monitoring: capture a small timestamped sample of recent announcements, links, hashtags, and visible engagement for human review. A sample is not a complete archive.

Forum-topic observation: preserve available topic names, reply links, and source counts for bounded community research. Missing topic names or replies should remain null rather than guessed.

Content pipelines: pass message text and extracted URLs into approved classification, translation, summarization, or archival workflows. Keep the original target, message ID, and date with derived data.

Media review: collect a narrowly bounded set of public photos or documents for authorized analysis. Avoid bulk downloading without a retention, malware-scanning, privacy, and storage plan.

Data Quality and Interpretation

Telegram controls access, entity resolution, message visibility, source counts, reactions, edits, forwards, service actions, and media availability. A later run can return different values. Sender labels can be incomplete or numeric, and forwarded-source details can be hidden.

Service messages are represented through type, service_type, and service_info. Only recognized actions receive a descriptive service type; unknown actions can remain empty. URLs and hashtags come from Telegram message entities rather than a general crawl of linked pages.

Never treat views as unique people, reactions as verified sentiment, sender labels as authenticated identity, or message absence as proof of deletion. Verify consequential information at the source.

Frequently Asked Questions

Can it open private invitation links?

No. The input normalizer rejects join and plus-style invitation links. Use a public username-addressable channel or group.

Why are free users limited to 10 messages?

The runtime applies a 10-message cap when the Apify user is not paying, even though the public field accepts larger values.

What is the difference between image and all?

image downloads Telegram photos. all also attempts Telegram document-based media. Neither option guarantees every media class or successful storage.

Can I set an end date?

No. start_date defines the beginning of the requested window, and collection moves toward the present.

Does a successful run guarantee rows?

No. Always verify the dataset item count and expected content. Access failures, empty ranges, source errors, skipped records, storage or push failures, and older published builds can affect output.

Limits and Troubleshooting

If the target is rejected, use a plain public username, @username, or standard t.me username URL. If no messages appear, remove the date, use text mode, request 10, and verify that the target is accessible without an invite link.

If a media run is slow, switch to text and reduce the time window. There is no byte cap, and individual documents can be large. Check key-value-store records separately from dataset rows.

If terminal status is successful but the dataset is empty, treat the regression as a failed data outcome. Preserve the run ID and input, inspect logs, and contact support rather than scaling, scheduling, or repeatedly paying for the same request.

Related Actors

• Telegram Info Scraper returns profile metadata for one username-addressable channel or group.
• Telegram Member Scraper targets visible participant data where Telegram permits access.
• Telegram Private Group Scraper serves a different access workflow; review its own input and authorization requirements.
• All Jobs Scraper, All Shopping Scraper, and All Video Scraper provide broader AgentX enrichment surfaces.

Support and Responsible Use

Contact AgentX support with the Actor name, run ID, sanitized input, expected item count, actual item count, and whether media was enabled. Never share Telegram sessions, Apify tokens, private files, or personal secrets.

Collect only data you are authorized to process. Follow Telegram terms, applicable law, copyright, privacy obligations, and retention policies. Do not use the Actor for harassment, surveillance, spam, sensitive profiling, or unauthorized redistribution. Open the Actor page for the current Store release and live prices.

Last updated: July 24, 2026.