telegram-send

telegram-send 是一个通过 Telegram 发送私信的工具，底层使用 Telethon，支持从 CSV 文件读取收件人并批量发送消息。

用途

当需要通过 Telegram 发送消息时使用，例如“send via telegram”“message everyone through telegram”“telegram campaign”，或数据中 preferred_channel = Telegram 时。

依赖

Python 3、Telethon、python-dotenv，以及一个有效的 Telegram 会话。

相关路径

工具：$TG_TOOLS_PATH/tools/tg_send.py 共享库：$TG_TOOLS_PATH/tg_utils/ Telegram 会话：$SALES_PATH/telegram/sessions/telegram_session.session 环境变量：$SALES_PATH/.env 发送日志：$TG_TOOLS_PATH/data/send_log.json

使用方式

第一步：准备 CSV。CSV 至少包含列：key,name,phone,username,message。示例： key,name,phone,username,message p-001,Alice,+380XXXXXXXXX,,Hello Alice! Message text. p-002,Ruslan,,,Nizami_ua,Hello Ruslan! 也可以不含 message 列，改用 --message 模板。

第二步：dry-run（验证）。 python3 $TG_TOOLS_PATH/tools/tg_send.py
--input contacts.csv --dry-run 或使用模板： python3 $TG_TOOLS_PATH/tools/tg_send.py
--input contacts.csv --message "Hello, {name}! Text." --dry-run

第三步：发送。 python3 $TG_TOOLS_PATH/tools/tg_send.py
--input contacts.csv --send 或先测试第一个联系人： python3 $TG_TOOLS_PATH/tools/tg_send.py
--input contacts.csv --send --test 1

参数

--input FILE：CSV 文件（或 - 表示 stdin），必填。 --message TMPL：带 {name} 的消息模板。 --message-file FILE：从文件读取模板。 --dry-run：仅预览，默认 true。 --send：实际发送，默认 false。 --test N：仅发送给前 N 个。 --max N：最大消息数。 --cold：冷启动外联限制（每天 5 条，分批暂停），默认 false。 --delay MIN MAX：覆盖延迟（秒），默认 20 60。 --status：显示发送日志。 --reset-log：重置日志。 --reset-cooldown：重置洪水冷却。 --key-col NAME：幂等键列，默认 key。 --name-col NAME：姓名列，默认 name。 --phone-col NAME：电话列，默认 phone。 --user-col NAME：用户名列，默认 username。 --msg-col NAME：消息列，默认 message。

架构

Claude（LLM）负责：选择收件人、撰写文本、生成 CSV、解释结果、更新 CRM。 tg-send 负责：Telegram 会话、电话规范化、消息投递、速率限制、幂等、洪水处理。

共享库（tg_utils/）

auth.py：连接 Telegram、加载凭据。 phone.py：电话规范化（UA/PL/IE/US）。 rate_limit.py：延迟、分批暂停、洪水冷却。 send_log.py：发送日志（幂等）。 contacts.py：实体解析（用户名/电话）、ImportContactsRequest。 output.py：用于组合的 JSON-line 输出。

速率限制

Warm（默认）：延迟 20-60 秒，每天上限 35 条，无分批暂停。 Cold（--cold）：延迟 30-60 秒，每天上限 5 条，每 3 条暂停 30 分钟。

输出

Stdout：JSON 行（用于管道/组合）： {"event":"send","status":"ok","key":"p-001","target":"@user","name":"Alice","ts":"..."} {"event":"summary","sent":5,"failed":1,"skipped":2,"ts":"..."} Stderr：人类可读的进度。

限制

并非所有电话号码都在 Telegram 注册。隐私设置可能阻止发送（UserPrivacyRestrictedError）。 FloodWaitError = 24 小时冷却，PeerFloodError = 48 小时冷却。临时联系人发送后会自动移除。

故障排查

FloodWaitError：自动 24 小时冷却，可用 --reset-cooldown 重置。 PeerFloodError：48 小时冷却，等待或使用 --reset-cooldown。 SessionExpired：使用 telegram-session。 UserPrivacyRestrictedError：对方已屏蔽私信。 “Not authorized”：需要通过 tg-auth 进行 QR 登录。

技能介绍