Awesome-omni-skill telegram-telethon

This skill should be used for comprehensive Telegram automation via Telethon API. Use for sending/receiving messages, monitoring chats, running a background daemon that triggers Claude Code sessions, managing channels/groups, and downloading media. Triggers on "telegram daemon", "monitor telegram", "telegram bot", "spawn Claude from telegram", or any Telethon-related request. IMPORTANT: Use `draft` command for "драфт/draft", use `send` for "отправь/send"; if ambiguous, ASK before sending.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/telegram-telethon" ~/.claude/skills/diegosouzapw-awesome-omni-skill-telegram-telethon && rm -rf "$T"

manifest: skills/development/telegram-telethon/SKILL.md

source content

Claude Behavior Guidelines

Draft vs Send: Follow User's Intent

User says	Claude does	Clarify?
"драфт", "draft", "сделай драфт"	`draft`	No
"отправь", "пошли", "send"	`send`	No
"напиши сообщение" (ambiguous)	Ask what user wants	Yes

Key Rules

Explicit draft → draft: "драфт", "draft" → use
```
draft
```
command immediately
Explicit send → send: "отправь", "пошли", "send" → use
```
send
```
command immediately
Ambiguous → clarify: If neither "draft" nor "send" verb present, ask: "Создать драфт или сразу отправить?"

Examples

User: "сделай драфт для lv: привет" Claude: Uses

draft --chat "lv" --text "привет"

immediately

User: "отправь сообщение Маше: встретимся в 5?" Claude: Uses

send --chat "Маша" --text "встретимся в 5?"

immediately

User: "напиши сообщение для Маши: встретимся в 5?" Claude: Asks "Создать драфт или сразу отправить?"

Telegram Telethon Skill

Full Telethon API wrapper with daemon mode and Claude Code integration. Supports interactive setup, background message monitoring, and automatic Claude session spawning per chat.

Prerequisites

Interactive Setup (Terminal)

Run setup wizard on first use:

python3 scripts/tg.py setup

This guides through:

Getting API credentials from https://my.telegram.org/auth
Phone number verification
2FA (if enabled)
Optional daemon trigger configuration

Non-Interactive Setup (Claude Code)

For use from Claude Code or scripts without TTY:

# Step 1: Provide credentials and trigger code send
python3 scripts/tg.py setup --api-id 12345678 --api-hash abc123... --phone +1234567890

# Step 2: User receives code on phone, then complete auth
python3 scripts/tg.py setup --api-id 12345678 --api-hash abc123... --phone +1234567890 --code 12345

# If 2FA enabled, add password
python3 scripts/tg.py setup --api-id 12345678 --api-hash abc123... --phone +1234567890 --code 12345 --password mypassword

The script auto-detects TTY and switches between interactive/non-interactive modes.

Quick Start

# Check connection status
python3 scripts/tg.py status

# List chats
python3 scripts/tg.py list

# Get recent messages from a chat
python3 scripts/tg.py recent "John Doe" --limit 20

# Search messages
python3 scripts/tg.py search "meeting notes"

# Configure daemon triggers interactively
python3 scripts/tg.py daemon-config

# Start daemon (foreground with logs)
python3 scripts/tgd.py start --foreground

# Start daemon (background)
python3 scripts/tgd.py start

# View daemon logs
python3 scripts/tgd.py logs

CLI Commands

Message Operations

# List all chats
python3 scripts/tg.py list [--limit 30] [--search "term"]

# Fetch recent messages
python3 scripts/tg.py recent [CHAT] [--limit 50] [--days 7] [--format markdown|json] [--output file.md]

# Search messages by content
python3 scripts/tg.py search QUERY [--chat "Chat Name"] [--limit 50] [--format markdown|json]

# Fetch unread messages
python3 scripts/tg.py unread [--chat "Chat Name"] [--format markdown|json]

# Fetch forum thread
python3 scripts/tg.py thread CHAT_ID THREAD_ID [--limit 100]

# Send message
python3 scripts/tg.py send --chat "Chat Name" --text "Message text" [--reply-to MSG_ID] [--file path] [--topic TOPIC_ID]

# Edit message
python3 scripts/tg.py edit --chat "Chat Name" --message-id MESSAGE_ID --text "New text"

# Delete messages
python3 scripts/tg.py delete --chat "Chat Name" --message-ids 123 456 789 [--no-revoke]

# Forward messages
python3 scripts/tg.py forward --from "Source" --to "Dest" --message-ids 123 456

# Mark messages as read
python3 scripts/tg.py mark-read --chat "Chat Name" [--max-id MSG_ID]

Draft Operations

# Save/update a draft message
python3 scripts/tg.py draft --chat "Chat Name" --text "Draft text" [--reply-to MSG_ID] [--no-preview]

# Clear a draft (save empty text)
python3 scripts/tg.py draft --chat "Chat Name" --text ""

# Clear all drafts
python3 scripts/tg.py draft --clear-all

# List all drafts
python3 scripts/tg.py drafts [--limit 50]

# Send a draft as a message (clears the draft)
python3 scripts/tg.py draft-send --chat "Chat Name"

Note: Use

"me"

as the chat name to target Saved Messages (your own chat). The literal name "Saved Messages" doesn't work as it's localized differently per user.

Media Operations

# Download media from chat
python3 scripts/tg.py download "Chat Name" [--limit 5] [--output-dir ~/Downloads] [--message-id ID] [--type voice|video|photo]

# Transcribe voice messages
python3 scripts/tg.py transcribe "Chat Name" MESSAGE_ID [--method telegram|groq|whisper]

# Batch transcribe voice messages
python3 scripts/tg.py transcribe "Chat Name" --batch [--limit 10]

Obsidian Integration

# Append messages to today's daily note
python3 scripts/tg.py to-daily "Chat Name" [--vault ~/Brains/brain] [--section "Telegram"]

# Append messages to a person's note
python3 scripts/tg.py to-person "Chat Name" "Person Name" [--vault ~/Brains/brain]

Voice Transcription

The skill supports three transcription methods with automatic fallback:

Telegram API (default) - Uses Telegram Premium's server-side transcription
Groq - Uses Groq's Whisper API (requires
```
GROQ_API_KEY
```
environment variable)
Whisper - Uses local OpenAI Whisper model (requires
```
pip install openai-whisper
```
)

# Use Telegram's transcription (Premium feature)
python3 scripts/tg.py transcribe "Chat" 123

# Force Groq transcription
python3 scripts/tg.py transcribe "Chat" 123 --method groq

# Force local Whisper
python3 scripts/tg.py transcribe "Chat" 123 --method whisper

Daemon Mode

The daemon monitors Telegram for messages matching configured triggers and can:

Reply with static text
Spawn Claude Code sessions to handle requests
Resume existing Claude sessions per-chat
Queue requests to prevent rate limiting

Trigger Configuration

Triggers are stored in

~/.config/telegram-telethon/daemon.yaml

triggers:
  # Respond to /claude command in DMs
  - chat: "@myusername"
    pattern: "^/claude (.+)$"
    action: claude
    reply_mode: inline

  # Respond to @Bot mentions in a group
  - chat: "AI Assistants"
    pattern: "@Bot (.+)$"
    action: claude
    reply_mode: new

  # Simple ping-pong in any chat
  - chat: "*"
    pattern: "^/ping$"
    action: reply
    reply_text: "pong"

claude:
  allowed_tools:
    - Read
    - Edit
    - Bash
    - WebFetch
  max_turns: 10
  timeout: 300

queue:
  max_concurrent: 1
  timeout: 600

Trigger Fields

Field	Description
`chat`	Chat name, `@username` , or `*` for all chats
`pattern`	Regex pattern (capture group 1 becomes Claude prompt)
`action`	`claude` , `reply` , or `ignore`
`reply_mode`	`inline` (reply to message) or `new` (separate message)
`reply_text`	Static text for `reply` action

Claude Integration

When action is

claude

Text captured by regex group 1 is sent to Claude Code via
```
claude -p "..." --output-format json
```
Claude sessions persist per-chat in
```
sessions.json
```
Subsequent messages from same chat resume session via
```
--resume <session_id>
```
Responses are sent back to Telegram as reply or new message

Session Persistence

Claude sessions are saved to

~/.config/telegram-telethon/sessions.json

Each chat_id maps to a Claude session_id
Sessions survive daemon restarts
Track message count and last used timestamp

To reset: delete chat entry from

sessions.json

or configure a

/reset

trigger.

Example Configurations

Personal AI Assistant

Respond to all DMs to yourself:

triggers:
  - chat: "@yourusername"
    pattern: "(.+)"
    action: claude
    reply_mode: inline

Group Bot with Mention Trigger

Only respond when @mentioned:

triggers:
  - chat: "Dev Team"
    pattern: "@AssistantBot (.+)"
    action: claude
    reply_mode: inline

Multi-Action Setup

triggers:
  - chat: "*"
    pattern: "^/ask (.+)"
    action: claude
    reply_mode: inline

  - chat: "*"
    pattern: "^/ping$"
    action: reply
    reply_text: "pong"

  - chat: "Noisy Group"
    pattern: ".*"
    action: ignore

File Structure

~/.config/telegram-telethon/
├── config.yaml        # API credentials (api_id, api_hash, phone)
├── daemon.yaml        # Daemon triggers and Claude config
├── session.session    # Telethon session file
├── sessions.json      # Claude session persistence
└── daemon.log         # Daemon log file

Development

# Install with dev dependencies
cd telegram-telethon
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=telegram_telethon

# Run specific test file
pytest tests/unit/test_claude_bridge.py -v

Troubleshooting

Issue	Solution
"Config not found"	Run `python3 scripts/tg.py setup`
"Session expired"	Delete `session.session` and re-run setup
"Claude timeout"	Increase `timeout` in `daemon.yaml`
"Queue full"	Reduce request rate or wait
"No trigger matched"	Check `pattern` regex and `chat` name match