name: telegram-send description: Telegram DM sending from CSV, rate limiting, idempotency

Telegram Send

Sending messages via Telegram (Telethon) with CSV input

When to use

• "send via telegram"
• "message everyone through telegram"
• "telegram campaign"
• When preferred_channel = Telegram in data

Dependencies

• Python 3, Telethon, python-dotenv
• Active Telegram session

Paths

How to run

Step 1: Prepare CSV

Claude prepares CSV with recipients. Minimum columns:

key,name,phone,username,message
p-001,Alice,+380XXXXXXXXX,,Hello Alice! Message text.
p-002,Ruslan,,,Nizami_ua,Hello Ruslan!

Or without the message column -- then use the --message template.

Step 2: Dry-run (verification)

python3 $TG_TOOLS_PATH/tools/tg_send.py \
    --input contacts.csv --dry-run

Or with a template:

python3 $TG_TOOLS_PATH/tools/tg_send.py \
    --input contacts.csv --message "Hello, {name}! Text." --dry-run

Step 3: Send

python3 $TG_TOOLS_PATH/tools/tg_send.py \
    --input contacts.csv --send

# Or test on the first contact:
python3 $TG_TOOLS_PATH/tools/tg_send.py \
    --input contacts.csv --send --test 1

Parameters

Architecture

Claude (LLM) is responsible for: selecting recipients, composing text, generating CSV, interpreting results, updating CRM.

tg-send is responsible for: Telegram session, phone normalization, message delivery, rate limiting, idempotency, flood handling.

Shared library (tg_utils/)

Rate Limiting

Output

Stdout: JSON lines (for pipe/composition):

{"event":"send","status":"ok","key":"p-001","target":"@user","name":"Alice","ts":"..."}
{"event":"summary","sent":5,"failed":1,"skipped":2,"ts":"..."}

Stderr: human-readable progress.

Limitations

• Not all phone numbers are registered on Telegram
• Privacy settings can block (UserPrivacyRestrictedError)
• FloodWaitError = 24h cooldown, PeerFloodError = 48h cooldown
• Temporary contacts are automatically removed after sending

Troubleshooting

Related skills

• telegram-check -- checking replies
• telegram-session -- if session is broken
• email-send-direct -- single email
• email-send-bulk -- mass email sending
• whatsapp-send -- alternative channel

Related tools

All Telegram tools: $TG_TOOLS_PATH/tools/

• tg-auth -- session, QR login
• tg-contacts -- export/import contacts, lookup
• tg-groups -- groups, posting, members
• tg-scrape -- channel search, scraping