> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrape.st/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Monitor Telegram groups and channels for real-time messages and token mentions

Track Telegram groups and channels in real-time. Capture messages, token mentions, and media — then backfill historical data on demand.

## What You Can Do

| Capability          | Endpoint                   | Description                             |
| ------------------- | -------------------------- | --------------------------------------- |
| **Track Group**     | `POST /track/telegram`     | Monitor a Telegram group or channel     |
| **Get Source**      | `GET /track/telegram`      | Retrieve a tracked Telegram source      |
| **Delete Tracking** | `DELETE /track/telegram`   | Stop tracking a Telegram source         |
| **Backfill**        | `PUT /backfill`            | Trigger historical message backfill     |
| **History**         | `GET /account/history/:id` | Retrieve backfilled historical messages |

## Track a Telegram Group

Start receiving real-time messages from any Telegram group or channel.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://scrape.st/track/telegram \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"sid": "crypto_signals_group"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://scrape.st/track/telegram", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ sid: "crypto_signals_group" }),
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://scrape.st/track/telegram",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={"sid": "crypto_signals_group"},
  )
  print(res.json())
  ```
</CodeGroup>

**Response:**

Telegram tracking is an asynchronous process because the Telegram client may need to resolve the invite link or username and join the channel. The API returns a `202 Accepted` status along with a `jobId`:

```json theme={null}
{
  "message": "Tracking request for \"crypto_signals_group\" on telegram has been queued",
  "jobId": "65"
}
```

### Check Tracking Status

You can poll the status endpoint to know when the tracking process completes and to get the internal ID (`src_...`) of the source.

```bash theme={null}
curl -X GET "https://scrape.st/track/status/telegram/65" \
  -H "x-api-key: YOUR_API_KEY"
```

**Response (In Progress):**

```json theme={null}
{
  "jobId": "65",
  "name": "track",
  "state": "active",
  "progress": 0,
  "attempts": 0
}
```

**Response (Completed):**

```json theme={null}
{
  "jobId": "65",
  "name": "track",
  "state": "completed",
  "progress": 100,
  "attempts": 1,
  "returnValue": {
    "name": "Crypto Signals Group",
    "username": "crypto_signals_group",
    "id": "src_456",
    "externalId": "-1001234567890"
  }
}
```

<Note>
  You'll need the `id` from the `returnValue` (`src_456` in this example) if you
  want to run historical backfills for this group later.
</Note>

## Search Messages & Users

Search for messages matching a keyword globally or within specific channels. You can also search for Telegram users and channel participants.

```bash theme={null}
# Search globally for crypto messages
curl -X GET "https://scrape.st/telegram/search?q=crypto&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

# Search messages within a specific channel
curl -X GET "https://scrape.st/telegram/channel/@durov/search?q=update&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

# Search for users by username
curl -X GET "https://scrape.st/telegram/users/search?q=satoshi&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

## Backfill History

Retrieve historical messages from tracked Telegram groups.

<Note>
  In the examples below, `src_456` is the **internal ID** of the Telegram
  group/channel whose historical data you want to pull. This is the same `id`
  returned when you created the tracking via `POST /track/telegram`.
</Note>

```bash theme={null}
# Trigger backfill for a Telegram source
curl -X PUT https://scrape.st/backfill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "src_456"}'

# Check backfill status
curl -X GET "https://scrape.st/backfill/status?id=src_456" \
  -H "x-api-key: YOUR_API_KEY"

# Retrieve historical messages
curl -X GET "https://scrape.st/account/history/src_456?limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

## Download Media

You can download media attached to a Telegram message using the channel ID and message ID. This endpoint returns the raw file buffer with appropriate `Content-Type` headers and is **aggressively rate-limited to 2 requests per minute** to prevent abuse.

```bash theme={null}
# Download a photo/video/document from a message
curl -X GET "https://scrape.st/telegram/media/2453451956/2410" \
  -H "x-api-key: YOUR_API_KEY" \
  --output media.jpg
```

## Webhook Payload

When a tracked Telegram group receives a message, your webhook receives a `SourceEvent` object. This is the exact shape sent via `JSON.stringify` to your webhook URL:

```json theme={null}
{
  "mid": 2410,
  "sid": "2453451956|-3611607141753548436",
  "source": "telegram",
  "timestamp": 1777820233000,
  "content": "Let's see what a payload looks like",
  "images": [],
  "payload": {
    "id": 2410,
    "fromId": {
      "userId": "976665869",
      "className": "PeerUser"
    },
    "fromBoostsApplied": null,
    "peerId": {
      "channelId": "2453451956",
      "className": "PeerChannel"
    },
    "fwdFrom": null,
    "viaBotId": null,
    "viaBusinessBotId": null,
    "replyTo": null,
    "date": 1777820233,
    "message": "Let's see what a payload looks like",
    "media": null,
    "replyMarkup": null,
    "entities": null,
    "views": null,
    "forwards": null,
    "replies": {
      "flags": 0,
      "comments": false,
      "replies": 0,
      "repliesPts": 3051,
      "recentRepliers": null,
      "className": "MessageReplies"
    },
    "editDate": null,
    "ttlPeriod": null,
    "quickReplyShortcutId": null,
    "effect": null,
    "factcheck": null,
    "reportDeliveryUntilDate": null,
    "className": "Message"
    // ... other MTProto fields (flags, media, forwards, replies, etc.)
  }
}
```

| Field       | Type   | Description                                     |
| ----------- | ------ | ----------------------------------------------- |
| `mid`       | number | Message ID — the Telegram message ID            |
| `sid`       | string | Source ID — the Telegram chat/channel ID        |
| `source`    | string | `"telegram"`                                    |
| `timestamp` | number | Unix timestamp (ms) when the event was received |
| `content`   | string | Message text                                    |
| `images`    | array  | Photo URLs via the media proxy (empty if none)  |
| `payload`   | object | Raw Telegram message object                     |

<Note>
  Telegram photos are not public URLs — each `images` entry points at the media
  proxy (`https://scrape.st/telegram/media/{channelId}/{messageId}`), which
  downloads the photo on demand. Only `MessageMediaPhoto` is included; videos
  and documents are omitted.
</Note>

## Delivery Methods

Telegram data is delivered through all the same channels as X:

* **[Webhooks](/rest-api-reference/create-webhook)** — Push to your endpoint
* **[WebSocket](/streams/websocket-connections)** — Real-time bidirectional stream
* **[SSE](/streams/public-sse)** — Server-sent events with auto-reconnect

## API Reference

All tracking endpoints use `/track/:source` where `:source` is `x`, `telegram`, or `discord`.

* [Create Tracking](/rest-api-reference/create-tracking) — `POST /track/telegram`
* [List Tracked Sources](/rest-api-reference/list-tracking) — `GET /track/telegram`
* [Delete Tracking](/rest-api-reference/delete-tracking) — `DELETE /track/telegram`
* [Trigger Backfill](/rest-api-reference/backfill/trigger) — `PUT /backfill`
* [Backfill Status](/rest-api-reference/backfill/status) — `GET /backfill/status`
* [Get History](/rest-api-reference/backfill/get-history) — `GET /account/history/:id`

### Telegram Queries

* [Global Search](/rest-api-reference/telegram-global-search) — `GET /telegram/search`
* [Search Users](/rest-api-reference/telegram-users-search) — `GET /telegram/users/search`
* [Search Channel Messages](/rest-api-reference/telegram-channel-search) — `GET /telegram/channel/:channelId/search`
* [Search Participants](/rest-api-reference/telegram-participants-search) — `GET /telegram/channel/:channelId/participants/search`
* [Search Media by Type](/rest-api-reference/telegram-channel-type-search) — `GET /telegram/channel/:channelId/type/:type/search`
* Download Media — `GET /telegram/media/:channelId/:messageId`