# Telegram Channel Scraper & Keyword Monitor (`ax_dev/telegram-channel-monitor`) Actor

Scrape public Telegram channels and monitor them for keywords — no API key, no phone, no login. Get posts, views, reactions, media & subscriber counts as clean JSON. Reliable retries, multi-channel keyword alerts, MCP-ready output for brand monitoring, crypto, OSINT & AI agents.

- **URL**: https://apify.com/ax\_dev/telegram-channel-monitor.md
- **Developed by:** [Alexandr Maier](https://apify.com/ax_dev) (community)
- **Categories:** Social media, AI, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Telegram Channel Scraper & Keyword Monitor

Scrape **public Telegram channels** and monitor them for keywords — **no API key, no phone number, no login**. Built for reliability and for AI agents: clean, flat, predictable JSON on every run.

This actor reads Telegram's public web preview (`t.me/s/<channel>`), the same data any browser sees when you open a channel without an account. It never logs in, never touches your Telegram account, and never asks for a phone number.

### Why this one

Most Telegram actors do the same basic dump. Two things break them in production, and this actor fixes both:

- **They crash on rate limits.** This actor retries every request with exponential backoff and can fall back to Apify Proxy, so a long run finishes instead of dying at channel #7.
- **They only scrape, they don't watch.** Monitor mode remembers the last post it saw per channel and returns *only new posts* on each scheduled run — turn any channel list into a keyword alert feed.

### What you get per message

```json
{
  "channel": "durov",
  "channelTitle": "Pavel Durov",
  "channelSubscribers": 11700000,
  "id": 510,
  "url": "https://t.me/durov/510",
  "datetime": "2026-05-12T17:28:39+00:00",
  "text": "🌍 With 400 validators across 6 continents, TON is one of the most…",
  "views": 3440000,
  "reactions": [{ "emoji": "🔥", "count": 12045 }],
  "media": ["photo"],
  "forwardedFrom": null,
  "links": ["https://ton.org"],
  "matchedKeywords": ["ton"],
  "scrapedAt": "2026-07-10T12:00:00.000Z"
}
```

### Input

| Field | Type | Description |
|---|---|---|
| `channels` | array **(required)** | `@name`, `name`, or `https://t.me/name` |
| `keywords` | array | Save only posts containing a keyword (case-insensitive). Empty = save all |
| `keywordMatch` | `substring` | `word` | Substring (default) or whole-word matching |
| `mode` | `scrape` | `monitor` | `scrape` = history; `monitor` = only new posts since last run |
| `maxPostsPerChannel` | integer | Cap on posts scanned per channel (default 100) |
| `postsNewerThan` | ISO date | Stop paging once older posts are reached |
| `minViews` / `minReactions` | integer | Skip low-engagement posts |
| `useProxy` | boolean | Route via Apify Proxy (only needed for large jobs) |

#### Example: monitor three news channels for a brand

```json
{
  "channels": ["telegram", "durov", "bloomberg"],
  "keywords": ["bitcoin", "regulation", "SEC"],
  "keywordMatch": "word",
  "mode": "monitor"
}
```

Schedule this every 15 minutes and the dataset fills only with new, on-topic posts.

### Use cases

- **Brand & crypto monitoring** — alert when your project, ticker, or competitor is mentioned across channels.
- **OSINT & news** — track announcements from public channels into a structured feed.
- **AI agents (MCP)** — flat JSON output plugs straight into a RAG pipeline or an MCP tool call ("what did channel X post about Y this week?").
- **Research & analytics** — export engagement (views, reactions) over a channel's history.

### Pricing (pay-per-event)

| Event | Price |
|---|---|
| Actor start | $0.005 |
| Message saved | $0.0002 |

You pay only for messages that pass your filters. Scraping 1,000 matching posts costs about **$0.20 + $0.005 = $0.205**. No monthly subscription; the Apify free tier covers testing.

### Limits & honest notes

- Works only with **public** channels that have web preview enabled. Private channels, groups, and comments are not accessible (and scraping them would require an account — out of scope by design).
- `t.me/s/` serves ~20 posts per page; the actor paginates backward through history up to your limit.
- Reads public preview data only. This actor does **not** use MTProto, does not collect member lists, and does not require your credentials.
- You are responsible for complying with Telegram's Terms and applicable law in your use of the data.

### Local development

```bash
npm install
apify run -p           # requires apify-cli and Docker/Node 18+
```

`src/parser.js` isolates all HTML parsing — if Telegram ever changes its preview markup, that single file is the only thing to update.

# Actor input Schema

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

Public Telegram channels to scrape. Accepts @name, name, or https://t.me/name.

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

If set, only messages containing at least one keyword are saved. Case-insensitive. Leave empty to save every message.

## `keywordMatch` (type: `string`):

substring = keyword anywhere in text; word = whole-word match only.

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

scrape = fetch history up to the limit. monitor = on each run, save only posts newer than the previous run (dedup state kept per channel). Use monitor on a schedule for alerts.

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

Upper bound on posts scanned per channel (paginates backward through history).

## `postsNewerThan` (type: `string`):

ISO date/time cutoff (e.g. 2026-01-01). Stops paging once older posts are reached.

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

Skip posts below this view count (0 = no filter).

## `minReactions` (type: `integer`):

Skip posts with fewer total reactions (0 = no filter).

## `useProxy` (type: `boolean`):

Route requests through Apify Proxy. Recommended only for large jobs — t.me/s/ usually needs no proxy.

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

Advanced proxy settings (overrides 'Use Apify Proxy').

## Actor input object example

```json
{
  "channels": [
    "@durov",
    "telegram",
    "https://t.me/whitehouse"
  ],
  "keywords": [],
  "keywordMatch": "substring",
  "mode": "scrape",
  "maxPostsPerChannel": 100,
  "minViews": 0,
  "minReactions": 0,
  "useProxy": false
}
```

# 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"
    ],
    "keywords": []
};

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

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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"
  ],
  "keywords": []
}' |
apify call ax_dev/telegram-channel-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ax_dev/telegram-channel-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ubcZN8TAMnvWeN9xf/builds/yFBOrIvdjQY6HMifF/openapi.json