# 📨Telegram Message (Photo & Video Downloader) (`nextapi/telegram-message`)

Unlock valuable insights from Telegram groups and channels. Our advanced scraper captures messages, photos, and videos with comprehensive metadata for research purposes.

- **URL**: https://beta-securitybyobscurity.apify.com/nextapi/telegram-message.md
- **Developed by:** [NextAPI](https://beta-securitybyobscurity.apify.com/nextapi) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 31 total users, 25 monthly users, 99.2% runs succeeded, 4 bookmarks
- **User rating**: 3.26 out of 5 stars

## Pricing

Pay per event

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

# README

## Telegram Message

A powerful Telegram message extraction API that aggregates data from any public Telegram channel or group, providing comprehensive message content, engagement metrics, and media downloads in a unified format.

This Actor streamlines Telegram data collection by extracting complete message information including text content, metadata, engagement statistics, service actions, and media files through a single, efficient API endpoint.

### Key Features

- **Multi-Channel Support**: Extract data from any public Telegram channel or group
- **Complete Message Data**: Full message content including text, metadata, timestamps, and sender information
- **Engagement Analytics**: Comprehensive engagement metrics with views, forwards, replies, and reaction data
- **Media Downloads**: Automatic photo and media file downloads with direct storage links
- **Service Action Tracking**: Monitor channel events like user joins, admin actions, and channel updates
- **Advanced Date Filtering**: Flexible date filtering with both relative and absolute date ranges
- **Real-time Processing**: Fast batch processing with concurrent message extraction
- **Multiple Output Formats**: Export data in JSON, CSV, Excel, or any preferred format

### Configuration

#### Required Parameters

| Parameter           | Type     | Description                                        |
| ------------------- | -------- | -------------------------------------------------- |
| **telegram\_target** | `string` | Telegram channel or group URL/username to scrape   |
| **download\_medias** | `string` | File download preference for message media content |

**Telegram Target Examples:**

- Username format: "@channel\_name", "group\_name"
- Share link format: "t.me/channel\_name"
- Full URL format: "https://t.me/channel\_name"

**Download Medias Options:**

- "text": 📄 Text only (no media downloads)
- "image": 📸 Text + Images
- "all": 🎬 Text + All media files (images, videos, documents)

#### Optional Parameters

| Parameter      | Type     | Description                                          |
| -------------- | -------- | ---------------------------------------------------- |
| **start\_date** | `string` | Extract messages from this date onwards (UTC format) |

**Start Date Examples:**

- ISO format: "2024-01-01", "2024-01-01T12:00:00Z"
- Relative dates: "7 days", "2 weeks", "1 month"
- Leave empty for all available messages

#### Usage Example

```json
{
  "telegram_target": "https://t.me/binanceexchange",
  "download_medias": "image",
  "start_date": "7 days"
}
```

### Data Output

The Actor returns an array of message objects with comprehensive information from the target Telegram channel or group. Output is available in multiple formats including JSON, CSV, Excel, and more.

#### Data Fields

##### Message Core Data

| Field    | Type     | Description                                   |
| -------- | -------- | --------------------------------------------- |
| `id`     | integer  | Telegram message unique identifier            |
| `type`   | string   | Type of message (regular, service, etc.)      |
| `date`   | ISO date | ISO formatted timestamp when message was sent |
| `text`   | string   | Text content of the message                   |
| `sender` | string   | Username or name of message sender            |

##### Engagement Metrics

| Field           | Type    | Description                                |
| --------------- | ------- | ------------------------------------------ |
| `view_count`    | integer | Number of views for the message            |
| `forward_count` | integer | Number of times message was forwarded      |
| `reply_count`   | integer | Number of replies to the message           |
| `reactions`     | object  | Message reactions (emoji to count mapping) |

##### Message Properties

| Field    | Type    | Description                       |
| -------- | ------- | --------------------------------- |
| `silent` | boolean | Whether message was sent silently |
| `pinned` | boolean | Whether message is pinned         |

##### Context Information

| Field          | Type    | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| `reply_to`     | integer | ID of message this is replying to           |
| `album_id`     | integer | Messages with same album\_id belong to album |
| `forward_info` | object  | Details about message forwarding            |

##### Service Actions

| Field          | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| `service_type` | string | Service message action type (e.g., chat\_add\_user, pin\_message) |
| `service_info` | string | Additional information about the service action                |

##### Media Content

| Field       | Type   | Description                                                               |
| ----------- | ------ | ------------------------------------------------------------------------- |
| `media_url` | string | Downloaded media file URL from Apify storage, or empty string if no media |

##### Source Information

| Field         | Type    | Description                                                           |
| ------------- | ------- | --------------------------------------------------------------------- |
| `source_id`   | integer | Unique identifier of the channel or group where message was extracted |
| `source_name` | string  | Name of the channel or group where message was extracted from         |
| `source_type` | string  | Type of the source (Channel, Group, etc.)                             |

##### Processing Information

| Field          | Type   | Description                                                     |
| -------------- | ------ | --------------------------------------------------------------- |
| `topic_name`   | string | Name of the forum topic (if message is in a forum topic)        |
| `processor`    | string | Identifier of the processing system that extracted this message |
| `processed_at` | string | ISO formatted timestamp when the message was processed          |

#### Example Output

```json
{
  "id": 2847,
  "type": "regular",
  "date": "2024-01-15T14:23:45.123Z",
  "text": "🚀 BREAKING: New cryptocurrency listing announcement! Trading starts tomorrow at 12:00 UTC. Get ready for the next big opportunity! #Crypto #Trading",
  "sender": "@crypto_announcements",
  "silent": false,
  "pinned": false,
  "view_count": 15420,
  "forward_count": 847,
  "reply_count": 156,
  "reactions": {
    "🚀": 234,
    "🔥": 189,
    "💎": 78,
    "📈": 145
  },
  "service_type": null,
  "service_info": null,
  "forward_info": {
    "date": "2024-01-15T14:20:15.000Z",
    "from_id": 1234567890,
    "from_name": "Crypto News Daily",
    "message_id": 1250
  },
  "reply_to": 2845,
  "album_id": null,
  "media_url": "https://apify.com/storage/kv/photo_2847_1642251625.jpg",
  "source_id": 1234567890,
  "source_name": "Binance",
  "source_type": "Channel",
  "topic_name": null,
  "processor": "https://apify.com/nextapi/telegram-message",
  "processed_at": "2024-01-15T14:24:00.000Z"
}
```

# Actor input Schema

## `download_medias` (type: `string`):

Select what medias to download from messages (text only, text + images, or text + all media)

## `telegram_target` (type: `string`):

Enter Telegram group or channel to scrape.

## `start_date` (type: `string`):

Extract messages from this date to present. Format: YYYY-MM-DD or {number} {unit} (e.g., 7 days, 2 weeks)

## Actor input object example

```json
{
  "download_medias": "image",
  "telegram_target": "https://t.me/binanceexchange",
  "start_date": "1 days"
}
```

# 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 = {
    "download_medias": "image",
    "telegram_target": "https://t.me/binanceexchange",
    "start_date": "1 days"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nextapi/telegram-message").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 = {
    "download_medias": "image",
    "telegram_target": "https://t.me/binanceexchange",
    "start_date": "1 days",
}

# Run the Actor and wait for it to finish
run = client.actor("nextapi/telegram-message").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 '{
  "download_medias": "image",
  "telegram_target": "https://t.me/binanceexchange",
  "start_date": "1 days"
}' |
apify call nextapi/telegram-message --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "📨Telegram Message (Photo & Video Downloader)",
        "description": "Unlock valuable insights from Telegram groups and channels. Our advanced scraper captures messages, photos, and videos with comprehensive metadata for research purposes.",
        "version": "0.0",
        "x-build-id": "h3niFObY7vtVq82Dg"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/nextapi~telegram-message/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-nextapi-telegram-message",
                "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/nextapi~telegram-message/runs": {
            "post": {
                "operationId": "runs-sync-nextapi-telegram-message",
                "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/nextapi~telegram-message/run-sync": {
            "post": {
                "operationId": "run-sync-nextapi-telegram-message",
                "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": [
                    "download_medias",
                    "telegram_target"
                ],
                "properties": {
                    "download_medias": {
                        "title": "📱 Download Medias",
                        "enum": [
                            "text",
                            "image",
                            "all"
                        ],
                        "type": "string",
                        "description": "Select what medias to download from messages (text only, text + images, or text + all media)"
                    },
                    "telegram_target": {
                        "title": "🎯 Telegram Target",
                        "type": "string",
                        "description": "Enter Telegram group or channel to scrape."
                    },
                    "start_date": {
                        "title": "📅 Start Date",
                        "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$",
                        "type": "string",
                        "description": "Extract messages from this date to present. Format: YYYY-MM-DD or {number} {unit} (e.g., 7 days, 2 weeks)"
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
