# Telegram Channel Scraper — New Posts & Google Sheets (`humming_cobalt/telegram-channel-watch`) Actor

Monitor public Telegram channels or export a date range with saved progress. Collect posts, reactions and channel data, with spending limits and status reports. Send results to Google Sheets using our free n8n workflow. No Telegram login required.

- **URL**: https://apify.com/humming_cobalt/telegram-channel-watch.md
- **Developed by:** [Albert Albesa Gonzalez](https://apify.com/humming_cobalt) (community)
- **Features:** Limited permissions
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.00 / 1,000 delivered telegram posts

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

## Telegram Channel Scraper — New Posts & Google Sheets

**Stop collecting the same history. Understand empty results. Recover when a run stops.**

Collect posts from public Telegram channels with saved progress, explicit status reports, and spending limits. Use the JSON/CSV API directly or send results to Google Sheets with the free n8n workflow. No Telegram login, phone number, or bot token is required.

**[Get the free workflow and setup guide →](https://humming-cobalt.github.io/telegram-to-google-sheets/)** · **[Watch the 90-second demo →](https://humming-cobalt.github.io/telegram-to-google-sheets/#demo)**

The workflow adds new rows and updates matching post IDs when you retry an import. If a Sheets write fails, resume the original run's dataset instead of collecting the same history again. The Actor also works on its own with JSON and CSV exports, including a resumable historical date-range mode.

### Built for the problems that make Telegram scraping frustrating

| The problem | How this Actor helps |
|---|---|
| **“Every run collects the same posts again.”** | Keep the same monitor ID to continue from saved progress. Every post has a stable `id`; the Sheets workflow updates matching IDs on sequential re-imports. A crash can replay a batch, so API consumers should also upsert by `id`. |
| **“I got zero results. Is it broken?”** | The report distinguishes a saved starting checkpoint, no new posts, date exclusions, keyword exclusions, and an unfinished scan. Observed publication dates help you see whether the channel has recent activity. |
| **“I only want posts between these dates.”** | Historical exports use an inclusive start and exclusive end, accept explicit timezones, and resume across page, post, or spending limits. Dates without a time mean midnight UTC. |
| **“The run stopped halfway through.”** | Saved progress lets the next collection continue. `PARTIAL`, `pauseReason`, and `nextAction` explain what remains. Keep every run's dataset; a new collection does not re-deliver rows already checkpointed. |
| **“One bad channel breaks my whole feed.”** | Source errors are reported per channel, while successful-channel rows are retained. Run-wide work or budget limits can still leave later channels unchecked; the report identifies them. |
| **“My spreadsheet failed after the scraper finished.”** | Set the workflow's `resumeRunId` to re-import the saved dataset without starting another Actor collection. The final error includes the affected channel or original error code and recovery guidance. |
| **“A file-only post looks empty.”** | Visible document cards retain filenames and sizes, including multi-file posts. Missing download URLs are explicit; a Telegram post link is never presented as a file download. |
| **“Retries ignore Telegram's rate limit.”** | Short server-requested waits are honored. Long cooldowns stop the current attempt with `RETRY_LATER` and `retryAfterSeconds`, instead of retrying early. Your scheduler should respect that delay before another run. |
| **“I don't want an open-ended bill.”** | Set a per-run event cap. Collection saves progress when the remaining budget cannot cover another post. Each new run still has a start fee, including empty or failed runs; limits reset for each run. |

#### Clear results for your application

Use the dataset for posts and **Channel status report** (`REPORT`) to decide what happens next. A green platform run alone does not mean the full scan finished.

- `COMPLETE` or `EMPTY`: this check finished. An empty result includes a per-channel `emptyReason`.
- `PARTIAL`: keep the available rows and inspect each channel's `nextAction` before continuing.
- `FAILED`: read the original error; fix invalid input or an unavailable source before retrying.
- `RESUME_SAME_INPUT`: start a new collection using the same monitor ID and filters. Another start fee applies.
- `RETRY_LATER`: wait for the reported source cooldown before another collection.

**Two different retries, made explicit:** re-importing a saved run repairs a downstream import; starting a new Actor run collects more posts. The workflow tells you which operation you need.

#### Tested against these failure cases

The 14 October 2026 release passed **99 automated checks**, including date boundaries, interrupted delivery, saved-progress resumption, empty results, and rate-limit handling. Three cloud acceptance runs verified capped-run guidance, empty-window explanations, and visible document metadata. The Sheets import path was also previously checked with 34 posts: importing twice kept 34 unique rows, and restoring a missing destination tab allowed recovery from the original saved run.

These are bounded checks, not an uptime or completeness guarantee. This Actor reads **public channel web previews**. It does not access private channels, recover deleted posts, download document files without exposed sources, or continuously refresh edits and engagement counts. The Sheets workflow supports one writer at a time.

### See the result before you connect

Your sheet includes `id`, `channel`, `publishedAt`, `text`, `url`, `views`, and `runId`. Available media links remain in the Actor dataset. The captioned demo shows actual Google Sheets test results.

Example sheet layout (illustrative values):

| id | channel | publishedAt | text | url | views | runId |
|---|---|---|---|---|---:|---|
| example_channel/42 | example_channel | 2026-10-14T09:00:00Z | A new update is available. | Original post link | 1250 | Your Apify run ID |

| Workflow check | Observed result |
|---|---|
| Import a saved run | 34 posts written to Google Sheets |
| Import that run again | Still 34 rows with 34 unique IDs |
| Destination tab missing | Import stops with a clear error |
| Restore the tab and retry the original run | All 34 posts present |
| Quiet channel check | Completes with zero new rows |

These checks were performed on 14 October 2026. The demo is an edited walkthrough of those checks. It does not promise exactly-once delivery or cover simultaneous writers. Keep one workflow writing to a sheet at a time and match rows by `id`.

### What you receive

- Post text, publication time, original Telegram URL, and stable post ID.
- Available photo, video, and audio links; displayed view counts and their original text.
- Visible document filenames and sizes, including multi-document posts. Download availability is stated explicitly.
- Visible reactions, custom emoji IDs, and paid Stars kept separately.
- Channel description, subscriber count, verification badge, avatar, and media counters where exposed.
- Author, edited/forwarded flags, reply context, and link previews where present.
- Progress saved independently for each channel, including when another channel fails.
- Optional keyword matching, watching from now, and resumable exports between exact dates.
- JSON/CSV dataset exports and a machine-readable status report.

No Telegram login, phone number, or bot token is required. The Actor reads public web previews at `https://t.me/s/CHANNEL`.

### Quick start

1. For a first test, keep the prefilled public news channel `bbcrussian`, or enter 1–10 public channel handles or channel links. Replace the sample with your own sources when ready.
2. Give the feed a monitor ID, for example `news-desk`.
3. Choose **Include recent posts** or **Start watching from now**.
4. Set the maximum event charge for the run. The default is $0.20.
5. Run once. Inspect both **New posts** and **Channel status report**.
6. Repeat with the same monitor ID to continue. Use an Apify task or an external workflow for scheduling; this Actor does not install a schedule itself.

```json
{
  "channels": ["bbcrussian"],
  "monitorId": "news-desk",
  "firstRunMode": "recent",
  "initialLookbackHours": 24,
  "keywords": [],
  "maxPostsPerChannel": 100,
  "maxPagesPerChannel": 10,
  "requestDelayMs": 600,
  "maxChargeUsd": 0.20
}
```

The prefilled news channel is an example source, not an affiliation. Result counts depend on recent activity and preview availability. Repeat with the same monitor ID: an empty result with `NO_NEW_POSTS` is a healthy check when nothing new has appeared. `from_now` deliberately returns no history on its first check. Use a new monitor ID to test a separate feed; do not change it on every scheduled run.

### Export a historical date range

Choose **Export a date range**, enter a start and end date, and give the export its own ID. The start is inclusive; the end is exclusive. Dates without a time mean midnight UTC. For example, this collects posts published on 12 and 13 October:

```json
{
  "channels": ["bbcrussian"],
  "mode": "history",
  "monitorId": "news-oct12-13",
  "fromDate": "2026-10-12",
  "toDate": "2026-10-14",
  "maxPostsPerChannel": 100,
  "maxPagesPerChannel": 10,
  "maxChargeUsd": 0.20
}
```

Repeat the **same input** when the report is partial. Combine each run's dataset by stable `id`. `historyComplete: true` and each channel's `HISTORY_COMPLETE` status mean the selected public-preview scan is finished. Repeating a completed export returns zero new rows; a run-start fee still applies. Stop scheduling it once complete.

History has separate saved progress from Monitor, even with the same ID, so a backfill cannot move an existing monitor's checkpoint. Use a new ID if you change the dates or keywords, or want a fresh snapshot. `firstRunMode` and `initialLookbackHours` apply to Monitor mode; leave first-run mode at Recent for History. ISO timestamps with explicit timezones are accepted.

Exports scan backwards from the latest visible page. Old ranges may require several runs that return no posts while traversing newer history; each run still incurs its start fee. Only Telegram's accessible web history can be collected. Completion does not guarantee an exhaustive archive, and completed exports do not refresh later edits, reaction changes, or future posts within a future-dated window.

### Engagement and channel context

The JSON dataset includes `reactions`, `reactionsTotal`, `paidStars`, `author`, `isEdited`, `isForwarded`, `forwardedFrom`, `replyTo`, `linkPreview`, and `channelInfo`. The **Engagement & context** dataset view provides a quick summary. `channelInfo` includes subscriber and media counts, description, avatar, and visible verification status; it is also available in each checked channel's report, including quiet monitor runs.

These are snapshots at collection time. Telegram often rounds counts: both numeric estimates and original labels are retained. Missing reaction counts are `null`, not a claim of zero engagement. Custom emoji IDs are kept as strings; the visible emoji may be unavailable. Paid Stars are separate from ordinary reaction totals. Reply context is quoted content, not a scraped comment thread. Edited flags describe the observed post; ongoing monitors do not re-emit old posts when they change.

The existing free Google Sheets workflow keeps its seven familiar columns. The extra fields remain in the Actor dataset and can be mapped into additional columns in your own workflow. No extra event fee is charged for enrichment.

Document cards appear in `documents`, with `fileName`, `sizeText`, the original post `sourceUrl`, and explicit download availability. For cards without a public file source, `downloadUrl` is `null` and `downloadAvailable` is `false`. The post link opens Telegram; it is not a file download. `media` continues to contain only exposed photo, video, and audio URLs.

### Pricing

| Event | Price |
|---|---:|
| Run start, up to 10 channels | $0.005 per run |
| Delivered post | $0.001 each ($1 per 1,000) |
| Channel status or error report | No additional event charge |

The start fee applies to empty runs, invalid inputs that start a run, failed runs, and overlapping runs rejected by the monitor lock. Post fees apply only after post rows have been saved to the dataset. There is no minimum bundle of 1,000 posts. Standard run compute is included in these event prices; your Apify subscription, retained storage, downstream API reads, and other services may have their own charges.

For example, one run delivering 25 posts costs $0.03 in Actor events. Hourly checks over a 30-day month plus 10,000 posts cost $13.60 in Actor events. These are usage examples, not subscriptions or monthly caps. Check the live Apify pricing panel before running.

### Spending and work limits

The Actor uses the lower of `maxChargeUsd` and Apify's run spending limit, including the run-start fee already charged by the platform. When there is insufficient room for another post, it saves progress and reports `BUDGET_REACHED`. A new run has a new budget and another start fee. The start fee is automatic and cannot be undone by input validation; choose a platform limit that covers it before starting.

Each cloud run also limits work to 10 channels, 10 pages per channel, 20 source requests in total including retries, 1 MiB per source response, and 10 MiB of source body data in total. Collection stops at a 90-second deadline; reporting and storage cleanup can take additional time. Memory is fixed at 512 MB. Use a 180-second platform timeout. Unfinished work resumes on another run. Page and post limits are maximums, not promises of output volume.

### Read the status report

| Status | Meaning |
|---|---|
| `HISTORY_COMPLETE` | Fixed date-range scan finished; stop or use a new export ID |
| `NEW_POSTS` | Posts delivered and this scan completed |
| `NO_NEW_POSTS` | Successfully checked; no new posts |
| `NO_MATCHES` | New posts did not match your keywords |
| `BASELINED` | First `from_now` check saved a starting point |
| `CATCHING_UP` | Page or post cap reached; repeat to continue |
| `BUDGET_REACHED` | No budget for another paid post; repeat with an appropriate budget |
| `REQUEST_LIMIT`, `TIME_LIMIT`, `TRANSFER_LIMIT` | Work bound reached; saved work can continue |
| `NOT_CHECKED` | An earlier run-wide stop prevented checking this channel |
| `ERROR` | Read the channel's error code and explanation |

Report version 4 adds a human-readable `summary` and per-channel `message`, `nextAction`, `emptyReason`, and `pauseReason`. Existing status codes and saved progress remain compatible. Each checked channel also has `diagnostics`: source posts observed during this run, oldest/newest observed publication dates, and the count excluded by the date window. These counters describe fetched pages, not a guarantee of complete history; a run can deliver saved buffered posts without fetching a new page.

An empty run explains whether it saved a starting checkpoint, found no posts inside the date window, filtered posts by keywords, or still has history to scan. `RESUME_SAME_INPUT` means start a new collection run with the same monitor ID and filters. A partial dataset should still be imported and retained. If Telegram requests a long cooldown, the channel reports `RETRY_LATER` with `error.retryAfterSeconds`; the Actor does not shorten that delay and retry prematurely.

Keywords match case-insensitive substrings in post text. For example, `AI` also matches “details” and “contains”; it is not a whole-word or semantic filter.

The overall report is `COMPLETE`, `EMPTY`, `PARTIAL`, or `FAILED`. A green Apify run can contain a `PARTIAL` report. Always inspect the report. A hard timeout or kill may leave saved posts without a final report: also check the platform run status and retain its dataset.

### Progress and recovery

Reuse a monitor ID within the same account and Actor. A new monitor ID starts a separate feed. Change keywords, initial lookback, or first-run mode by starting a new monitor ID. Adding a channel begins its first scan; removing and later re-adding it resumes its saved position. Do not delete the monitor's named storage unless you intend to reset progress.

Normal repeated runs return only newly collected posts. A crash between delivery and checkpointing can repeat a batch. **Upsert or deduplicate by `id`**, such as `telegram/460`; do not rely on exactly-once delivery. If a delivery or billing attempt is uncertain, its recovery replay has no additional post fee, even if the first attempt was never charged. Each new run still has a start fee. Separate monitor IDs can intentionally collect and charge for the same source post.

Collect the datasets from every run, including failed and partial runs. Starting another Actor run cannot recover rows already checkpointed but lost by a downstream integration. If a Google Sheets write fails, retry importing that same run's dataset.

Overlapping runs with the same monitor ID are rejected. After a forced stop, wait up to 180 seconds for the monitor lock to expire. Posts are collected newest-first within pages; sort by publication time for chronological display. Posts arriving during a longer catch-up are found by a subsequent scan.

### Supported content and limitations

Only public channels with readable web previews are supported. Visibility inside the Telegram app does not guarantee an accessible web preview. Private groups, member lists, comments, sending messages, and tracking edits or deletions are outside this release. Content removed before a check cannot be recovered.

Views, subscriber counts, reactions, and Stars can be rounded by Telegram. Media URLs can expire; files are not downloaded. Document filenames and sizes are retained when visible, but document files without public direct sources cannot be downloaded. `contentUnavailable` flags explicit unavailable-content notices; it is not a completeness guarantee. Telegram may change its HTML or restrict access, requiring maintenance. There is no proxy support or uptime guarantee in this beta.

### Automation demo

The free [n8n workflow and setup guide](https://humming-cobalt.github.io/telegram-to-google-sheets/) (tested with live Google Sheets imports, repeat imports, and destination-failure recovery) starts or resumes an Apify run, waits for its terminal status, reads its report and dataset, and upserts posts into Google Sheets by `id`. It surfaces partial or failed runs after saving available rows. Configure your own credentials and sheet before enabling it. The linked 90-second demo shows the live workflow checks described above. Google Sheets requires your own Google connection; the Actor does not write to Sheets without the separate workflow. Keep failed-run datasets so their imports can be retried.

For support, use the Actor's Issues tab and include the run ID, affected channel, and error code. Never include API tokens or private messages.

# Actor input Schema

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

1–10 public channel usernames, @handles, or t.me channel links. The prefilled news channel is a sample; replace it with your own sources. No private invites, groups, or individual post links.

## `mode` (type: `string`):

Monitor continues from saved positions. History exports a fixed date range with separate progress; repeat the same input to resume.

## `monitorId` (type: `string`):

Reuse this ID to resume. Monitor and History progress are separate, even with the same ID. Use a new ID for changed filters or a different historical date range.

## `firstRunMode` (type: `string`):

For Monitor mode only. Recent collects the first-run lookback; From now saves a starting position. In History mode leave this at Recent.

## `initialLookbackHours` (type: `integer`):

For Monitor mode with Recent selected only. History mode uses its explicit start and end dates.

## `keywords` (type: `array`):

Return posts containing any of these phrases (case-insensitive substring match). Empty means all posts. Use a new monitor ID if you change the keywords.

## `maxPostsPerChannel` (type: `integer`):

Unfinished work is saved for the next run. The report says CATCHING_UP until the backlog is complete.

## `maxPagesPerChannel` (type: `integer`):

Up to 10 pages per channel. Across the run: at most 20 source requests including retries, 10 MiB of source data, and 90 seconds of collection work. Unfinished work resumes on the next run.

## `requestDelayMs` (type: `integer`):

Conservative pacing. Temporary errors and rate limits are retried with additional delays.

## `maxChargeUsd` (type: `number`):

Limit this run’s Actor event charges, including the start fee. The lower of this and Apify’s maximum cost applies. The platform start fee applies even to empty or failed starts.

## `fromDate` (type: `string`):

Required in History mode. YYYY-MM-DD means midnight UTC; or use an ISO timestamp with timezone. Example: 2026-10-01.

## `toDate` (type: `string`):

Required in History mode. To include all of 1 October use 2026-10-02. A completed export does not refresh later edits or posts; use a new ID for a new snapshot.

## Actor input object example

```json
{
  "channels": [
    "bbcrussian"
  ],
  "mode": "monitor",
  "monitorId": "main",
  "firstRunMode": "recent",
  "initialLookbackHours": 24,
  "keywords": [],
  "maxPostsPerChannel": 100,
  "maxPagesPerChannel": 10,
  "requestDelayMs": 600,
  "maxChargeUsd": 0.2
}
```

# Actor output Schema

## `posts` (type: `string`):

No description

## `report` (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": [
        "bbcrussian"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("humming_cobalt/telegram-channel-watch").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": ["bbcrussian"] }

# Run the Actor and wait for it to finish
run = client.actor("humming_cobalt/telegram-channel-watch").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": [
    "bbcrussian"
  ]
}' |
apify call humming_cobalt/telegram-channel-watch --silent --output-dataset

```

## MCP server setup

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

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/rm4iUmn6dCIoClTps/builds/c7bxTaAQpWj7EaY1R/openapi.json
