Coletor de Histórias do Telegram 📱

Um script Python que permite coletar e baixar automaticamente histórias dos seus amigos do Telegram usando a biblioteca Telethon. O script monitora e salva continuamente fotos e vídeos das histórias, junto com seus metadados.

TGSS - Interface Principal

Nota Importante Sobre Acesso a Histórias ⚠️

Devido às restrições da API do Telegram, este script só pode acessar histórias de:

• Usuários que você adicionou à sua lista de amigos
• Usuários cujas configurações de privacidade permitem que você veja suas histórias

Esta é uma limitação da API do Telegram e não pode ser contornada.

Recursos 🚀

• Coleta automaticamente todas as histórias disponíveis dos seus amigos do Telegram
• Baixa fotos e vídeos das histórias
• Armazena metadados em banco de dados SQLite
• Exporta dados para planilha Excel
• Monitoramento em tempo real com intervalos personalizáveis
• Carimbo de data/hora definido para (UTC+2)
• Mantém registro de histórias já baixadas anteriormente
• Capacidade de retomada
• Mecanismo de repetição automática

Pré-requisitos 📋

Antes de executar o script, você precisará de:

• Python 3.7 ou superior
• Conta no Telegram
• Credenciais da API do Telegram
• Amigos no Telegram cujas histórias você deseja rastrear

Pacotes Python necessários

pip install -r requirements.txt

Conteúdo do requirements.txt:

telethon
openpyxl
schedule

Obtendo Credenciais da API do Telegram 🔑

1. Visite https://my.telegram.org/auth
2. Faça login com seu número de telefone
3. Clique em "API development tools"
4. Preencha o formulário:
   • Título do aplicativo: Nome do seu aplicativo
   • Nome curto: Nome curto do seu aplicativo
   • Plataforma: Pode ser deixado como "Desktop"
   • Descrição: Breve descrição do seu aplicativo
5. Clique em "Create application"
6. Você receberá:
   • api_id: Um número
   • api_hash: Uma sequência de letras e números

Mantenha essas credenciais seguras, você precisará delas para executar o script!

Configuração e Execução 🔧

1. Clone o repositório:

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

2. Instale os requisitos:

pip install -r requirements.txt

3. Execute o script:

python TGSS.py

4. Na primeira execução, você será solicitado a inserir:
   • Seu API ID
   • Seu API Hash
   • Seu número de telefone (com código do país)
   • Código de verificação (enviado para seu Telegram)
   • Intervalo de verificação em segundos (padrão é 60)

Como Funciona 🔄

O script:

1. Conecta-se à sua conta do Telegram
2. Verifica periodicamente novas histórias dos seus amigos
3. Baixa quaisquer novas histórias (fotos/vídeos)
4. Armazena metadados em um banco de dados SQLite
5. Exporta informações para um arquivo Excel
6. Executa continuamente até ser interrompido (Ctrl+C)

Armazenamento de Dados 💾

Estrutura do Banco de Dados (stories.db)

Banco de dados SQLite contendo:

• user_id: ID do usuário do Telegram do criador da história
• story_id: Identificador único da história
• timestamp: Quando a história foi publicada (UTC+2)
• filename: Nome do arquivo local da mídia baixada

Exportação CSV e Excel (stories_export.csv/xlsx)

Arquivo de exportação contendo as mesmas informações do banco de dados, útil para:

• Visualização fácil dos metadados das histórias
• Filtragem e classificação
• Análise de dados
• Compartilhamento de dados com outras pessoas

Armazenamento de Mídia 📁

• Fotos são salvas como: {user_id}_{story_id}.jpg
• Vídeos são salvos com sua extensão original: {user_id}_{story_id}.{extensão}
• Todos os arquivos de mídia são salvos no diretório do script

Recursos em Detalhe 🔍

Monitoramento Contínuo

• Intervalo de verificação personalizável (padrão: 60 segundos)
• Executa continuamente até ser interrompido manualmente
• Mantém o estado entre execuções
• Evita downloads duplicados

Manipulação de Mídia

• Suporta fotos e vídeos
• Detecta automaticamente o tipo de mídia
• Preserva a qualidade original
• Gera nomes de arquivo únicos

Tratamento de Erros 🛠️

O script inclui:

• Mecanismo de repetição automática para downloads com falha
• Registro de erros para operações com falha
• Tratamento de erros de conexão
• Preservação do estado em caso de interrupção

Limitações ⚠️

• Sujeito aos limites de taxa do Telegram
• As histórias devem estar atualmente ativas (não expiradas)
• Limites de tamanho de download de mídia se aplicam de acordo com as restrições do Telegram

Contribuindo 🤝

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença 📄

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Aviso Legal ⚖️

Esta ferramenta é apenas para fins educacionais. Certifique-se de:

• Respeitar os Termos de Serviço do Telegram
• Obter as permissões necessárias antes de coletar
• Usar de forma responsável e ética
• Cumprir as regulamentações de proteção de dados
• Respeitar a privacidade do usuário