telegram

Telegram Message Skill

Fetch, search, download, send, and publish Telegram messages with flexible filtering and output options.

Prerequisites

Authentication must be configured in ~/.telegram_dl/. Run setup command to check status or get instructions:

python3 scripts/telegram_fetch.py setup

If not configured, follow these steps:

1. Get API credentials from https://my.telegram.org/auth
2. Clone telegram_dl: https://github.com/glebis/telegram_dl
3. Run python telegram_dl.py and follow interactive prompts
4. Verify with python3 scripts/telegram_fetch.py setup

Quick Start

Run the script at scripts/telegram_fetch.py with appropriate commands:

# List available chats
python3 scripts/telegram_fetch.py list
 
# Get recent messages
python3 scripts/telegram_fetch.py recent

Commands

List Chats

To see available Telegram chats:

Options:

• --search "text": Filter by substring match (case-insensitive)
• --exact: Require exact name match instead of substring (use with --search)
• --limit N: Max chats to retrieve (default: 30, increase if chat not found)

Important: If you're looking for a specific chat by exact name and it's not found, increase --limit to 100 or 200, as the chat may not be in the most recent 30.

Returns JSON with chat IDs, names, types, and unread counts.

Fetch Recent Messages

To get recent messages:

Search Messages

To search message content:

Fetch Unread Messages

To get only unread messages:

Send Messages

To send a message to a chat:

Formatting (--markdown flag):

• Without --markdown: text is sent as-is (plain text, no formatting)
• With --markdown: converts markdown to Telegram HTML (**bold** -> bold, _italic_ -> italic, [text](url) -> link, ## Header -> bold, * item -> arrow list)
• IMPORTANT: Always use --markdown when sending draft content that contains markdown formatting
• The publish command handles markdown conversion automatically; the send command does NOT unless --markdown is specified

Send Files

To send images, documents, or videos:

Chat resolution order:

1. @username - Resolves Telegram username directly
2. Numeric ID - Resolves chat by Telegram ID
3. Name match - Fuzzy search in existing dialogs

Returns JSON with send status, resolved chat name, message ID, and file info (for media).

Edit Messages

To edit an existing message:

Note: You can only edit your own messages. Telegram formatting (bold, etc.) is preserved.

Returns JSON with edit status and message ID.

Download Attachments

To download media files from a chat:

Default output: ~/Downloads/telegram_attachments/

Returns JSON with download results (file names, paths, sizes).

Fetch Forum Thread Messages

To get messages from a specific forum thread (topics in groups):

Messages are sorted newest first (reverse chronological order).

How to find thread ID:

• Forum topic IDs appear in the thread URL: https://t.me/c/CHAT_ID/THREAD_ID
• Use recent command on the chat to see message IDs in threads

Returns markdown or JSON with all messages from the specified thread.

Publish Draft to Channel

To publish a draft from the klodkot channel to Telegram:

Workflow:

1. Parses draft frontmatter and body
2. Validates channel field (must be "klodkot")
3. Extracts media references from frontmatter video: field and wikilinks
4. Resolves media paths in Channels/klodkot/attachments/ or Sources/
5. Strips draft headers (e.g., "# Title - Telegram Draft")
6. Appends footer if not present: "КЛОДКОТ — Claude Code и другие агенты: инструменты, кейсы, вдохновение"
7. Sends to @klodkot channel (multiple media as album)
8. Updates frontmatter with published_date, telegram_message_id
9. Moves file from drafts/ to published/
10. Updates channel index with new entry at top

Media handling:

• Frontmatter: video: filename.mp4
• Wikilinks: [[filename.mp4]], [[image.png|alt text]]
• Multiple media sent as Telegram album

Safety:

• --dry-run shows preview without sending
• Validates before sending
• Rollback on send failure (file not moved)
• Warnings on post-publish errors (file sent but move/index update failed)

Returns: JSON with publish status, message ID, warnings (if any)

Output Options

Default (Markdown to stdout)

By default, outputs formatted markdown suitable for Claude to read and summarize.

JSON Format

Add --json flag for structured data:

Append to Obsidian Daily Note

Add messages to today's daily note in the vault:

Appends to ~/Brains/brain/Daily/YYYYMMDD.md

Append to Person's Note

Add messages to a specific person's note:

Creates or appends to ~/Brains/brain/{PersonName}.md

Save to File (Token-Efficient)

Save messages directly to file without consuming context tokens:

Returns JSON with save status (file path, message count, media download results) - minimal token usage.

Example User Requests

When user asks:

• "Show my recent Telegram messages" -> recent --limit 20
• "What Telegram messages did I get today?" -> recent --days 1
• "Search Telegram for messages about the project" -> search "project"
• "Get unread messages from Tool Building Ape" -> unread + filter output
• "Add my Telegram messages to daily note" -> recent --to-daily
• "What chats do I have on Telegram?" -> list
• "Find the exact chat named X" -> list --search "X" --exact --limit 200
• "Send hello to John on Telegram" -> send --chat "John" --text "Hello!"
• "Message @username on Telegram" -> send --chat "@username" --text "..."
• "Reply to that message with thanks" -> send --chat "..." --text "Thanks!" --reply-to <id>
• "Send this image to John" -> send --chat "John" --file "/path/to/image.jpg"
• "Send report.pdf with caption" -> send --chat "..." --file "report.pdf" --text "Here's the report"
• "Send to topic 12 in Group" -> send --chat "Group" --text "..." --topic 12
• "Download attachments from Tool Building Ape" -> download --chat "Tool Building Ape"
• "Download last 10 files from Project Group" -> download --chat "Project Group" --limit 10
• "Save last 100 messages from AGENCY to file" -> recent --chat "AGENCY: Community" --limit 100 -o ~/agency.md
• "Archive chat with media" -> recent --chat "Group" -o ~/archive.md --with-media
• "Edit that message" -> edit --chat "..." --message-id <id> --text "new text"
• "Fix the typo in message 123" -> edit --chat "..." --message-id 123 --text "corrected text"
• "Is Telegram configured?" -> setup
• "How do I set up Telegram?" -> setup (returns instructions if not configured)
• "Publish this draft to klodkot" -> publish --draft "Channels/klodkot/drafts/...md"
• "Preview this draft before publishing" -> publish --draft "..." --dry-run

Rate Limiting

The script includes built-in rate limiting (0.1s between messages) and handles Telegram's FloodWaitError automatically with backoff.

Dependencies

Requires Python packages:

• telethon - Telegram API client
• pyyaml - YAML parsing for draft frontmatter

Install with: pip install telethon pyyaml