# 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, 1 monthly users, 100.0% runs succeeded, NaN 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Telegram Channel Intelligence", "version": "0.1", "x-build-id": "z4qadEyViqmql4CG7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/botflowtech~telegram-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-botflowtech-telegram-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/botflowtech~telegram-intelligence/runs": { "post": { "operationId": "runs-sync-botflowtech-telegram-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/botflowtech~telegram-intelligence/run-sync": { "post": { "operationId": "run-sync-botflowtech-telegram-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "channel", "search", "messages", "monitor" ], "type": "string", "description": "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.", "default": "messages" }, "channels": { "title": "Channels", "type": "array", "description": "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\"]", "items": { "type": "string" }, "default": [] }, "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword or phrase to search for public Telegram channels. Used only in 'search' mode. Example: 'crypto trading signals' or 'AI news'." }, "maxMessages": { "title": "Max Messages per Channel", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of messages to collect per channel. Applies to 'channel' and 'messages' modes. Higher values require more requests and time.", "default": 50 }, "startDate": { "title": "Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only collect messages from this date onward. Format: YYYY-MM-DD (e.g. '2024-01-01'). Leave empty for no lower date bound." }, "endDate": { "title": "End Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "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": { "title": "Filter Keywords (Monitor Mode)", "type": "array", "description": "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.", "items": { "type": "string" }, "default": [] }, "minViews": { "title": "Minimum Views", "minimum": 0, "type": "integer", "description": "Only return messages with at least this many views. Set to 0 to disable. Useful for filtering out low-engagement posts.", "default": 0 }, "includeChannelInfo": { "title": "Include Channel Info", "type": "boolean", "description": "When enabled in 'channel' mode, also fetches and saves the channel profile (name, description, subscriber count, photo). Disable to only collect messages.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```