Telegram Story Scraper 📱

Un script en Python que te permite extraer y descargar automáticamente las historias de tus amigos de Telegram usando la librería Telethon. El script monitorea continuamente y guarda tanto fotos como videos de las historias, junto con sus metadatos.

TGSS - Interfaz principal

Nota importante sobre el acceso a las historias ⚠️

Debido a las restricciones de la API de Telegram, este script solo puede acceder a historias de:

• Usuarios que hayas agregado a tu lista de amigos
• Usuarios cuya configuración de privacidad te permita ver sus historias

Esta es una limitación de la API de Telegram y no se puede eludir.

Características 🚀

• Extrae automáticamente todas las historias disponibles de tus amigos de Telegram
• Descarga tanto fotos como videos de las historias
• Almacena metadatos en una base de datos SQLite
• Exporta datos a una hoja de cálculo Excel
• Monitoreo en tiempo real con intervalos personalizables
• La marca de tiempo está configurada en (UTC+2)
• Mantiene un registro de historias descargadas previamente
• Capacidad de reanudación
• Mecanismo de reintento automático

Requisitos previos 📋

Antes de ejecutar el script, necesitarás:

• Python 3.7 o superior
• Cuenta de Telegram
• Credenciales de API de Telegram
• Amigos en Telegram cuyas historias quieras rastrear

Paquetes Python requeridos

pip install -r requirements.txt

Contenido de requirements.txt:

telethon
openpyxl
schedule

Cómo obtener las credenciales de la API de Telegram 🔑

1. Visita https://my.telegram.org/auth
2. Inicia sesión con tu número de teléfono
3. Haz clic en "API development tools"
4. Completa el formulario:
   • App title: El nombre de tu aplicación
   • Short name: El nombre corto de tu aplicación
   • Platform: Puede dejarse como "Desktop"
   • Description: Breve descripción de tu aplicación
5. Haz clic en "Create application"
6. Recibirás:
   • api_id: Un número
   • api_hash: Una cadena de letras y números

Guarda estas credenciales de forma segura, ¡las necesitarás para ejecutar el script!

Configuración y ejecución 🔧

1. Clona el repositorio:

git clone https://github.com/unnohwn/telegram-story-scraper.git
cd telegram-story-scraper

2. Instala los requisitos:

pip install -r requirements.txt

3. Ejecuta el script:

python TGSS.py

4. En la primera ejecución, se te pedirá que ingreses:
   • Tu API ID
   • Tu API Hash
   • Tu número de teléfono (con código de país)
   • Código de verificación (enviado a tu Telegram)
   • Intervalo de comprobación en segundos (por defecto es 60)

Cómo funciona 🔄

El script:

1. Se conecta a tu cuenta de Telegram
2. Verifica periódicamente si hay nuevas historias de tus amigos
3. Descarga cualquier historia nueva (fotos/videos)
4. Almacena los metadatos en una base de datos SQLite
5. Exporta la información a un archivo Excel
6. Se ejecuta continuamente hasta que se interrumpe (Ctrl+C)

Almacenamiento de datos 💾

Estructura de la base de datos (stories.db)

Base de datos SQLite que contiene:

• user_id: ID de usuario de Telegram del creador de la historia
• story_id: Identificador único de la historia
• timestamp: Cuándo se publicó la historia (UTC+2)
• filename: Nombre de archivo local del medio descargado

Exportación a CSV y Excel (stories_export.csv/xlsx)

Archivo de exportación que contiene la misma información que la base de datos, útil para:

• Visualización fácil de los metadatos de las historias
• Filtrar y ordenar
• Análisis de datos
• Compartir datos con otros

Almacenamiento de medios 📁

• Las fotos se guardan como: {user_id}_{story_id}.jpg
• Los videos se guardan con su extensión original: {user_id}_{story_id}.{extension}
• Todos los archivos multimedia se guardan en el directorio del script

Características en detalle 🔍

Monitoreo continuo

• Intervalo de comprobación personalizable (por defecto: 60 segundos)
• Se ejecuta continuamente hasta que se detiene manualmente
• Mantiene el estado entre ejecuciones
• Evita descargas duplicadas

Manejo de medios

• Soporta tanto fotos como videos
• Detecta automáticamente el tipo de medio
• Conserva la calidad original
• Genera nombres de archivo únicos

Manejo de errores 🛠️

El script incluye:

• Mecanismo de reintento automático para descargas fallidas
• Registro de errores para operaciones fallidas
• Manejo de errores de conexión
• Preservación del estado en caso de interrupción

Limitaciones ⚠️

• Sujeto a los límites de velocidad de Telegram
• Las historias deben estar actualmente activas (no expiradas)
• Se aplican límites de tamaño de descarga de medios según las restricciones de Telegram

Contribuciones 🤝

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia 📄

Este proyecto está bajo la licencia MIT; consulta el archivo LICENSE para más detalles.

Aviso legal ⚖️

Esta herramienta es solo para fines educativos. Asegúrate de:

• Respetar los Términos de servicio de Telegram
• Obtener los permisos necesarios antes de extraer datos
• Usarla de manera responsable y ética
• Cumplir con las regulaciones de protección de datos
• Respetar la privacidad de los usuarios