Banner

TeleStat 是一款基于 Python 的 Telegram 数据统计与可视化工具,支持聊天记录采集、数据分析及多维度报告生成。通过 Telegram API 实现数据收集,结合 Pandas、Matplotlib 等库完成统计分析,并生成包含用户画像、活跃趋势、词云图等内容的可视化报告。

• 数据采集:获取聊天记录、用户信息及头像,支持私聊、群组、超级群组等多种聊天类型。
• 统计分析:
  • 消息总数、日均发送量、独立用户数等基础统计;
  • 活跃群聊 TOP 排行、高频互动用户、回复频率分析;
  • 消息长度分布、媒体消息占比、活跃时段趋势。
• 可视化报告:生成包含用户头像、关键指标、群聊活跃度进度条及词云图的综合报告。
• 配置管理:支持环境变量、交互式配置及配置文件持久化存储。

• 访问 Telegram API 平台 注册账号,获取 API_ID 和 API_HASH。

pip install -r requirements.txt 

python main.py 

• 首次运行将提示输入手机号、API 信息,支持选择 数据采集、分析、可视化 单一模式或完整流程。
• 报告默认生成至 output/ 目录,文件名包含时间戳(如 tgstat_report_20231001_1430.png)。

可通过环境变量覆盖默认配置,优先级高于配置文件:

export TG_API_ID=your_api_id 
export TG_API_HASH=your_api_hash 
export TG_PHONE=+86138xxxxxxxx 

• 交互式配置信息自动保存至 user_config.json,包含 API 凭证及会话信息。
• 手动修改路径:config.py 中定义的 DATA_DIR、AVATAR_DIR 等路径可自定义。

• 报告默认使用 ZhuZiAWan-2.ttc 字体,需将字体文件放置于项目根目录。
• 修改字体路径:编辑 visualization.py 中的 font_path 参数,指向自定义字体文件(.ttf/.ttc 格式)。

• 运行时通过命令行参数指定报告保存路径,或修改 config.py 中的 OUTPUT_DIR 全局变量。

本项目采用 WTFPL(Do What The Fuck You Want To Public License) 许可协议,允许自由使用、修改及分发。

WTFPL LICENSE 
------------ 
Version 2, December 2004 
Copyright (C) 2004 Sam Hocevar <sam@hocevar.net> 
Everyone is permitted to copy and distribute verbatim or modified copies of this license document, and changing it is allowed as long as the name is changed. 
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE 
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 
0. You just DO WHAT THE FUCK YOU WANT TO. 

• 问题反馈:通过 GitHub Issues 提交功能请求或 Bug 报告。
• 代码贡献:Fork 仓库后提交 Pull Request,建议先创建 Issue 说明改进方向。

示例截图

项目地址:GitHub.com/OutlinedArc217/TeleStat
维护者:OutlinedArc217