# Telegram Channels Scraper (`maximedupre/telegram-channels-scraper`) Actor

Search Telegram channels by keyword or enrich known handles and t.me links. Export channel titles, URLs, descriptions, member counts, and verification flags.

- **URL**: https://apify.com/maximedupre/telegram-channels-scraper.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Social media, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 channels

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 channels scraper for keyword discovery

Telegram Channels Scraper finds public [Telegram](https://telegram.org/) channels from search terms and enriches known Telegram handles or `t.me` links with public channel metadata. Add keywords such as `ai`, `crypto`, or `marketing`, then export channel titles, usernames, URLs, descriptions, subscriber/member counts, verification flags, profile photos, source links, and scrape timestamps.

Use this Telegram channel scraper when you need a repeatable way to build channel lists for audience research, community discovery, influencer scouting, market monitoring, competitor tracking, or lead enrichment. You do not need a Telegram login, cookies, phone number, or API key.

For a small first run, keep the prefilled `ai` search term and the default limit of 25 channels. The Actor searches public channel directory results, deduplicates channels across keywords and known targets, checks Telegram public preview pages, and saves usable channel rows to the dataset during the run.

### ✅ What this Actor does

- Finds Telegram channels from one or more search keywords.
- Enriches known public Telegram channels from bare usernames, `@handles`, `t.me` links, or `telegram.me` links.
- Saves one dataset item per discovered or enriched channel.
- Adds public channel metadata such as title, description, username, canonical channel URL, member/subscriber count, verification status, profile photo URL, and source URLs.
- Preserves the matched search term or input index so you can trace why a channel was included.
- Can add a small recent-message preview when Telegram exposes public posts.
- Skips invalid, private, missing, or unavailable targets instead of adding placeholder dataset rows.
- Works with Apify exports, API access, schedules, webhooks, and integrations.

This Actor is focused on public Telegram channel discovery and metadata enrichment. It does not join channels, read private chats, scrape hidden member lists, or download media files.

### 📦 Data you can export

Each output row represents one public Telegram channel. Depending on what Telegram and the discovery source expose, rows can include:

- `resultPosition`, `sourceMode`, `matchedSearchTerm`, and `inputIndex`
- `username`, `normalizedTarget`, `channelUrl`, and `sourceUrl`
- `channelTitle`, `description`, and `entityKind`
- `memberCount` and `memberCountText`
- `isVerified`, `isScam`, `isFake`, `isRestricted`, and `isBot`
- `profilePhotoUrl`
- `directoryTitle`, `directoryDescription`, `directoryMemberCount`, `directoryMemberCountText`, and `directoryUrl`
- `recentMessages` with message URL, date, text, and views when message preview is enabled
- `confidence`, `fieldCompleteness`, and `scrapedAt`

You can export the dataset as JSON, CSV, Excel, XML, RSS, or HTML, or read it through the Apify API.

### 👥 Common use cases

- Build Telegram channel lists around a market, topic, product, or audience.
- Find communities for influencer research, outreach prep, or sponsorship review.
- Compare public subscriber/member counts across channels in a niche.
- Track public Telegram channels for competitor monitoring or market research.
- Enrich an existing list of Telegram handles with public metadata.
- Feed channel discovery data into spreadsheets, CRMs, dashboards, or data pipelines.

### ▶️ How to run it

1. Add one or more keywords in **Search terms** to discover public Telegram channels.
2. Optionally add known channels in **Known channel targets** to enrich handles or links you already have.
3. Keep **Channel limit** small for your first run, then raise it when the output shape fits your workflow.
4. Leave recent message preview off for a fast metadata-only run, or enable it when you need a short sample of public posts.
5. Start the Actor and open the dataset.

Example input:

```json
{
	"searchTerms": ["ai"],
	"channelTargets": ["@telegram"],
	"maxChannels": 10,
	"maxChannelsPerSearchTerm": 10,
	"includeRecentMessagesPreview": false
}
````

### ⚙️ Input options

- **Search terms**: keywords or topics used to find public Telegram channels.
- **Known channel targets**: public Telegram usernames, `@handles`, `t.me` links, or `telegram.me` links to enrich directly.
- **Channel limit**: maximum saved channel rows across search results and known targets.
- **Channels per search term**: maximum candidates each keyword can contribute before deduplication and enrichment.
- **Include recent messages preview**: add a small sample of recent public messages when Telegram exposes them.
- **Preview messages per channel**: maximum recent messages to include per channel, up to 5.

Private `/c/` links and invite-only chats are not supported because they do not have public preview pages.

### 🧾 Output example

```json
{
	"resultPosition": 1,
	"sourceMode": "search",
	"matchedSearchTerm": "ai",
	"inputIndex": null,
	"username": "telegram",
	"normalizedTarget": "@telegram",
	"channelUrl": "https://t.me/telegram",
	"sourceUrl": "https://t.me/telegram",
	"channelTitle": "Telegram News",
	"description": "The official Telegram on Telegram.",
	"entityKind": "channel",
	"memberCount": 10618211,
	"memberCountText": "10 618 211 subscribers",
	"isVerified": true,
	"isScam": false,
	"isFake": false,
	"isRestricted": false,
	"isBot": false,
	"profilePhotoUrl": "https://cdn.example/profile.jpg",
	"directoryTitle": "Telegram News",
	"directoryDescription": "The official Telegram on Telegram.",
	"directoryMemberCount": 10618211,
	"directoryMemberCountText": "10 618 211 members",
	"directoryUrl": "https://www.tgresou.com/channel/telegram",
	"recentMessages": [],
	"confidence": 1,
	"fieldCompleteness": 1,
	"scrapedAt": "2026-06-02T00:00:00.000Z"
}
```

### 💳 Pricing

Telegram Channels Scraper uses pay-per-event pricing. You pay for each public Telegram channel saved to the dataset, so small test runs stay predictable.

### ⚠️ Limits and caveats

- The Actor only collects public Telegram channel data.
- Keyword discovery uses public directory search results and may not match Telegram app search exactly.
- Telegram may hide or omit subscriber counts, descriptions, profile photos, verification flags, or recent messages for some channels.
- Recent message preview is a small sample, not a full channel history export.
- The Actor does not log in to Telegram, join channels, scrape private chats, collect hidden member lists, send messages, or download media files.

### ❓ FAQ

#### 🔐 Does this Telegram channels scraper need a Telegram account?

No. The Actor works with public channel search results and Telegram public preview pages. You do not need to provide Telegram cookies, login credentials, a phone number, or an API key.

#### 👥 Can it scrape Telegram channel members?

No. It can return a public subscriber or member count when Telegram shows one, but it does not scrape member lists or hidden users.

#### 🔎 Can I use it as a Telegram channel finder?

Yes. Add keywords in **Search terms** to discover public Telegram channels, then use the exported usernames and channel URLs in your research, outreach, or monitoring workflow.

#### 🧩 Can I enrich channels I already know?

Yes. Add known channels in **Known channel targets** using bare usernames, `@handles`, `t.me` links, or `telegram.me` links.

#### 📅 Can I schedule repeat runs?

Yes. You can schedule the Actor on Apify and compare exported datasets over time. The Actor does not maintain a historical database by itself.

### 📝 Changelog

- 0.0: Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~telegram-channels-scraper/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Other actors

- [Telegram Info Scraper ↗](https://apify.com/maximedupre/telegram-info-scraper) - Enrich known Telegram usernames, channels, groups, bots, and profiles.
- [Telegram Channel Messages Scraper ↗](https://apify.com/maximedupre/telegram-channel-messages-scraper) - Export public Telegram channel posts with dates, text, links, views, and metadata.
- [Telegram Media Downloader ↗](https://apify.com/maximedupre/telegram-media-downloader) - Extract public Telegram media URLs from posts, channels, and groups.
- [YouTube Channel Search Scraper ↗](https://apify.com/maximedupre/youtube-channel-search-scraper) - Find YouTube channels from keywords and export channel metadata.
- [Social Media Stats Checker ↗](https://apify.com/maximedupre/social-media-stats-checker) - Check public profile stats across major social platforms.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `searchTerms` (type: `array`):

Topics or keywords used to find public Telegram channels. Try a small first run with a topic such as ai, crypto, marketing, or fitness.

## `channelTargets` (type: `array`):

Optional public Telegram channels to enrich directly. Accepts bare usernames, @handles, t.me links, and telegram.me links.

## `maxChannels` (type: `integer`):

Maximum number of Telegram channels to save across search results and known targets. Lower this for a quick test run.

## `maxChannelsPerSearchTerm` (type: `integer`):

Maximum channel candidates to collect from each keyword before deduplication and Telegram metadata enrichment.

## `includeRecentMessagesPreview` (type: `boolean`):

Add a small sample of recent public channel messages when Telegram exposes them. Keep this off for the fastest metadata-only run.

## `maxPreviewMessagesPerChannel` (type: `integer`):

Maximum recent public messages to include per channel when message preview is enabled. This is a preview, not a full history export.

## Actor input object example

```json
{
  "searchTerms": [
    "ai",
    "crypto",
    "marketing"
  ],
  "channelTargets": [
    "@telegram",
    "https://t.me/durov"
  ],
  "maxChannels": 25,
  "maxChannelsPerSearchTerm": 25,
  "includeRecentMessagesPreview": false,
  "maxPreviewMessagesPerChannel": 0
}
```

# Actor output Schema

## `overview` (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 = {
    "searchTerms": [
        "ai",
        "crypto",
        "marketing"
    ],
    "channelTargets": [
        "@telegram",
        "https://t.me/durov"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/telegram-channels-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 = {
    "searchTerms": [
        "ai",
        "crypto",
        "marketing",
    ],
    "channelTargets": [
        "@telegram",
        "https://t.me/durov",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/telegram-channels-scraper").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 '{
  "searchTerms": [
    "ai",
    "crypto",
    "marketing"
  ],
  "channelTargets": [
    "@telegram",
    "https://t.me/durov"
  ]
}' |
apify call maximedupre/telegram-channels-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Telegram Channels Scraper",
        "description": "Search Telegram channels by keyword or enrich known handles and t.me links. Export channel titles, URLs, descriptions, member counts, and verification flags.",
        "version": "0.0",
        "x-build-id": "lIK9FQHAWAXg3SsSs"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/maximedupre~telegram-channels-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-maximedupre-telegram-channels-scraper",
                "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/maximedupre~telegram-channels-scraper/runs": {
            "post": {
                "operationId": "runs-sync-maximedupre-telegram-channels-scraper",
                "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/maximedupre~telegram-channels-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-maximedupre-telegram-channels-scraper",
                "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": {
                    "searchTerms": {
                        "title": "Search terms",
                        "maxItems": 50,
                        "type": "array",
                        "description": "Topics or keywords used to find public Telegram channels. Try a small first run with a topic such as ai, crypto, marketing, or fitness.",
                        "items": {
                            "type": "string",
                            "minLength": 1
                        }
                    },
                    "channelTargets": {
                        "title": "Known channel targets",
                        "maxItems": 1000,
                        "type": "array",
                        "description": "Optional public Telegram channels to enrich directly. Accepts bare usernames, @handles, t.me links, and telegram.me links.",
                        "items": {
                            "type": "string",
                            "minLength": 1
                        }
                    },
                    "maxChannels": {
                        "title": "Channel limit",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of Telegram channels to save across search results and known targets. Lower this for a quick test run.",
                        "default": 25
                    },
                    "maxChannelsPerSearchTerm": {
                        "title": "Channels per search term",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "Maximum channel candidates to collect from each keyword before deduplication and Telegram metadata enrichment.",
                        "default": 25
                    },
                    "includeRecentMessagesPreview": {
                        "title": "Recent message preview",
                        "type": "boolean",
                        "description": "Add a small sample of recent public channel messages when Telegram exposes them. Keep this off for the fastest metadata-only run.",
                        "default": false
                    },
                    "maxPreviewMessagesPerChannel": {
                        "title": "Preview messages per channel",
                        "minimum": 0,
                        "maximum": 5,
                        "type": "integer",
                        "description": "Maximum recent public messages to include per channel when message preview is enabled. This is a preview, not a full history export.",
                        "default": 0
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```