# Telegram Channel Intelligence (`botflowtech/telegram-intelligence`) Actor

- **URL**: https://apify.com/botflowtech/telegram-intelligence.md
- **Developed by:** [BotFlowTech](https://apify.com/botflowtech) (community)
- **Categories:** Social media, Automation, Lead generation
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.0015 / telegram result

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/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 Intelligence — Messages, Channel Info, Search & Keyword Monitor

**Scrape any public Telegram channel's messages, subscriber counts, and analytics. Monitor keywords across channels, discover channels by topic, and extract message history — no API key or login required.**

***

### What It Does

This actor operates in **4 modes**, making it the most versatile Telegram intelligence tool on Apify:

| Mode | Input | What You Get |
|---|---|---|
| **`channel`** | Channel username(s) | Full channel profile (name, description, subscriber count, photo) + recent messages |
| **`search`** | Keyword / topic | Ranked list of public channels related to that topic |
| **`messages`** | Channel username(s) + filters | Bulk message history with date range, minimum views, and keyword filters |
| **`monitor`** | Channel username(s) + keywords | Only messages from the last 24h that match your keywords |

All modes work with **public channels only** — no Telegram login, phone number, or Bot API key needed.

***

### Use Cases

| Who | How They Use It |
|---|---|
| **Crypto traders** | Monitor signal channels (e.g. `@cryptosignals`) for buy/sell alerts in real time |
| **Brand managers** | Track brand mentions across Telegram communities using keyword monitor mode |
| **Journalists & researchers** | Extract full message history from news channels for investigative research |
| **Marketers** | Discover top channels in their niche to identify advertising opportunities |
| **Competitive intelligence** | Monitor competitor announcement channels for product launches and promotions |
| **AI/ML teams** | Collect large text datasets from topic-specific channels for model training |

***

### Example Inputs

#### Mode: `channel` — Channel Profile + Messages

```json
{
  "mode": "channel",
  "channels": ["cointelegraph", "bbcnews"],
  "maxMessages": 100,
  "includeChannelInfo": true
}
```

#### Mode: `search` — Discover Channels by Keyword

```json
{
  "mode": "search",
  "searchQuery": "crypto trading signals"
}
```

#### Mode: `messages` — Bulk Message Scraper with Filters

```json
{
  "mode": "messages",
  "channels": ["cointelegraph", "cryptopanic", "wublockchain"],
  "maxMessages": 500,
  "startDate": "2024-06-01",
  "endDate": "2024-06-30",
  "minViews": 1000
}
```

#### Mode: `monitor` — Keyword Alert Monitor

```json
{
  "mode": "monitor",
  "channels": ["cryptosignals", "whaleAlerts", "bitcoinmagazine"],
  "filterKeywords": ["BTC", "bullish", "buy signal", "short squeeze"]
}
```

***

### Example Output

#### Message Record

```json
{
  "type": "message",
  "messageId": "48291",
  "channelUsername": "cointelegraph",
  "channelName": "Cointelegraph",
  "date": "2024-06-15T09:43:00Z",
  "text": "Bitcoin surges past $70K as institutional demand hits record highs. Analysts expect further rally into Q3 as ETF inflows accelerate.",
  "views": 45200,
  "forwards": 890,
  "repliesCount": 143,
  "hasPhoto": true,
  "hasVideo": false,
  "hasDocument": false,
  "photoUrl": "https://cdn5.telegram-cdn.org/file/abc123.jpg",
  "messageUrl": "https://t.me/cointelegraph/48291"
}
```

```json
{
  "type": "monitor_match",
  "messageId": "12055",
  "channelUsername": "cryptosignals",
  "channelName": "Crypto Signals VIP",
  "date": "2024-06-15T08:17:00Z",
  "text": "🚀 BTC signal: Strong bullish divergence on 4H chart. Entry zone $68,500–$69,000. TP1: $72K. Stop: $67,200.",
  "views": 8910,
  "forwards": 234,
  "repliesCount": 67,
  "hasPhoto": false,
  "hasVideo": false,
  "hasDocument": false,
  "photoUrl": null,
  "messageUrl": "https://t.me/cryptosignals/12055",
  "matchedKeywords": ["BTC", "bullish"]
}
```

#### Channel Record

```json
{
  "type": "channel",
  "username": "cointelegraph",
  "name": "Cointelegraph",
  "description": "Covering the latest news and trends in blockchain, cryptocurrency, and decentralized technology.",
  "subscriberCount": 987432,
  "subscriberCountText": "987 432 subscribers",
  "profilePhotoUrl": "https://cdn5.telegram-cdn.org/file/ct_photo.jpg",
  "joinUrl": "https://t.me/cointelegraph",
  "isVerified": true,
  "scrapedAt": "2024-06-15T10:00:00.000Z"
}
```

***

### Output Fields Reference

#### Message Fields

| Field | Type | Description |
|---|---|---|
| `type` | string | `"message"` or `"monitor_match"` |
| `messageId` | string | Telegram message ID |
| `channelUsername` | string | Channel username (without @) |
| `channelName` | string | Display name of the channel |
| `date` | string | ISO 8601 datetime of the message |
| `text` | string | Full message text content |
| `views` | number | null | View count (null if not public) |
| `forwards` | number | null | Number of times forwarded |
| `repliesCount` | number | null | Reply count |
| `hasPhoto` | boolean | Whether message contains a photo |
| `hasVideo` | boolean | Whether message contains a video |
| `hasDocument` | boolean | Whether message contains a file |
| `photoUrl` | string | null | Direct URL to photo (if available) |
| `messageUrl` | string | Direct link to the message on Telegram |
| `matchedKeywords` | string\[] | (monitor mode only) Keywords found in text |

#### Channel Fields

| Field | Type | Description |
|---|---|---|
| `type` | string | `"channel"` |
| `username` | string | Channel username (without @) |
| `name` | string | Channel display name |
| `description` | string | null | Channel bio/description |
| `subscriberCount` | number | null | Subscriber count as integer |
| `subscriberCountText` | string | null | Raw subscriber count text from page |
| `profilePhotoUrl` | string | null | URL to channel profile photo |
| `joinUrl` | string | t.me link to join/view the channel |
| `isVerified` | boolean | Whether the channel has a verification badge |
| `scrapedAt` | string | ISO 8601 timestamp when data was collected |

***

### Limitations

- **Public channels only.** Private groups, private channels, and password-protected channels cannot be accessed without a Telegram login. This actor uses Telegram's public web preview (`t.me/s/`) which only works for public channels.
- **~30 messages per page.** Telegram's public preview shows approximately 30 messages per page. Pagination is used to collect more, but very high `maxMessages` values (1000+) will take several minutes per channel.
- **View counts.** View counts are only displayed on Telegram for channels (broadcast channels), not groups. Group messages will have `views: null`.
- **No real-time data.** There may be a delay of a few minutes between a message being posted and it appearing in the public preview.
- **Rate limits.** This actor uses polite delays between requests (1–3 seconds) to avoid being rate-limited by Telegram. Very large scrapes will take proportionally longer.
- **Search mode accuracy.** Search uses Google/DuckDuckGo to discover t.me links for a query. Results depend on how well-indexed those channels are by search engines.

***

### Pricing

**$1.50 per 1,000 results** (pay-per-result via Apify's platform charging).

Each channel profile or message counts as one result. You only pay for what you extract.

***

### Technical Notes

- Built with [Apify SDK v3](https://docs.apify.com/sdk/js/) and [Crawlee CheerioCrawler](https://crawlee.dev/)
- Uses `https://t.me/s/{username}` (Telegram's public server-side rendered preview) — no browser/JavaScript needed
- Rotating desktop User-Agent headers for reliability
- Graceful error handling: private or non-existent channels are skipped with a warning
- TypeScript, ES2022, Node.js ≥ 18 required

# Actor input Schema

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

Select the operation mode: 'channel' for full channel profile + messages, 'search' to discover channels by keyword, 'messages' for bulk message scraping with filters, 'monitor' for keyword alerting across multiple channels.

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

List of Telegram channel usernames or t.me URLs to process. Accepts: @username, t.me/username, https://t.me/username, or just the username. Example: \["cryptosignals", "bbcnews", "@cointelegraph"]

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

Keyword or phrase to search for public Telegram channels. Used only in 'search' mode. Example: 'crypto trading signals' or 'AI news'.

## `maxMessages` (type: `integer`):

Maximum number of messages to collect per channel. Applies to 'channel' and 'messages' modes. Higher values require more requests and time.

## `startDate` (type: `string`):

Only collect messages from this date onward. Format: YYYY-MM-DD (e.g. '2024-01-01'). Leave empty for no lower date bound.

## `endDate` (type: `string`):

Only collect messages up to and including this date. Format: YYYY-MM-DD (e.g. '2024-12-31'). Leave empty for no upper date bound.

## `filterKeywords` (type: `array`):

List of keywords to monitor. Only messages containing at least one keyword will be returned. Case-insensitive. Example: \["BTC", "bullish", "buy signal"]. Used in 'monitor' mode; also filters in 'messages' mode if provided.

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

Only return messages with at least this many views. Set to 0 to disable. Useful for filtering out low-engagement posts.

## `includeChannelInfo` (type: `boolean`):

When enabled in 'channel' mode, also fetches and saves the channel profile (name, description, subscriber count, photo). Disable to only collect messages.

## Actor input object example

```json
{
  "mode": "messages",
  "channels": [],
  "maxMessages": 50,
  "filterKeywords": [],
  "minViews": 0,
  "includeChannelInfo": true
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("botflowtech/telegram-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("botflowtech/telegram-intelligence").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 '{}' |
apify call botflowtech/telegram-intelligence --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/cy3CaPWIZa3yFXC7K/builds/z4qadEyViqmql4CG7/openapi.json