---
name: telegram-collector
description: Collect, analyze and organize information from Telegram groups and channels. Use to monitor Telegram channels, extract knowledge, build topic databases, and integrate Telegram data into your OpenClaw memory.
version: 2.0.0
tags: [telegram, data-collection, knowledge-base, monitoring]
requirements:
  - python3
dependencies:
  - telethon>=1.42.0
  - python-dotenv
allowed-tools: [exec, read, write, edit, cron]
platforms: [linux]
---

# Telegram Collector

> Сбор, хранение и инкрементальное обновление сообщений из Telegram-групп и каналов.

## Возможности

- ✅ Мониторинг каналов и супергрупп (включая форумные топики)
- ✅ Первичная загрузка всей истории (пакетами по 10 000, пауза 3 мин)
- ✅ Инкрементальная загрузка каждые 6 часов (только новые сообщения)
- ✅ Хранение по структуре: канал → топик → батчи
- ✅ Загрузка медиафайлов (фото, документы ≤50 МБ)
- ✅ Метаданные для видео и файлов >50 МБ (для отложенной загрузки)
- ✅ Восстановление дерева диалогов через reply_to

## Структура данных

```
workspace/data/telegram-collector/
└── raw/
    └── {channel_id}/                   ← числовой ID канала/группы
        ├── meta.json                   ← название, username, список топиков
        └── {topic_id}/                 ← ID форумного топика (1 = Основная)
            ├── state.json              ← прогресс загрузки, last_message_id
            ├── batch_0001.json
            ├── batch_0002.json
            └── media/
                ├── {msg_id}_photo.jpg
                ├── {msg_id}_document.pdf
                └── ...
```

### meta.json
```json
{
  "id": -1001234567890,
  "username": "snowbikerussia",
  "title": "Сноубайк Россия",
  "topics": {
    "1": "Основная",
    "63155": "Барахолка",
    "63467": "Техничка"
  }
}
```

### state.json (на каждый топик)
```json
{
  "topic_id": 63155,
  "topic_title": "Барахолка",
  "first_message_id": 1000,
  "last_message_id": 165197,
  "total_messages": 5432,
  "initial_load_complete": true,
  "last_incremental_at": "2026-03-24T14:00:00Z"
}
```

### Структура сообщения
```json
{
  "id": 165197,
  "date": "2026-03-24T13:08:29Z",
  "text": "Смотрите что купил",
  "from_id": 469188764,
  "reply_to_msg_id": 165180,
  "reply_to_top_id": 63155,
  "quote_text": null,
  "edit_date": null,
  "media": {
    "type": "photo",
    "file_id": "AgACAgI...",
    "size": 245000,
    "mime": "image/jpeg",
    "filename": null,
    "duration": null,
    "width": null,
    "height": null,
    "local_path": "media/165197_photo.jpg",
    "downloaded": true
  }
}
```

## Логика медиафайлов

| Тип | Размер | Действие |
|-----|--------|----------|
| Фото | любой | ✅ скачать |
| Документ / PDF / ZIP / etc | ≤ 50 МБ | ✅ скачать |
| Видео | любой | ⏭ только метаданные |
| Любой файл | > 50 МБ | ⏭ только метаданные |

`downloaded: false` + `local_path: null` = файл ожидает отложенной загрузки.

## Восстановление диалогов

- `reply_to_msg_id` = ID сообщения на которое ответили (или ID топика для корневых)
- `reply_to_top_id` = ID топика (для ответов внутри треда)
- Дерево диалогов строится по этим полям

## Credentials (.env)

Хранятся в `~/.openclaw/.env`, никогда в файлах скилла:

```bash
TELEGRAM_COLLECTOR_API_ID=36911437
TELEGRAM_COLLECTOR_API_HASH=***
TELEGRAM_COLLECTOR_PHONE=+7XXXXXXXXXX
TELEGRAM_COLLECTOR_SESSION=telegram_collector
```

Сессия: `skills/telegram-collector/telegram_collector.session`

## Конфигурация (config.json)

```json
{
  "data_dir": "/home/node/.openclaw/workspace/data/telegram-collector",
  "incremental_cron": "0 21 * * *",
  "sources": [
    {
      "channel_id": 1242788123,
      "username": "snowbikerussia",
      "title": "Сноубайк Россия",
      "type": "supergroup_forum",
      "enabled": true
    }
  ],
  "media": {
    "download_photos": true,
    "download_documents": true,
    "max_file_size_mb": 50,
    "skip_video": true
  }
}
```

## Скрипты

```bash
# Первичная загрузка всей истории (пакетами по 10 000, пауза 3 мин)
python3 scripts/initial_load.py

# Инкрементальная загрузка (только новые сообщения, отчёт в Telegram)
python3 scripts/incremental.py

# Двухпроходный анализ: GPT-4o mini (пасс 1) + Claude Sonnet (пасс 2)
# Поддерживает возобновление, считает стоимость, результат → data/{channel}/knowledge_base.md
python3 scripts/analyzer.py              # оба пасса
python3 scripts/analyzer.py --pass1-only # только извлечение фактов
python3 scripts/analyzer.py --pass2-only # только синтез из готовых фактов
python3 scripts/analyzer.py --reset      # начать заново
```

## Расписание

Настройки расписания (cron expression, job ID) хранятся в `config.json` (поле `incremental_cron`) и в `raw/{channel_id}/meta.json` (поле `cron_job_id`).

По завершении инкремента скрипт автоматически отправляет отчёт в Telegram.

Логи: `/tmp/incremental.log`

## Источники

Список источников хранится в `config.json` (поле `sources`).
Детальная информация по каждому каналу (топики, статус загрузки, статистика) — в `raw/{channel_id}/meta.json`.

## Установка зависимостей

```bash
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
python3 /tmp/get-pip.py --break-system-packages
~/.local/bin/pip install --break-system-packages telethon python-dotenv
```