# Telegram Media Downloader (`parsebird/telegram-media-downloader`) Actor
Extract Telegram post media URLs, titles, descriptions, thumbnails, and media metadata from public Telegram channels or groups. Use API access, scheduling, integrations, and JSON, CSV, Excel exports.
- **URL**: https://apify.com/parsebird/telegram-media-downloader.md
- **Developed by:** [ParseBird](https://apify.com/parsebird) (community)
- **Categories:** Integrations, Videos, Social media
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet
## Pricing
from $0.01 / 1,000 results
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
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/docs.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Media Downloader
Telegram Media Downloader extracts media download URLs and metadata from public [Telegram](https://telegram.org/) channel and group posts.
Get Telegram post media URLs, thumbnails, titles, descriptions, media type, file extension, quality labels, and processing status in a structured dataset ready for API access, scheduling, integrations, and export.
##### Copy to your AI assistant
Copy this block into ChatGPT, Claude, Cursor, or any LLM to start using this actor.
```text
Use Apify Actor parsebird/telegram-media-downloader to extract media URLs from public Telegram posts. Input: {"links":["https://t.me/csifeducacionmadrid/2508"]}. Output fields: url, result.url, result.source, result.title, result.description, result.thumbnail, result.medias[{url,quality,extension,type}], result.type, result.error, result.status, result.time_end. Run with ApifyClient actor("parsebird/telegram-media-downloader").call(run_input={...}); API docs: https://docs.apify.com/api/client/python/docs/quick-start and https://docs.apify.com/api/client/js/docs/quick-start; token: https://console.apify.com/settings/integrations.
````
### What is Telegram Media Downloader?
**Telegram Media Downloader** is a Telegram media downloader and Telegram scraper for public post URLs such as `https://t.me/channel/12345`. It fetches the public Telegram embed page, extracts post text, thumbnails, and media CDN URLs, and returns analysis-ready JSON data. Use it as a lightweight **Telegram API alternative** when you need public post media metadata without logging in.
### What can Telegram Media Downloader do?
- Extract media download URLs from public Telegram posts.
- Capture post title, description, thumbnail URL, media type, extension, quality label, and status.
- Process multiple Telegram post links in one run, with a recommended maximum of 100 URLs.
- Run on a schedule with [Apify schedules](https://docs.apify.com/platform/schedules), call from the [Apify API](https://docs.apify.com/api/v2), and connect to [Apify integrations](https://apify.com/integrations).
- Export results as JSON, CSV, Excel, XML, RSS, or HTML from Apify datasets.
### What data can you extract from Telegram posts?
| Field | Description |
|-------|-------------|
| `url` | Original Telegram post URL submitted in the input |
| `result.url` | Telegram embed URL used for extraction |
| `result.title` | Cleaned post text, shortened for title-style display |
| `result.description` | Full cleaned post text when available |
| `result.thumbnail` | Thumbnail or preview image URL detected on the post |
| `result.medias` | List of extracted media objects with URL, quality, extension, and type |
| `result.status` | `success`, `no_media`, or `error` |
| `result.time_end` | Processing time for that URL in milliseconds |
### Input parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `links` | array | **Yes** | - | Public Telegram post URLs to process, for example `https://t.me/csifeducacionmadrid/2508` |
### Output example
```json
[
{
"url": "https://t.me/csifeducacionmadrid/2508",
"result": {
"url": "https://t.me/csifeducacionmadrid/2508?embed=1&mode=tme",
"source": "telegram",
"title": "CSIF CONVOCA HUELGA EL 13/02...",
"description": "CSIF CONVOCA HUELGA EL 13/02...",
"thumbnail": "https://cdn4.cdn-telegram.org/file/example.jpg",
"medias": [
{
"url": "https://cdn4.cdn-telegram.org/file/example.mp4",
"quality": "HD",
"extension": "mp4",
"type": "video"
}
],
"type": "single",
"error": false,
"status": "success",
"time_end": 692
}
}
]
```
Download the dataset in JSON, CSV, Excel, XML, RSS, or HTML from the Apify dataset export menu.
### How to scrape Telegram media URLs
1. Open Telegram Media Downloader on Apify.
2. Paste one or more public Telegram post URLs into `links`.
3. Start the run.
4. Open the dataset to review titles, descriptions, thumbnails, media URLs, and statuses.
5. Export the dataset or connect the Actor to your workflow through the Apify API, webhooks, or integrations.
### Python API example
```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("parsebird/telegram-media-downloader").call(run_input={
"links": [
"https://t.me/csifeducacionmadrid/2508",
],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
```
### JavaScript API example
```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('parsebird/telegram-media-downloader').call({
links: [
'https://t.me/csifeducacionmadrid/2508',
],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```
### How much does it cost to scrape Telegram media?
Telegram Media Downloader uses pay-per-event pricing. You pay for processed results and extracted media URLs.
| Event | Free / Bronze / Silver | Gold | What counts as an event |
|-------|------------------------|------|--------------------------|
| `result` | $0.01 per 1,000 | $0.01 per 1,000 | One processed input URL pushed to the dataset |
| `media` | $3.99 per 1,000 | $3.49 per 1,000 | One extracted media URL |
For example, 1,000 public Telegram post URLs with 1,000 extracted media URLs cost $4.00 on Free, Bronze, or Silver tiers before platform usage charges. If Apify shows a free trial or free platform credits for your account, you can use them to test a small run first.
### Use cases
- Archive media URLs from public Telegram announcements.
- Monitor public Telegram channels for posts with images, videos, or documents.
- Build media research datasets for journalism, OSINT, brand monitoring, or social listening.
- Feed Telegram post media metadata into Google Sheets, Make, Zapier, webhooks, or internal APIs.
### Is it legal to scrape Telegram?
Scraping publicly available web data is generally legal in many jurisdictions, but you should only process content you are allowed to access and use. Telegram Media Downloader only supports public Telegram channel and group posts; it does not bypass login, private channels, invite-only groups, or access restrictions. Review Telegram's terms and Apify's guide on [the legality of web scraping](https://blog.apify.com/is-web-scraping-legal/) before using extracted data in production.
### Other Telegram scrapers and related Actors
- [Kick Video Downloader](https://apify.com/parsebird/kick-video-downloader) - download Kick VODs and clips.
- [YouTube Thumbnail Downloader](https://apify.com/parsebird/youtube-thumbnail-downloader) - extract YouTube thumbnail URLs.
- [Pinterest Image Downloader](https://apify.com/parsebird/pinterest-image-downloader) - extract Pinterest image data.
- [Unsplash Image Scraper](https://apify.com/parsebird/unsplash-image-scraper) - scrape Unsplash image metadata.
### FAQ
**Does Telegram Media Downloader work with private Telegram channels?**
No. It only works with public Telegram channels and groups that expose public `t.me` post pages.
**Does it download and store media files?**
No. It returns Telegram media URLs and metadata. It does not re-upload files into Apify key-value storage.
**What Telegram URL format is supported?**
Use public post URLs like `https://t.me/channel/12345`. Invite links, private links, and login-only content are not supported.
**What happens when a post has no media?**
The Actor returns a dataset item with `status` set to `no_media`, an empty `medias` array, and any text metadata it can extract.
**Can I schedule recurring Telegram media extraction?**
Yes. Use Apify schedules to run the Actor hourly, daily, weekly, or at a custom interval.
**Can I use Telegram Media Downloader from Python or JavaScript?**
Yes. Use the Apify API clients for Python or JavaScript with the examples above, or call the Actor through the REST API.
**What are the main limitations?**
Only public Telegram channels and groups are supported. The Actor respects Telegram rate limiting, and a maximum of 100 URLs per run is recommended.
# Actor input Schema
## `links` (type: `array`):
Add public Telegram post URLs to process. Use links like https://t.me/csifeducacionmadrid/2508. Private channels, invite links, and login-only posts are not supported.
## Actor input object example
```json
{
"links": [
"https://t.me/csifeducacionmadrid/2508"
]
}
```
# Actor output Schema
## `dataset` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"links": [
"https://t.me/csifeducacionmadrid/2508"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("parsebird/telegram-media-downloader").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 = { "links": ["https://t.me/csifeducacionmadrid/2508"] }
# Run the Actor and wait for it to finish
run = client.actor("parsebird/telegram-media-downloader").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 '{
"links": [
"https://t.me/csifeducacionmadrid/2508"
]
}' |
apify call parsebird/telegram-media-downloader --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=parsebird/telegram-media-downloader",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Telegram Media Downloader",
"description": "Extract Telegram post media URLs, titles, descriptions, thumbnails, and media metadata from public Telegram channels or groups. Use API access, scheduling, integrations, and JSON, CSV, Excel exports.",
"version": "1.0",
"x-build-id": "71WzRzoRdO9JfjFQC"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/parsebird~telegram-media-downloader/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-parsebird-telegram-media-downloader",
"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/parsebird~telegram-media-downloader/runs": {
"post": {
"operationId": "runs-sync-parsebird-telegram-media-downloader",
"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/parsebird~telegram-media-downloader/run-sync": {
"post": {
"operationId": "run-sync-parsebird-telegram-media-downloader",
"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",
"required": [
"links"
],
"properties": {
"links": {
"title": "Telegram Post URLs",
"type": "array",
"description": "Add public Telegram post URLs to process. Use links like https://t.me/csifeducacionmadrid/2508. Private channels, invite links, and login-only posts are not supported.",
"items": {
"type": "string"
}
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```