Agent Skills: Telegram Send

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

| What | Path | |------|------| | Tool | $TG_TOOLS_PATH/tools/tg_send.py | | Shared lib | $TG_TOOLS_PATH/tg_utils/ | | Telegram Session | $SALES_PATH/telegram/sessions/telegram_session.session | | ENV | $SALES_PATH/.env | | Send Log | $TG_TOOLS_PATH/data/send_log.json |

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

| Parameter | Description | Default | |-----------|-------------|---------| | --input FILE | CSV file (or - for stdin) | required | | --message TMPL | Message template with {name} | - | | --message-file FILE | Template from file | - | | --dry-run | Preview only | true (default) | | --send | Actual sending | false | | --test N | Send only to first N | - | | --max N | Max number of messages | - | | --cold | Limits for cold outreach (5/day, batch pauses) | false | | --delay MIN MAX | Override delay (sec) | 20 60 | | --status | Show send log | - | | --reset-log | Reset log | - | | --reset-cooldown | Reset flood cooldown | - | | --key-col NAME | Column for idempotency | key | | --name-col NAME | Column for name | name | | --phone-col NAME | Column for phone | phone | | --user-col NAME | Column for username | username | | --msg-col NAME | Column for message | message |

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/)

| Module | Purpose | |--------|---------| | auth.py | Connecting to Telegram, loading credentials | | phone.py | Phone normalization (UA/PL/IE/US) | | rate_limit.py | Delays, batch pauses, flood cooldown | | send_log.py | Send log (idempotency) | | contacts.py | Entity resolution (username/phone), ImportContactsRequest | | output.py | JSON-line output for composition |

Rate Limiting

| Mode | Delay | Limit/day | Batch pause | |------|-------|-----------|-------------| | Warm (default) | 20-60s | 35 | - | | Cold (--cold) | 30-60s | 5 | 30min every 3 |

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

| Problem | Solution | |---------|----------| | FloodWaitError | Automatic 24h cooldown. --reset-cooldown to reset | | PeerFloodError | 48h cooldown. Wait or --reset-cooldown | | SessionExpired | telegram-session | | UserPrivacyRestrictedError | Person has blocked DMs | | "Not authorized" | Need QR login via tg-auth |

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