doudou/telegram-customer-bot

Fork 0

Files

你的用户名 0406b5664f chore: initial commit

2025-11-01 21:58:31 +08:00

6.1 KiB

Raw Permalink Blame History

Telegram 整合机器人 - NewBot925 🤖

一个功能强大的Telegram机器人，集成了客服系统和搜索镜像功能。

项目说明

该项目构建了一个多管理员协作的 Telegram 客服机器人，支持消息自动转发、镜像搜索与统计看板等高级功能。通过模块化架构与丰富的脚本工具，可以快速部署、生成会话凭证并实现自动化运维。项目已预置示例配置与日志目录，适合作为客服团队的统一入口或集成至更大的业务系统。

✨ 核心功能

客服中转系统

🔄 消息自动转发：客户消息自动转发给管理员
💬 便捷回复：管理员直接回复转发消息即可回复客户
👥 会话管理：追踪和管理多个客户会话
📊 实时统计：消息数量、会话状态等统计信息

智能功能

⏰ 营业时间管理：自动识别工作时间
🤖 自动回复：非工作时间自动回复
📝 消息历史：完整的对话记录存储
🏷️ 标签系统：客户和会话标签管理

管理功能

📈 统计仪表板：查看详细统计信息
🔍 会话监控：实时查看活跃会话
📢 广播消息：向所有客户发送通知
⚙️ 动态配置：运行时调整设置

🏗️ 系统架构

telegram-customer-bot/
├── src/
│   ├── core/           # 核心模块
│   │   ├── bot.py      # 主机器人类
│   │   ├── router.py   # 消息路由系统
│   │   └── handlers.py # 处理器基类
│   ├── modules/        # 功能模块
│   │   └── storage/    # 数据存储
│   ├── utils/          # 工具函数
│   │   ├── logger.py   # 日志系统
│   │   ├── exceptions.py # 异常处理
│   │   └── decorators.py # 装饰器
│   └── config/         # 配置管理
├── tests/              # 测试文件
├── logs/               # 日志文件
├── data/               # 数据存储
└── main.py            # 程序入口

🚀 快速开始

1. 环境要求

Python 3.9+
pip

2. 安装

# 克隆或下载项目
cd /Users/lucas/telegram-customer-bot

# 安装依赖
pip install -r requirements.txt

3. 配置

复制 .env.example 为 .env 并填写配置：

cp .env.example .env

编辑 .env 文件（已配置你的信息）：

BOT_TOKEN: 你的机器人 Token
ADMIN_ID: 你的 Telegram ID (7363537082)
其他配置根据需要调整

4. 运行

python main.py

📝 使用指南

客户端命令

/start - 开始使用机器人
/help - 获取帮助信息
/status - 查看服务状态
/contact - 联系人工客服

管理员命令

/stats - 查看统计信息
/sessions - 查看活跃会话
/reply <用户ID> <消息> - 回复指定用户
/broadcast <消息> - 广播消息
/settings - 机器人设置

回复客户消息

直接回复：回复机器人转发的消息
命令回复：使用 /reply 命令
快捷按钮：使用消息下方的快捷操作按钮

🔧 高级配置

环境变量说明

变量名	说明	默认值
`BOT_TOKEN`	Telegram Bot Token	必填
`ADMIN_ID`	管理员 Telegram ID	必填
`LOG_LEVEL`	日志级别	INFO
`DATABASE_TYPE`	数据库类型	sqlite
`BUSINESS_HOURS_START`	营业开始时间	09:00
`BUSINESS_HOURS_END`	营业结束时间	18:00
`TIMEZONE`	时区	Asia/Shanghai

功能开关

在 .env 文件中可以控制功能开关：

ENABLE_AUTO_REPLY - 自动回复
ENABLE_STATISTICS - 统计功能
ENABLE_CUSTOMER_HISTORY - 客户历史记录

🛡️ 安全特性

✅ 权限控制：严格的管理员权限验证
✅ 速率限制：防止消息轰炸
✅ 错误处理：完善的异常捕获和处理
✅ 日志记录：详细的操作日志
✅ 数据加密：敏感数据加密存储（可选）

📊 监控和维护

日志文件

位置：logs/bot.log
JSON 格式：logs/bot.json
自动轮转：达到 10MB 自动轮转

数据库维护

自动清理：30天以上的已关闭会话
备份建议：定期备份 data/bot.db

性能优化

异步处理：所有 I/O 操作异步执行
连接池：数据库连接池管理
缓存：频繁访问数据缓存

🔄 更新和升级

# 备份数据
cp -r data data_backup

# 更新代码
git pull  # 如果使用git

# 更新依赖
pip install -r requirements.txt --upgrade

# 重启机器人
python main.py

🐛 故障排除

常见问题

机器人无响应
- 检查 Token 是否正确
- 检查网络连接
- 查看日志文件
消息未转发
- 确认管理员 ID 正确
- 检查机器人权限
数据库错误
- 检查 data 目录权限
- 尝试删除并重建数据库

调试模式

在 .env 中设置 DEBUG=true 启用调试模式。

📈 扩展开发

添加新功能模块

在 src/modules/ 创建新模块
继承 BaseHandler 类
在 bot.py 中注册处理器

自定义中间件

from src.core.router import MessageRouter

router = MessageRouter(config)

@router.middleware()
async def custom_middleware(context, telegram_context):
    # 处理逻辑
    return True  # 继续处理

🤝 技术支持

查看日志：tail -f logs/bot.log
数据库查询：使用 SQLite 工具打开 data/bot.db
性能监控：查看 /stats 命令输出

📄 许可证

MIT License

🙏 致谢

python-telegram-bot - Telegram Bot API 库
SQLite - 轻量级数据库
所有开源贡献者

当前版本: 1.0.0 最后更新: 2025-09-24 作者: 阿泰 (@xiaobai_80)

6.1 KiB Raw Permalink Blame History Unescape Escape