tgscope

OSINT, scraping y archivado de Telegram.
Una aplicación web local que se ejecuta completamente en tu máquina y solo se comunica con Telegram.

npm install
npm start

Luego abre http://127.0.0.1:5173. La primera ejecución te guía a través de las credenciales de la API, un inicio de sesión por QR y la carga de tus diálogos. Telegram es el único servidor con el que se comunica. No hay ninguna cuenta que crear, ni telemetría ni ningún servicio intermedio: lo que recopilas permanece en un archivo SQLite que te pertenece.

Sucesor de telegram-scraper, telescope y Harrier, construido sobre Telethon 1.44.

Recopilar	Canales, grupos y temas de foro en varias cuentas, con multimedia, deduplicación y reanudación
Investigar	Teléfono, @username, id o enlace t.me a un perfil, todas las fotos históricas y un diff desde la última vez
Exportar	Diez formatos, desde un CSV simple hasta un paquete de evidencias con hashes
Se ejecuta en	Node 18+, Python 3.12+, SQLite. Una base de datos, una carpeta, sin servicios

Qué hace

Recopilar

• Cada canal, grupo, tema de foro y chat, en cada cuenta con sesión iniciada, en un único árbol seleccionable con el id completo -100 junto al nombre y una insignia de la cuenta que lo ve
• Cada diálogo se recopila bajo la cuenta que realmente puede leerlo, de modo que una selección que abarca dos cuentas inicia una ejecución por cuenta
• Mensajes con metadatos completos: vistas, reenvíos, reacciones, fechas de edición, álbumes, encuestas, geolocalización, enlaces, cadenas de respuestas, autores de publicaciones y el origen del reenvío de cada mensaje
• Grupos de foro divididos por tema — recopila temas individuales en lugar de grupos completos
• Multimedia descargada en paralelo y deduplicada por SHA-256 y por id de archivo de Telegram, de modo que un archivo reenviado a cinco canales se almacena una sola vez
• Reanudación desde una marca de agua por diálogo; el modo continuo vuelve a comprobar a intervalos
• Las colecciones guardadas vuelven a ejecutar una selección con un clic

Investigar

• Busca un número de teléfono, @username, id de usuario o enlace t.me
• Biografía, indicadores, precisión del último acceso como indicador de privacidad, chats en común, canal personal
• Cualquier cosa que Telegram decida revelar sobre la cuenta: el mes en que se registró, el país al que pertenece su número de teléfono, cuándo se renombró por última vez la persona o cambió su foto, su temporizador de autoeliminación, el nombre mostrado en los reenvíos restringidos. Advertencia: normalmente no revela nada de ello. Esos campos acompañan al panel antiestafa que Telegram muestra cuando un desconocido te escribe, y vuelven vacíos para un perfil que consultas directamente, así que considéralos un extra en lugar de algo con lo que contar
• Las cuentas de empresa sí proporcionan de forma fiable una dirección postal, coordenadas y una zona horaria
• Todas las fotos de perfil visibles, con hash SHA-256 y un hash perceptual, mostradas como una galería
• Los hashes perceptuales se comparan entre cuentas, de modo que la misma imagen en un segundo perfil aparece
• Los remitentes de mensajes se registran a medida que se extraen, de modo que un nombre en el navegador es un enlace funcional a una búsqueda incluso cuando la persona no tiene nombre de usuario; "Sync members" rellena eso para cualquier cosa recopilada anteriormente
• Cada búsqueda se guarda como instantánea y se compara: cambios de nombre de usuario, cambios de nombre visible, ediciones de biografía, fotos añadidas o eliminadas, cambios de privacidad

Exportar

Formato	Qué obtienes
csv	Un archivo por diálogo
json / jsonl	Metadatos completos; JSONL se transmite fila por fila
xlsx	Hojas para mensajes, multimedia, participantes y reacciones
html	Informe autónomo: estadísticas, actividad, principales remitentes, orígenes de reenvíos, tabla con búsqueda
markdown	El mismo informe como texto
gexf / edges	Grafo de reenvíos para Gephi y Maltego
sqlite	Una base de datos autónoma solo con los diálogos seleccionados
bundle	ZIP con datos, multimedia, un manifiesto de hashes SHA-256 y el registro de la recopilación

Requisitos

• Node.js 18+
• Python 3.12+
• Credenciales de la API de my.telegram.org/apps

npm install crea el entorno de Python en server/.venv e instala ambos lados.

Dónde se guarda todo

Qué	Dónde
Configuración	~/.config/tgscope/config.json (modo 600)
Base de datos	~/.local/share/tgscope/tgscope.db (WAL, FTS5)
Multimedia	~/.local/share/tgscope/media/
Exportaciones	~/.local/share/tgscope/exports/<timestamp>-<label>/

Una base de datos lo contiene todo, lo que hace posible la búsqueda entre diálogos, la tabla de usuarios compartida, la deduplicación de medios y el grafo de reenvíos.

Diseño de medios

Los archivos se organizan por tipo de diálogo, luego por diálogo, luego por tema del foro, luego por tipo de medio:

media/
├── channels/technews_-1001234567890/
│   ├── photos/00004711-8001-conference-slides.jpg
│   └── documents/00004802-8210-quarterly-report.pdf
├── groups/pythondev_-1009876543210/
│   ├── general/photos/…
│   └── help/voice/00000004-9004-voice.ogg
└── profiles/123456789/000-5544332211.jpg

Los nombres de directorio combinan el identificador con el id completo, los títulos no ASCII se transliteran y los nombres de archivo se rellenan con ceros para que se ordenen cronológicamente.

Límites de velocidad y seguridad de la cuenta

Cada llamada a Telegram pasa por un gobernador por cuenta con un token bucket y retroceso FloodWait, y cada lectura paginada —mensajes, diálogos, miembros, fotos de perfil— espera a que pase un flood y se reanuda en lugar de fallar la ejecución. Tres perfiles:

Perfil	Trabajadores de medios	Espaciado entre solicitudes	Esperas absorbidas en silencio
stealth	1	1.6 s	hasta 180 s
balanced	4	0.35 s	hasta 90 s
fast	8	ninguno	hasta 45 s

Las esperas más largas se anuncian en el registro de actividad y se aguardan; doce seguidas en una misma lectura hacen que se abandone y se informe de ello.

Se admiten varias cuentas. Marca una como burner en Ajustes y las búsquedas de teléfono se ejecutarán automáticamente en ella, porque esa es la única operación arriesgada:

Una búsqueda de teléfono importa el número como contacto por un momento y lo elimina de nuevo. Si el propietario ya tiene tu número guardado, puede que vea una notificación de "se unió a Telegram". tgscope pregunta primero, siempre, y la tarjeta de perfil registra qué cuenta utilizó.

Desarrollo

npm test                    # 92 backend and 42 frontend tests, no network needed
npm run build               # production bundle of the client

El backend es FastAPI sobre un núcleo de Telethon, probado contra un cliente de Telethon falso: el scraper, los exportadores, el diseño de medios y cada migración de esquema. Las pruebas del frontend cubren la lógica pura detrás del navegador, la aritmética de periodos, el agrupamiento en histogramas y el formato de números y marcas de tiempo, y renderizan cada pantalla dos veces, una vacía y otra poblada.