Visão Geral do Sistema de Automação

A gestão manual de comunidades no Telegram torna-se inviável à medida que o volume de interações e a necessidade de migração de usuários crescem. Este projeto propõe a criação de uma interface administrativa baseada em Web para gerenciar múltiplas contas, identificar usuários ativos e automatizar convites em massa via protocolo MTProto.

Diferente de bots convencionais baseados em HTTP API, esta solução utiliza a biblioteca Telethon, permitindo simular o comportamento de um cliente real e acessar funcionalidades restritas a contas de usuário (UserBots).

Funcionalidades Principais

Estrutura do Projeto

A arquitetura foi desenhada para separar a lógica de comunicação com o Telegram da interface de usuário:

.
├── app_server.py         # Ponto de entrada FastAPI e rotas da API
├── core_engine.py        # Lógica de negócio e integração com Telethon
├── account_manager.py    # Script auxiliar para login via terminal
├── settings.py           # Definições de API e caminhos de diretório
├── requirements.txt      # Dependências do ecossistema Python
└── storage/              # Pasta para armazenamento das sessões SQLite

Requisitos e Dependências

• Python: Versão 3.10 ou superior.
• Telethon: Cliente Python para a API do Telegram.
• FastAPI + Uvicorn: Framework para disponibilizar a interface Web.
• Credenciais API: API ID e API Hash obtidos no portal oficial.

Configuração de Credenciais

1. Acesse my.telegram.org.
2. Realize o login com o número de telefone da sua conta principle.
3. Navegue até API development tools.
4. Crie uma nova aplicação para gerar o App api_id e o App api_hash.

Preparação do Ambiente

Recomenda-se o uso de um ambiente virtual para isolar as dependências:

# Criação do ambiente virtual
python -m venv .venv

# Ativação (Linux/macOS)
source .venv/bin/activate

# Ativação (Windows)
.venv\Scripts\activate

# Instalação das bibliotecas necessárias
pip install telethon fastapi uvicorn python-multipart

Implementação da Configuração

Crie o arquivo settings.py para centralizar as variáveis de ambienet e chaves de acesso:

# settings.py
from pathlib import Path

# Credenciais obtidas em my.telegram.org
TELEGRAM_APP_ID = 0  # Insira seu API ID como inteiro
TELEGRAM_APP_HASH = "seu_hash_aqui"

# Configuração de armazenamento
BASE_PATH = Path(__file__).parent
SESSION_PATH = BASE_PATH / "storage"

# Garantir que o diretório de sessões exista
SESSION_PATH.mkdir(exist_ok=True)

Inicialização do Servidor Web

O servidor pode ser iniciado utilizando o Uvicorn para servir a aplicação FastAPI. O exemplo abaixo demonstra a estrutura básica para carregar o painel:

# app_server.py
from fastapi import FastAPI
import uvicorn
from settings import TELEGRAM_APP_ID

app = FastAPI(title="TG Admin Backend")

@app.get("/")
async def health_check():
    return {"status": "online", "api_configured": TELEGRAM_APP_ID != 0}

if __name__ == "__main__":
    uvicorn.run("app_server:app", host="127.0.0.1", port=8000, reload=True)

Tratamento de Conectividade e Restrições

Ao trabalhar com o protocolo MTProto, é essencial considerar os seguintes pontos:

• Proxies: Se o servidor estiver em uma região com bloqueio ao Telegram, a instância do TelegramClient deve ser configurada com parâmetros de proxy (SOCKS5 ou HTTP).
• FloodWait: O Telegram impõe limites de taxa (Rate Limiting). O Telethon gerencia isso automaticamente na maioria dos casos, mas operações em massa devem incluir delays propositais para evitar banimentos.
• Segurança: Nunca compartilhe os arquivos .session gerados, pois eles contêm chaves de acesso total às contas conectadas.

Formatos de Links Suportados

O sistema processa diferentes tipos de identificadores de grupos:

• Links públicos: https://t.me/nome_do_grupo
• Links de convite privados: https://t.me/+CodigoConvite
• Usernames diretos: @nome_do_grupo