# Telegram Channel Scraper — Messages, Search, Media & Analytics (`foxlabs/telegram-channel-scraper`) Actor

Scrape public Telegram channels with no login, phone number or API keys. Extracts channel subscribers, view rates, paginated message history, in-channel keyword search, views, emoji & Star reactions, forwards, replies and media URLs.

- **URL**: https://apify.com/foxlabs/telegram-channel-scraper.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Social media, News
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 telegram messages

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<p align="center">
  <img src="https://img.shields.io/badge/Pay--Per--Event-No_Media_Surcharges-00C853?style=for-the-badge" alt="Pay-Per-Event" />&nbsp;
  <img src="https://img.shields.io/badge/Zero_Auth-No_Phone_%26_No_API_Hash-2962FF?style=for-the-badge" alt="No Phone or API Hash" />&nbsp;
  <img src="https://img.shields.io/badge/AI_Agent_Ready-MCP_%26_x402-7C4DFF?style=for-the-badge" alt="MCP & x402 Ready" />&nbsp;
  <img src="https://img.shields.io/badge/Dual_Runtime-Batch_%2B_Standby_API-FF6D00?style=for-the-badge" alt="Batch + Standby API" />
</p>

## Telegram Channel Scraper — Messages, Search, Media & Analytics 🚀

**foXLabs Social & OSINT Series:** [Threads Scraper](https://apify.com/foxlabs/threads-scraper) · [X (Twitter) Profile](https://apify.com/foxlabs/x-profile-scraper) · [Bluesky Creator Intelligence](https://apify.com/foxlabs/bluesky-creator-intelligence) · [YouTube Channel Email Scraper](https://apify.com/foxlabs/youtube-channel-email-scraper) · [Substack Newsletter Data](https://apify.com/foxlabs/substack-newsletter-data) · [Discord Server Discovery](https://apify.com/foxlabs/discord-server-discovery)

🎉 Turn public Telegram channels (`t.me`) into clean, structured intelligence — with **no Telegram phone number, no `api_id` / `api_hash`, no session strings and zero risk of SIM or account bans**. Extract enriched channel profiles (subscriber counts, numeric `channelId`, verification badges, bio links/emails and real `viewRatePct`), multi-page historical message timelines, native in-channel keyword searches, emoji & paid Telegram Stars reactions, forwards, replies and direct CDN media URLs in one unified schema.

Built for crypto/Web3 & macro analysts, OSINT & threat-intelligence monitors, influencer/ad-buy agencies, newsrooms and autonomous AI agents.

### 🔍 What is the Telegram Channel Scraper — and when should you use it?

Collecting Telegram channel data through MTProto client libraries (such as Telethon or GramJS) requires registering a personal SIM card, maintaining fragile session strings, and risking permanent account freezes whenever automated jobs paginate rapidly. Meanwhile, Telegram's official Bot API cannot read historical messages from third-party public channels where your bot is not an administrator.

This Actor solves public Telegram extraction cleanly without any account or credentials:

- **Channel profiles & fake-subscriber detection** (`channels`) — extracts `subscribersCount` (plus raw display string `subscribersRaw`), numeric `channelId`, `isVerified`, media counters (`photosCount`, `videosCount`, `linksCount`, `filesCount`), parsed `descriptionLinks` and `descriptionEmails`, and computes `avgViews`, `avgReactions` and **`viewRatePct`** (`avgViews / subscribersCount * 100`) so media buyers can spot botted channels immediately.
- **Multi-page historical message timelines** (`channels` + `maxMessagesPerChannel`) — walks backwards cleanly past the initial 20 messages up to `maxMessagesPerChannel` (`1`–`2,000` messages per channel) and stops automatically as soon as `postedAfter` or `maxResults` is reached.
- **Native in-channel keyword search** (`channels` + `searchQuery`) — searches inside each target channel server-side for specific tickers, CVEs, brand names or phrases without downloading thousands of unrelated posts.
- **Direct single-post lookup** (`postUrls`) — resolves individual `https://t.me/<channel>/<id>` message URLs for fast point verification.

**Use it when you need:** zero-login monitoring of public crypto, finance, news or OSINT broadcast channels; Telegram sponsorship & ad-buy vetting using `viewRatePct` and `paidStarsCount`; targeted historical keyword searches inside large announcement channels; or scheduled RAG/LLM feed ingestion.

**Use something else when:** you need **private invite-only channels (`t.me/+…`)**, **group chat member rosters**, **discussion-group comment threads**, or **channels whose admins disabled public web previews**. Those surfaces require an authenticated Telegram client membership and are intentionally out of scope so you never have to expose credentials.

### 🤖 Use with AI agents (MCP, Claude, Cursor & x402)

**Already connected to the Apify MCP server?** Ask your AI assistant to call `foxlabs/telegram-channel-scraper`.

- **Hosted MCP URL (zero install):** `https://mcp.apify.com?tools=foxlabs/telegram-channel-scraper`
- **Local stdio config (Claude Desktop, Cursor, Cline, Windsurf):**

```json
{
  "mcpServers": {
    "telegram-channel-scraper": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--tools", "foxlabs/telegram-channel-scraper"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

**Your agent can pay for its own runs.** This Actor uses pay-per-event pricing and supports agentic payments, so autonomous agents can discover it, invoke runs and settle usage over **x402 (USDC on Base)** or **Skyfire** as well as standard Apify API tokens. Billing is strictly per delivered `channel` or `message` row — there are **zero per-photo or per-video surcharges**, and diagnostic `status` rows are free.

Copy-paste prompt for Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
Use the Apify Actor `foxlabs/telegram-channel-scraper` to fetch public Telegram channel profiles, message history, in-channel keyword searches or specific post URLs.

Input fields:
- `channels`: array of handles or URLs (e.g. ["durov", "@telegram", "https://t.me/toncoin"])
- `searchQuery`: optional keyword to search inside each channel in `channels`
- `postUrls`: optional array of direct message URLs (e.g. ["https://t.me/durov/538"])
- `channelMode`: "messagesAndChannelInfo" (default) | "messagesOnly" | "channelInfoOnly"
- `maxMessagesPerChannel`: integer 1..2000 (default 40)
- `maxResults`: overall row cap across the run (default 100; 0 = unlimited)
- `minViews`: minimum viewsCount filter on messages (default 0)
- `postedAfter`: optional ISO date string YYYY-MM-DD

Start with:
{"channels":["durov","telegram"],"channelMode":"messagesAndChannelInfo","maxMessagesPerChannel":15,"maxResults":35}
```

**Things you can ask your AI agent:**

- *"Compare @durov and @telegram's subscriber counts, average views and viewRatePct across their latest 20 announcements."*
- *"Search inside @telegram for messages mentioning 'mini apps' and summarize every feature launch with links."*
- *"Pull all messages posted after 2026-10-01 from these 10 Web3 channels with at least 10,000 views and flag token listings."*

The machine-readable Actor summary, MCP metadata and OpenAPI schema live at `https://apify.com/foxlabs/telegram-channel-scraper.md`.

### 📋 Overview

Everything needed to turn public `t.me` broadcast channels into structured analytics and real-time feeds — without SIM cards, MTProto sessions or browser overhead.

| Property | Details |
|---|---|
| **Public data source** | Public Telegram web channel previews & post widgets (`t.me`) |
| **Authentication required** | None — zero phone number, `api_id`, `api_hash`, 2FA or session strings |
| **Container footprint** | Lightweight `256 MB` HTTP runtime (sub-second startup, minimal compute cost) |
| **Output row types (`rowType`)** | `channel` (`$0.0020`), `message` (`$0.0008`), `status` (`$0.00` diagnostic rows) |
| **Deduplication & restart safety** | Deterministic `rowKey` (`channel:<handle>`, `message:<handle>/<id>`) — zero duplicate rows or double billing |
| **Execution modes** | Standard Batch Dataset runs + synchronous Standby HTTP API (`/channels`, `/messages`, `/search`, `/post`) |

**Why teams pick this Actor:**

- 🛡️ **Zero ban risk** — never touches your personal or corporate Telegram accounts.
- 📊 **Built-in `viewRatePct` & paid Stars signals** — exposes real reach-to-subscriber ratios and `paidStarsCount` monetization signals for sponsorship due diligence.
- 🎬 **All media URLs included at `$0.00` extra** — unlike scrapers that charge extra per image or video, photos, albums, MP4 videos, voice notes, polls and OpenGraph link cards are included in the base `$0.0008` message event.
- 🔎 **Server-side channel search** — filter multi-year announcement histories by keyword (`searchQuery`) in seconds.
- 💎 **Strict `null` discipline** — disabled reaction bars and missing header counters emit `null` (never fake `0`s), while preserving both parsed integers (`viewsCount`) and Telegram's raw strings (`viewsRaw`).

### ✨ Key Features

- 📈 **Channel Profile & Sponsorship Vetting** — Extracts `channelUsername`, numeric `channelId`, `title`, `description`, `isVerified`, `avatarUrl`, `subscribersCount` (`subscribersRaw`), `photosCount`, `videosCount`, `linksCount`, `filesCount`, `descriptionLinks`, `descriptionEmails`, `avgViews`, `avgReactions` and `viewRatePct`.
- ⏪ **Deep Backward Pagination** — Automatically steps backwards through message history (~20 posts per page) up to `maxMessagesPerChannel` (`2,000` per channel), halting early as soon as `postedAfter` or `maxResults` is satisfied.
- 🔎 **In-Channel Keyword Search** — Queries Telegram's native channel search across every handle in `channels` when `searchQuery` is set.
- ⭐ **Granular Emoji & Paid Telegram Stars Reactions** — Parses every reaction pill into structured `reactions[]` (`type`: `emoji`, `custom_emoji`, or `paid_stars`, `emoji`, `customEmojiId`, `count`, `countRaw`) alongside `totalReactionsCount` and `paidStarsCount`.
- 🖼️ **Rich Media, Albums, Documents & Polls** — Captures single photos and multi-photo albums (`photoUrls`), inline playable MP4 `videoUrls`, `videoThumbUrl`, `videoDuration`, `voiceUrl`, `documentTitle`, `documentExtra`, `pollQuestion`, inline `links` and structured `linkPreview` cards.
- 🔁 **Forward & Reply Provenance** — Preserves `isForwarded`, `forwardedFromName`, `forwardedFromUrl`, `isReply`, `replyToMessageId`, `replyToUrl`, `isEdited` and `signatureAuthor` for OSINT amplification mapping.

### 🎬 Quick Start (API & Standby HTTP)

**1. Synchronous Batch API call (returns clean JSON records directly):**

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~telegram-channel-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channels":["durov","telegram"],"channelMode":"messagesAndChannelInfo","maxMessagesPerChannel":15,"maxResults":35}'
```

**2. Real-time Standby HTTP API (warm container queries):**

```bash
## Audit channel subscriber & view-rate metrics instantly
curl "https://foxlabs--telegram-channel-scraper.apify.actor/channels?channels=durov,telegram&token=YOUR_APIFY_TOKEN"

## Search inside a channel in real time
curl "https://foxlabs--telegram-channel-scraper.apify.actor/search?channels=telegram&q=stars&max=20&token=YOUR_APIFY_TOKEN"
```

### 🚀 Getting Started (3 steps)

1. **Enter channels or post links** — Add public handles or URLs (`durov`, `@telegram`, `https://t.me/toncoin`) in **Channels**, or direct message links in **Post URLs**.
2. **Select mode & filters** — Choose `channelMode` (`messagesAndChannelInfo`, `messagesOnly`, or `channelInfoOnly`), optionally enter an in-channel `searchQuery`, and set `minViews` or `postedAfter` (`YYYY-MM-DD`).
3. **Run & export** — Click **Start** and export your clean dataset as JSON, CSV, Excel, Parquet or XML, or connect it straight to n8n, Make or BigQuery.

### 📥 Input & Filters

```json
{
  "channels": ["durov", "https://t.me/telegram"],
  "searchQuery": "",
  "postUrls": ["https://t.me/durov/538"],
  "channelMode": "messagesAndChannelInfo",
  "maxMessagesPerChannel": 25,
  "maxResults": 100,
  "minViews": 1000,
  "postedAfter": "2026-01-01"
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `channels` | `array<string>` | Prefill `["durov", "telegram"]` | Public Telegram channel handles (`durov`, `@telegram`) or URLs (`https://t.me/telegram`, `https://t.me/s/durov`). |
| `searchQuery` | `string` | `""` | Optional keyword or phrase searched inside every channel listed in `channels`. |
| `postUrls` | `array<string>` | `[]` | Optional specific message URLs (`https://t.me/durov/538`) fetched individually. |
| `channelMode` | `string` | `"messagesAndChannelInfo"` | Controls output for `channels`: `"messagesAndChannelInfo"` (1 `channel` row + `message` rows), `"messagesOnly"`, or `"channelInfoOnly"`. |
| `maxMessagesPerChannel` | `integer` | `40` | Maximum messages collected per channel (`1`–`2000`; prefill `15`). |
| `maxResults` | `integer` | `100` | Overall ceiling on total billable rows delivered across the run (`0` = unlimited; prefill `35`). |
| `minViews` | `integer` | `0` | Keep only message rows where `viewsCount >= minViews` (`0` keeps all messages). |
| `postedAfter` | `string` | `""` | Optional ISO-8601 date cut-off (`YYYY-MM-DD`). Skips older messages and stops backward pagination once crossed. |
| `proxyConfiguration` | `object` | `{"useApifyProxy": true}` | Managed automatically via Apify Proxy. |

**Copy-paste input recipes:**

- **Sponsorship & ad-fraud audit across 50 channels (`channelInfoOnly`):**
  `{"channels":["durov","telegram","toncoin"],"channelMode":"channelInfoOnly","maxResults":50}`
- **Daily high-signal news/crypto feed (`messagesOnly` + `postedAfter` + `minViews`):**
  `{"channels":["durov","telegram"],"channelMode":"messagesOnly","postedAfter":"2026-10-01","minViews":10000,"maxMessagesPerChannel":50,"maxResults":100}`
- **Targeted ticker/keyword search inside channels (`searchQuery`):**
  `{"channels":["telegram"],"searchQuery":"mini apps","channelMode":"messagesOnly","maxMessagesPerChannel":40,"maxResults":40}`

### 📤 Output Schema & Real Sample Record

Every Dataset record includes deterministic `rowKey`, `rowType`, `sourceType`, `input`, `url` and `scrapedAt` columns, plus flat `*Text` companion fields (`photoUrlsText`, `videoUrlsText`, `linksText`, `descriptionLinksText`, `descriptionEmailsText`) for clean one-click CSV/Excel exports.

#### Channel rows (`rowType: "channel"`)

| Field | Type | Description |
|---|---|---|
| `rowKey` | `string` | Deterministic unique key `channel:<channelUsername>` |
| `channelUsername` / `channelId` | `string` / `string \| null` | Normalized lowercase handle and numeric Telegram channel ID |
| `title` / `description` | `string \| null` | Channel display name and public biography |
| `isVerified` / `avatarUrl` | `boolean` / `string \| null` | Official Telegram verification badge and CDN avatar URL |
| `subscribersCount` / `subscribersRaw` | `integer \| null` / `string \| null` | Parsed integer subscriber count (`10700000`) and exact display string (`"10.7M"`) |
| `photosCount` / `videosCount` / `linksCount` / `filesCount` | `integer \| null` | Channel header media counters (`null` when not displayed) |
| `recentMessagesSampled` | `integer` | Count of recent messages sampled to compute engagement metrics |
| `avgViews` / `avgReactions` / `viewRatePct` | `number \| null` | Mean views, mean reactions, and `avgViews / subscribersCount * 100` |
| `descriptionLinks` / `descriptionEmails` | `array<string>` | External websites and lowercased contact emails parsed from the description |

#### Message rows (`rowType: "message"`)

| Field | Type | Description |
|---|---|---|
| `rowKey` | `string` | Deterministic unique key `message:<channelUsername>/<messageId>` |
| `channelUsername` / `channelId` / `messageId` | `string` / `string \| null` / `integer` | Channel handle, numeric channel ID and sequential post number |
| `publishedAt` | `string \| null` | Exact UTC ISO-8601 publication timestamp |
| `text` / `isEdited` / `signatureAuthor` | `string` / `boolean` / `string \| null` | Clean message body text, edit indicator and optional author signature |
| `viewsCount` / `viewsRaw` | `integer \| null` / `string \| null` | Parsed integer view count (`4690000`) and raw counter (`"4.69M"`) |
| `totalReactionsCount` / `paidStarsCount` | `integer \| null` | Total reaction count and paid Telegram Stars count (`null` when reaction bar is absent) |
| `reactions` | `array<object>` | Breakdown of each reaction pill (`type`, `emoji`, `customEmojiId`, `count`, `countRaw`) |
| `mediaType` | `string` | `"text"`, `"photo"`, `"album"`, `"video"`, `"voice"`, `"document"`, or `"poll"` |
| `photoUrls` / `videoUrls` / `videoThumbUrl` / `videoDuration` / `voiceUrl` | `array` / `string \| null` | Direct `telesco.pe` CDN media URLs |
| `documentTitle` / `documentExtra` / `pollQuestion` | `string \| null` | Attachment filename/size and poll question text |
| `links` / `linkPreview` | `array<string>` / `object \| null` | Inline URLs and OpenGraph preview card (`url`, `siteName`, `title`, `description`, `imageUrl`) |
| `isForwarded` / `forwardedFromName` / `forwardedFromUrl` | `boolean` / `string \| null` | Forward source attribution |
| `isReply` / `replyToMessageId` / `replyToUrl` | `boolean` / `integer \| null` / `string \| null` | In-channel reply parent reference |

#### Real sample records (from live platform verification `tgszIvDMyxSGuvSny`, 2026-11-14)

```json
{
  "rowKey": "channel:durov",
  "rowType": "channel",
  "sourceType": "channel_info",
  "input": "durov",
  "channelUsername": "durov",
  "channelId": "1006503122",
  "title": "Pavel Durov",
  "text": "Thoughts from the Product Manager / CEO / Founder of Telegram.",
  "description": "Thoughts from the Product Manager / CEO / Founder of Telegram.",
  "isVerified": true,
  "avatarUrl": "https://cdn4.telesco.pe/file/C3pcCOAmC1_HIOTSmNL1m_WQJUHAdAjcsLFFlF2zX_oP5cd2Xy6B6DRJ6OYUVGoC6xiS1S3xnKwk3a_sEXs0ydq-yLUfpy-ooBb0atbcyj5J3S_gpMYVzoUr5E00.jpg",
  "subscribersCount": 10700000,
  "subscribersRaw": "10.7M",
  "photosCount": 56,
  "videosCount": 15,
  "linksCount": 182,
  "filesCount": null,
  "recentMessagesSampled": 15,
  "avgViews": 3950000,
  "avgReactions": 88400,
  "viewRatePct": 36.92,
  "descriptionLinks": [],
  "descriptionLinksText": "",
  "descriptionEmails": [],
  "descriptionEmailsText": "",
  "url": "https://t.me/durov",
  "scrapedAt": "2026-11-14T05:02:21.110Z"
}
```

```json
{
  "rowKey": "message:durov/538",
  "rowType": "message",
  "sourceType": "channel_timeline",
  "input": "durov",
  "channelUsername": "durov",
  "channelId": "1006503122",
  "title": "Pavel Durov",
  "messageId": 538,
  "postKey": "durov/538",
  "url": "https://t.me/durov/538",
  "publishedAt": "2026-08-04T15:20:04.000Z",
  "text": "Today is my birthday. Turning 40...",
  "isEdited": true,
  "signatureAuthor": "Pavel Durov",
  "viewsCount": 4690000,
  "viewsRaw": "4.69M",
  "totalReactionsCount": 94500,
  "paidStarsCount": 17900,
  "reactions": [
    { "type": "paid_stars", "emoji": "⭐", "customEmojiId": null, "count": 17900, "countRaw": "17.9K" },
    { "type": "custom_emoji", "emoji": null, "customEmojiId": "5373223594484587136", "count": 46200, "countRaw": "46.2K" }
  ],
  "mediaType": "text",
  "photoUrls": [],
  "photoUrlsText": "",
  "videoUrls": [],
  "videoUrlsText": "",
  "links": [],
  "linksText": "",
  "linkPreview": null,
  "isForwarded": false,
  "forwardedFromName": null,
  "forwardedFromUrl": null,
  "isReply": false,
  "replyToMessageId": null,
  "replyToUrl": null,
  "scrapedAt": "2026-11-14T05:02:21.114Z"
}
```

Every completed run also writes a `SOURCE_REPORT` record to the default Key-Value Store summarizing per-channel status, HTTP request counts and delivered row totals.

### 🧪 Data Quality — Measured

Verified on the Apify platform across QA runs (`UR72IW420dE8eYLxW`, `n9T5F5ocIOEUq5j7I`, `QuN402s20QKUXZcO9`) and live D+0 billing verification (`tgszIvDMyxSGuvSny`, `fCvPBY38L6bdYgeJ9` on 2026-11-14):

- **100% row uniqueness:** Every channel and message row is deduplicated by `rowKey` (`channel:<handle>` and `message:<handle>/<id>`), delivering `0` duplicates across overlapping `channels` and `postUrls` inputs.
- **Dual numeric + raw fidelity:** Telegram abbreviates large public counters (`"10.7M"`, `"4.69M"`); every row stores both the clean numeric integer (`subscribersCount: 10700000`) for sorting/SQL math and `subscribersRaw` / `viewsRaw` so nothing is overstated.
- **Verified billing accuracy:** In live D+0 verification (`tgszIvDMyxSGuvSny`: `1` channel + `5` messages; `fCvPBY38L6bdYgeJ9`: `1` diagnostic `status` row on empty input), settled `chargedEventCounts` matched `{channel: 1, message: 5}` and `{channel: 0, message: 0}` with `0` discrepancies.

### ⏱️ Performance — Measured

Measured on the Apify platform at the default **`256 MB`** memory tier:

- **Fast pure-HTTP throughput:** Collecting 20 messages + channel analytics takes **2 to 5 seconds** per channel because each page of ~20 messages requires a single lightweight HTTP fetch with zero headless browser startup.
- **Minimal compute footprint:** Peak memory stays well under `120 MB` inside a `256 MB` container, even on multi-hundred-message backward pagination runs.
- **Restart-safe execution:** On container restart or migration, already-written `rowKey` items in the run's Dataset are detected and skipped automatically.

### 💼 Use Cases

1. **Telegram Ad-Buy & Sponsorship Fraud Vetting (`channelInfoOnly`)**
   - *Input:* `{"channels":["durov","telegram","toncoin"],"channelMode":"channelInfoOnly","maxResults":50}`
   - *Output:* One summary row per channel with `subscribersCount`, `avgViews`, `viewRatePct`, `avgReactions`, `descriptionLinks` and `descriptionEmails`.
   - *Business action:* Spot botted channels (e.g. 200K subscribers with `0.4%` `viewRatePct`) before committing sponsorship budgets, and push verified admin contacts to your outreach CRM.

2. **Crypto, Macro & Breaking-News Monitoring (`messagesOnly` + `postedAfter`)**
   - *Input:* `{"channels":["telegram","toncoin"],"channelMode":"messagesOnly","postedAfter":"2026-11-01","minViews":5000,"maxMessagesPerChannel":100,"maxResults":200}`
   - *Output:* High-reach announcements with timestamps, inline links, media URLs and paid Stars counts.
   - *Business action:* Stream breaking exchange listings, governance proposals or geopolitical alerts into trading desks, Slack channels or RAG vector stores.

3. **OSINT & Threat-Intelligence Forwarding Graph Analysis**
   - *Input:* `{"channels":["durov","telegram"],"channelMode":"messagesAndChannelInfo","maxMessagesPerChannel":200,"maxResults":405}`
   - *Output:* Full message timelines with `channelId`, `isForwarded`, `forwardedFromName`, `forwardedFromUrl` and `replyToUrl`.
   - *Business action:* Map cross-channel amplification networks and track primary sources behind viral narratives without joining suspect channels from a personal phone number.

4. **Historical Keyword & CVE Audits (`searchQuery`)**
   - *Input:* `{"channels":["telegram"],"searchQuery":"stars","channelMode":"messagesOnly","maxMessagesPerChannel":50,"maxResults":50}`
   - *Output:* Only the historical posts inside `@telegram` matching `"stars"`.
   - *Business action:* Audit every historical mention of a ticker, protocol name, vulnerability ID or product feature in seconds.

### 🔗 Integrations (Node.js, Python, n8n, Make & Clay)

#### JavaScript / Node.js (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('foxlabs/telegram-channel-scraper').call({
    channels: ['durov', 'telegram'],
    channelMode: 'messagesAndChannelInfo',
    maxMessagesPerChannel: 20,
    maxResults: 50,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Fetched ${items.length} Telegram rows`, items[0]);
```

#### Python (`apify-client` v3)

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("foxlabs/telegram-channel-scraper").call(
    run_input={
        "channels": ["durov", "telegram"],
        "channelMode": "messagesAndChannelInfo",
        "maxMessagesPerChannel": 20,
        "maxResults": 50,
    }
)

for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item["rowType"], item.get("channelUsername"), item.get("viewsCount"), item["url"])
```

*(Written for `apify-client` v3 where `call()` returns a `Run` object exposing `run.default_dataset_id`; on `apify-client` v1/v2 use `run["defaultDatasetId"]`.)*

#### n8n, Make, Zapier & Clay

- **Automated feed ingestion (n8n / Make / Zapier):** Run every 15–60 minutes with `channelMode: "messagesOnly"` and `maxMessagesPerChannel: 15` → deduplicate on `rowKey` (`message:<channel>/<id>`) → push new posts into Discord, Slack, Telegram alerts, Airtable or Supabase.
- **Clay channel enrichment:** Query `https://foxlabs--telegram-channel-scraper.apify.actor/channels?channels={{handle}}` from Clay to enrich Web3/community prospect tables with `subscribersCount`, `viewRatePct` and `descriptionEmails`.

### 📊 Pricing (Pay-Per-Event)

Transparent **Pay-Per-Event (PPE)** billing — no monthly rental fees and **zero extra per-image or per-video surcharges**:

| Event Name | Trigger | Price per Item | Price per 1,000 |
|---|---|---|---|
| `channel` | Once per unique `rowType: "channel"` profile summary delivered | **$0.0020** | **$2.00 / 1,000** |
| `message` | Once per unique `rowType: "message"` post delivered (all media & reactions included) | **$0.0008** | **$0.80 / 1,000** |
| `status` *(diagnostic)* | Invalid handle, private/no-preview channel, or zero-match filter note | **$0.00 (Free)** | **$0.00** |

**Worked cost examples:**

- **100 channels audited for subscriber & `viewRatePct` metrics (`channelInfoOnly`):** `100 × $0.0020` = **$0.20**
- **10 channels × (1 channel header + 50 messages each):** `10 × $0.0020 + 500 × $0.0008` = **$0.42**
- **1,000 historical messages (`messagesOnly`):** `1,000 × $0.0008` = **$0.80**

**Billing guarantees:**

- **Media, reactions & link previews are included:** Photos, albums, MP4 video links, emoji reactions and paid Stars counters never trigger hidden add-on events.
- **Proxy traffic is included:** Apify Proxy traffic runs inside our environment at no separate proxy charge to your account.
- **Budget ceiling enforced:** Set **Maximum cost per run** in Apify options; `ChargingManager` checks your remaining budget before emitting each batch and stops cleanly at your limit. *(Note: if Apify applies its platform `apify-actor-start` fee on your plan, that platform start event applies when a run starts, including runs that deliver zero billable rows.)*

### ❓ Frequently Asked Questions (FAQ)

#### Do I need a Telegram phone number, `api_id`, `api_hash`, or session string?

No. The Actor reads publicly broadcast Telegram web pages and post widgets directly on our infrastructure. You never supply phone numbers, SMS codes, MTProto `api_id` / `api_hash` keys, session strings or custom proxies, which means zero setup friction and zero risk of getting a personal or company Telegram account banned.

#### Can this Actor scrape private invite links (`t.me/+…`), secret chats, or group member lists?

No. Private invite-only channels (`t.me/+…` or `t.me/joinchat/…`), standard group chats without public broadcast previews, personal user accounts, and subscriber rosters are protected behind authenticated Telegram membership. When given one of those links, the Actor writes a free `rowType: "status"` diagnostic row explaining why and continues processing the rest of your batch cleanly.

#### What happens if a public channel has disabled web message previews?

Channel administrators on Telegram can keep a handle public while disabling the browser message timeline preview. When that setting is active, Telegram still serves the public channel card (`title`, `subscribersCount`, `description`, `avatarUrl`), so the Actor delivers the `channel` profile row (unless `channelMode: "messagesOnly"`) alongside a free diagnostic `status` row noting that web message history is disabled for that channel.

#### How far back in history can `maxMessagesPerChannel` paginate?

Initial channel preview pages show up to 20 recent messages, and setting `maxMessagesPerChannel` above 20 causes the Actor to step backwards through older message batches (~20 messages per request) up to `2,000` messages per channel in a single run. Pagination stops early automatically as soon as `postedAfter` or `maxResults` is reached, or when the very first message of the channel is reached.

#### How do I get the numeric Telegram `channelId` for Bot API or MTProto cross-referencing?

Every `channel` and `message` row includes `channelId` (for example `"1006503122"` for `@durov`) whenever Telegram exposes peer metadata on the channel's public posts. In Telegram Bot API and MTProto peer notation, public broadcast channels prefix that numeric ID with `-100` (so `"1006503122"` corresponds directly to peer ID `-1001006503122`), making it easy to join scraped datasets with downstream bot or database tables.

#### Why are `subscribersCount` and `viewsCount` rounded on multi-million-subscriber channels?

Telegram's public web interface displays large counters in compact human-readable form such as `"10.7M"` or `"46.2K"`, while smaller channels display exact integers like `"8421"`. To keep your spreadsheets sortable without hiding how Telegram reported the figure, every row provides both the parsed integer (`subscribersCount: 10700000`, `viewsCount: 4690000`) and the exact raw label (`subscribersRaw: "10.7M"`, `viewsRaw: "4.69M"`).

#### Why are `totalReactionsCount` and `paidStarsCount` `null` on certain messages?

When a post has zero reactions or when a channel administrator disables reactions altogether, Telegram omits the reaction container from the rendered message card. Because an omitted reaction bar can mean either "reactions disabled" or "no reactions yet", the Actor emits `null` rather than guessing `0`, and outputs exact counts (`totalReactionsCount`, `paidStarsCount`, and the `reactions[]` array) whenever reaction pills exist.

#### Do `photoUrls` and `videoUrls` CDN links expire over time?

Direct `cdn*.telesco.pe` media URLs returned on message rows carry temporary CDN signature tokens, particularly for inline MP4 videos and voice notes. If your workflow needs long-term archival copies of images or videos (for OSINT evidence preservation or dataset archiving), download the media files shortly after your run finishes rather than storing the raw CDN URLs indefinitely.

#### Why is `videoUrls` occasionally empty even when `mediaType` is `"video"`?

Telegram's public web preview embeds inline playable `<video>` streams only for video files below Telegram's web-embed size limit (roughly ~20 MB); larger broadcast videos display a "View in Telegram" overlay instead of a direct MP4 stream. For those oversized videos, the Actor still sets `mediaType: "video"` and captures `videoThumbUrl` and `videoDuration` while leaving `videoUrls` as `[]`.

#### How do I fetch only specific `postUrls` without scraping the prefilled channels?

In the Apify Console, remove the prefilled items in **Channels** before clicking Start. When calling via the API, Python/JS SDK, or MCP, pass `"channels": []` explicitly alongside `"postUrls": ["https://t.me/durov/538"]` so only your target message links are fetched.

#### How does `viewRatePct` help detect fake subscribers before buying Telegram ads?

`viewRatePct` divides `avgViews` across the channel's sampled recent posts by `subscribersCount` (`× 100`). Healthy organic broadcast channels typically show consistent view rates relative to their niche and posting cadence, whereas channels inflated with purchased bot subscribers often show stark anomalies (such as 500,000 subscribers paired with `0.2%` view rates or unnatural flat-line view counts across consecutive posts).

#### Is the Actor safe against duplicate rows and double charges if a run restarts?

Yes. Every channel row is keyed by `channel:<channelUsername>` and every message row by `message:<channelUsername>/<messageId>`. If Apify migrates or restarts your container mid-run, the Actor reads the existing `rowKey` set from the run's Dataset before resuming and skips any record already delivered, guaranteeing zero duplicate rows and zero double charges.

### 🐛 Troubleshooting

- **Dataset returned only a `rowType: "status"` row with `"Empty input"`:** You passed `"channels": []` without providing any `postUrls`. Add at least one public channel handle/URL or direct post URL.
- **Channel returned `rowType: "channel"` plus a `status` note about disabled preview:** That channel's admin turned off public `/s/` web history, or the handle belongs to a group/bot rather than a public broadcast channel.
- **Fewer messages delivered than `maxMessagesPerChannel`:** Check `maxResults` (overall run cap, default `100`), `minViews`, and `postedAfter`, or check `SOURCE_REPORT` in the Key-Value Store to see whether the channel has fewer total messages or fewer matches for `searchQuery`.
- **Invalid date error row:** Ensure `postedAfter` follows strict `YYYY-MM-DD` format (e.g. `"2026-10-15"`).

### 🚧 What It Does Not Do

- Does **not** join or scrape private invite-only Telegram channels (`t.me/+…` / `joinchat`).
- Does **not** extract group chat member lists, user phone numbers, or linked discussion-group comment threads.
- Does **not** download multi-hundred-megabyte video binaries hosted exclusively inside authenticated MTProto clients.

### ⚠️ Trademark Notice

This Actor is an independent data-collection tool developed by **foXLabs** and is not affiliated with, endorsed by, or sponsored by Telegram FZ-LLC. "Telegram" is a trademark of Telegram FZ-LLC, referenced strictly to describe compatibility with publicly accessible `t.me` web pages.

### ⚖️ Is It Legal to Scrape Public Telegram Channels?

This Actor reads only publicly broadcast `t.me` web pages that Telegram serves to any unauthenticated browser visitor — never private groups, invite-only channels, member rosters or direct messages. Public posts and channel biographies may still contain personal data (such as names, handles or contact emails) subject to GDPR, CCPA and local privacy laws; ensure your downstream storage and use have a valid lawful basis.

### 🤝 Support, Custom Data & Contact

- 🌐 **Website & full portfolio:** [data.foxlabs.com.tr](https://data.foxlabs.com.tr)
- 📧 **Custom data & enterprise inquiries:** info@foxlabs.com.tr
- 🐛 **Bug reports & feature requests:** open an issue in the Actor's **Issues** tab on Apify Store (include your Run ID)
- 🧰 **Browse all foXLabs Actors:** [apify.com/foxlabs](https://apify.com/foxlabs)

### Changelog

#### 0.1.2 — 2026-11-14

- Upgraded Store README to full SIÁN standard with MCP & x402 AI agent setup, Standby HTTP query examples, measured platform QA & D+0 billing verification metrics, worked PPE cost examples, and expanded 12-question FAQ.

#### 0.1 — 2026-11-13

- Initial release of `foxlabs/telegram-channel-scraper` supporting public channel analytics (`subscribersCount`, `channelId`, `viewRatePct`), multi-page backward message pagination, in-channel keyword search, emoji & paid Telegram Stars reactions, rich media URLs, and Batch + Standby HTTP modes.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/telegram-channel-scraper/changelog.md

# Actor input Schema

## `channels` (type: `array`):

Public Telegram channel handles or URLs (e.g. 'durov', '@telegram', 'https://t.me/toncoin', 'https://t.me/s/durov').

## `searchQuery` (type: `string`):

Optional keyword or phrase to search inside each channel in 'channels' (uses Telegram's public ?q= channel search). Leave empty for full chronological timeline.

## `postUrls` (type: `array`):

Optional direct Telegram post URLs (e.g. 'https://t.me/durov/538') to fetch individual messages directly.

## `channelMode` (type: `string`):

Choose whether to emit both channel summary + messages, messages only, or channel summary rows only.

## `maxMessagesPerChannel` (type: `integer`):

Maximum messages to collect per channel (paginates backwards automatically past the initial 20 messages).

## `maxResults` (type: `integer`):

Overall cap on delivered rows across the entire run (0 = unlimited).

## `minViews` (type: `integer`):

Keep only messages whose viewsCount is at least this number (0 keeps all).

## `postedAfter` (type: `string`):

Optional ISO date cut-off (e.g. '2026-01-01'). Older messages are skipped and backward pagination stops once passed.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Public Telegram pages work out of the box on default Apify Proxy.

## Actor input object example

```json
{
  "channels": [
    "durov",
    "telegram"
  ],
  "channelMode": "messagesAndChannelInfo",
  "maxMessagesPerChannel": 15,
  "maxResults": 35,
  "minViews": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "channels": [
        "durov",
        "telegram"
    ],
    "maxMessagesPerChannel": 15,
    "maxResults": 35,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/telegram-channel-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "channels": [
        "durov",
        "telegram",
    ],
    "maxMessagesPerChannel": 15,
    "maxResults": 35,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/telegram-channel-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "channels": [
    "durov",
    "telegram"
  ],
  "maxMessagesPerChannel": 15,
  "maxResults": 35,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call foxlabs/telegram-channel-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,foxlabs/telegram-channel-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/058tg45slC0EoHbpk/builds/KYURg5SDhX5WvmRqt/openapi.json
