telegram-bot-dumper

Fácil extração de todo o conteúdo de bots do Telegram.

Entrada: apenas o token do bot.

Saída: nome e informações do bot, todo o histórico de texto e mídia dos chats, informações e fotos dos usuários do bot.

---

Esta é uma implementação em Python.

🚀 Versão em Golang rápida, por ScBoln.

Visualizador web

Uma interface de navegador semelhante ao Telegram Web para um dump: lista de chats, histórico completo de mensagens com mídia embutida, perfis de usuários com carrossel de fotos e busca global em todas as conversas ao mesmo tempo. Modo ao vivo suportado: ele executa o dumper em segundo plano e transmite novas mensagens para o navegador em tempo real.

Caso de uso — pentest de um token de bot vazado. Tokens de bots do Telegram aparecem constantemente em um engajamento — codificados diretamente em um aplicativo mobile/desktop, commitados em um repositório, ou presentes em um log de CI, arquivo de configuração ou bundle do lado do cliente. Por si só, um token parece um achado de baixa severidade; carregá-lo aqui mostra o raio de impacto real. Para um bot interno (help desk, assistente de TI/DevOps, assistente de IA), isso significa todas as conversas dos funcionários com ele — nomes de hosts internos, perfis de VPN, credenciais e detalhes de infraestrutura — navegáveis e pesquisáveis, permitindo dimensionar o impacto e evidenciar o achado no seu relatório.

Executar a partir de uma imagem pré-construída (Docker Hub)

docker run --rm -p 8010:8010 -v "$PWD:/data" soxoj/telegram-bot-dumper-web

Ou construir localmente

docker compose up --build      # builds and serves on http://127.0.0.1:8010

Ou sem Docker

pip install -r requirements.txt
python webapp/server.py        # serves the current directory's dumps on :8010

Abra http://127.0.0.1:8010 e cole um token de bot para selecionar a pasta de dump correspondente. A visualização somente leitura é livre de autenticação, local e não requer credenciais de API. O modo ao vivo adicionalmente requer API_ID/API_HASH de my.telegram.org, passados via ambiente — nunca embutidos na imagem:

# one-off container
docker run --rm -p 8010:8010 -v "$PWD:/data" \
  -e API_ID=123456 -e API_HASH=abc... soxoj/telegram-bot-dumper-web

# or with docker compose: put them in a local .env (see .env.example)
cp .env.example .env && $EDITOR .env && docker compose up

As variáveis de ambiente PORT e HOST substituem os padrões (8010, 127.0.0.1).

Funcionalidades

• Extrai as mensagens do bot com conteúdo de mídia percorrendo os ids de mensagem para cima (padrão) ou para baixo (--down / --start-from-id).
• Modo de escuta ao vivo (--listen-only): recebe novas mensagens em tempo real e oferece extrair o histórico para baixo a partir do primeiro id observado.
• Resolve informações de usuário tanto para mensagens recebidas quanto para respostas enviadas pelo bot.
• Modos leves para enumeração rápida de usuários: pula mídia, pula histórico de texto por chat, grava usuários em um único CSV.
• Mensagens de grupo / supergrupo são marcadas com [from:USER][group:CHAT]. DMs enviadas pelo bot são marcadas com [to:USER].
• Monitoramento de grupos: se o bot foi adicionado a um grupo/supergrupo E seu modo de privacidade está desabilitado, o bot recebe todas as mensagens do grupo — não apenas comandos e respostas — e --listen-only as extrairá em tempo real. Com o modo de privacidade habilitado (o padrão), o bot só vê comandos, menções e respostas.

Requisitos

• Python >= 3.6
• Telethon (veja requirements.txt para a versão fixada)
• Registre uma aplicação no Telegram para obter API_ID e API_HASH

Usando como ferramenta de linha de comando

pip install -r requirements.txt

# Telegram API credentials from https://my.telegram.org (read from the environment)
export API_ID=123456
export API_HASH=abc...

Início rápido — dump completo (comportamento padrão)

Percorre os ids 1..∞ para cima em lotes de 200, baixando cada mensagem, toda a mídia e todas as fotos de perfil dos usuários. Por padrão, o dumper continua escutando novas mensagens recebidas após o término do dump. Para sair imediatamente após a extração do histórico (ideal para scripts e cron jobs), passe --no-listen.

./dumper.py --token 12345678:ABCe2rPVteUWZ7wLeCqCb3CH3ilUY_fLabc

Extrair para baixo a partir da mensagem mais recente

Para um bot ativo, a varredura para cima encontra um longo trecho de ids antigos removidos (excluídos/expirados) e desiste. Percorrer para baixo a partir do id mais recente é muito mais produtivo. --down sonda automaticamente o limite superior (potências de 10 até 10⁹) e começa a partir do id não vazio mais alto que encontrar:

./dumper.py --token TOKEN --down

Nota. O Telegram não retém o histórico de mensagens de bots para sempre. Empiricamente, apenas as últimas centenas de milhares de mensagens permanecem acessíveis — em nossos testes, um bot movimentado expôs aproximadamente as últimas 500K mensagens antes de messages.getMessages começar a retornar apenas MessageEmpty para ids mais antigos. Se seu bot historicamente processou mais tráfego do que isso, o histórico mais antigo simplesmente se foi no lado do servidor e nenhuma flag irá recuperá-lo.

Se você já conhece um id de mensagem recente (por exemplo, um que viu em tempo real), pode pular a sondagem e começar exatamente a partir dele:

./dumper.py --token TOKEN --start-from-id 11922524

Modo de escuta

Não extraia nada; apenas observe o que chega. Na primeira mensagem recebida, o script oferecerá iniciar uma extração para baixo a partir desse id:

./dumper.py --token TOKEN --listen-only

Enumeração leve de usuários (CSV, sem mídia, sem histórico por chat)

Útil quando você só precisa de uma lista de quem conversou com o bot — sem zips, sem jpegs, sem *_history.txt por chat.

./dumper.py --token TOKEN --down --users-csv --no-photos --no-media --no-history

Saída: <bot_id>/users.csv com as colunas id, username, first_name, last_name, phone, lang_code, bot, premium, verified, scam, fake.

Retomar após um crash / FloodWait

A varredura para baixo imprime Requesting message ids X..Y ... para cada lote. Se a execução for interrompida, reinicie a partir do último limite inferior impresso:

./dumper.py --token TOKEN --start-from-id <Y>

Ajustando o tamanho do lote

Lotes menores → feedback mais rápido no log e janela de recuperação mais curta após um FloodWait. Lotes maiores → menos round-trips ao escanear intervalos de ids esparsos / removidos. Valores até 1000 funcionam bem na prática.

./dumper.py --token TOKEN --down --batch-size 50
./dumper.py --token TOKEN --down --batch-size 500
./dumper.py --token TOKEN --down --batch-size 1000

Outras flags