Back to Details

telegram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Telegram Message Skill

Telegram 消息处理Skill

Fetch, search, download, send, and publish Telegram messages with flexible filtering and output options.
通过灵活的筛选和输出选项，在Telegram上获取、搜索、下载、发送和发布消息。

Prerequisites

前置条件

Authentication must be configured in 
~/.telegram_dl/
. Run 
setup
command to check status or get instructions:
bash
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
需在
~/.telegram_dl/
中配置身份验证。运行
setup
命令检查状态或获取配置说明：
bash
python3 scripts/telegram_fetch.py setup
若未配置，请按照以下步骤操作：
  1. 从 https://my.telegram.org/auth 获取API凭证
  2. 克隆telegram_dl仓库：https://github.com/glebis/telegram_dl
  3. 运行
    python telegram_dl.py
    并按照交互式提示完成配置
  4. 运行
    python3 scripts/telegram_fetch.py setup
    验证配置是否成功

Quick Start

快速开始

Run the script at 
scripts/telegram_fetch.py
with appropriate commands:
bash
undefined
运行
scripts/telegram_fetch.py
脚本并使用相应命令：
bash
undefined

List available chats

列出可用聊天

python3 scripts/telegram_fetch.py list
python3 scripts/telegram_fetch.py list

Get recent messages

获取最近消息

python3 scripts/telegram_fetch.py recent --limit 20
python3 scripts/telegram_fetch.py recent --limit 20

Search messages

搜索消息

python3 scripts/telegram_fetch.py search "meeting"
python3 scripts/telegram_fetch.py search "meeting"

Get unread messages

获取未读消息

python3 scripts/telegram_fetch.py unread
undefined
python3 scripts/telegram_fetch.py unread
undefined

Commands

命令说明

List Chats

列出聊天列表

To see available Telegram chats:
bash
python3 scripts/telegram_fetch.py list
python3 scripts/telegram_fetch.py list --limit 50
python3 scripts/telegram_fetch.py list --search "AI"
python3 scripts/telegram_fetch.py list --search "claude code глеб + саши" --exact
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.
查看可用的Telegram聊天：
bash
python3 scripts/telegram_fetch.py list
python3 scripts/telegram_fetch.py list --limit 50
python3 scripts/telegram_fetch.py list --search "AI"
python3 scripts/telegram_fetch.py list --search "claude code глеб + саши" --exact
可选参数：
  • --search "text"
    : 根据子字符串筛选（不区分大小写）
  • --exact
    : 要求完全匹配名称（需与--search配合使用）
  • --limit N
    : 最多获取的聊天数量（默认：30，若未找到目标聊天可增大该值）
重要提示： 如果你按精确名称查找特定聊天但未找到，请将
--limit
增大到100或200，因为该聊天可能不在最近的30个聊天中。
返回包含聊天ID、名称、类型和未读消息数的JSON数据。

Fetch Recent Messages

获取最近消息

To get recent messages:
bash
undefined
获取最近的消息：
bash
undefined

From all chats (last 50 messages across top 10 chats)

获取所有聊天的最近消息（前10个聊天中的最后50条消息）

python3 scripts/telegram_fetch.py recent
python3 scripts/telegram_fetch.py recent

From specific chat

获取指定聊天的最近消息

python3 scripts/telegram_fetch.py recent --chat "Tool Building Ape" python3 scripts/telegram_fetch.py recent --chat-id 123456789
python3 scripts/telegram_fetch.py recent --chat "Tool Building Ape" python3 scripts/telegram_fetch.py recent --chat-id 123456789

With limits

限制消息数量

python3 scripts/telegram_fetch.py recent --limit 100 python3 scripts/telegram_fetch.py recent --days 7
undefined
python3 scripts/telegram_fetch.py recent --limit 100 python3 scripts/telegram_fetch.py recent --days 7
undefined

Search Messages

搜索消息

To search message content:
bash
undefined
搜索消息内容：
bash
undefined

Global search across all chats

在所有聊天中全局搜索

python3 scripts/telegram_fetch.py search "project deadline"
python3 scripts/telegram_fetch.py search "project deadline"

Search in specific chat

在指定聊天中搜索

python3 scripts/telegram_fetch.py search "meeting" --chat-id 123456789
python3 scripts/telegram_fetch.py search "meeting" --chat-id 123456789

Limit results

限制搜索结果数量

python3 scripts/telegram_fetch.py search "important" --limit 20
undefined
python3 scripts/telegram_fetch.py search "important" --limit 20
undefined

Fetch Unread Messages

获取未读消息

To get only unread messages:
bash
python3 scripts/telegram_fetch.py unread
python3 scripts/telegram_fetch.py unread --chat-id 123456789
仅获取未读消息：
bash
python3 scripts/telegram_fetch.py unread
python3 scripts/telegram_fetch.py unread --chat-id 123456789

Send Messages

发送消息

To send a message to a chat:
bash
undefined
给指定聊天发送消息：
bash
undefined

Send to existing chat by name

按名称发送给已存在的聊天

python3 scripts/telegram_fetch.py send --chat "John Doe" --text "Hello!"
python3 scripts/telegram_fetch.py send --chat "John Doe" --text "Hello!"

Send to username (works even without prior conversation)

发送给用户名（即使没有过对话也可使用）

python3 scripts/telegram_fetch.py send --chat "@username" --text "Hello!"
python3 scripts/telegram_fetch.py send --chat "@username" --text "Hello!"

Reply to a specific message (use message ID from recent/search output)

回复特定消息（使用recent/search输出中的消息ID）

python3 scripts/telegram_fetch.py send --chat "Tool Building Ape" --text "Thanks!" --reply-to 12345
python3 scripts/telegram_fetch.py send --chat "Tool Building Ape" --text "Thanks!" --reply-to 12345

Send to a forum topic (for groups with topics enabled)

发送到论坛话题（适用于开启话题功能的群组）

python3 scripts/telegram_fetch.py send --chat "Group Name" --text "Hello topic!" --topic 12
python3 scripts/telegram_fetch.py send --chat "Group Name" --text "Hello topic!" --topic 12

Send with markdown formatting (converts bold, italic, links to Telegram HTML)

发送带markdown格式的消息（将粗体、斜体、链接转换为Telegram HTML格式）

python3 scripts/telegram_fetch.py send --chat "@username" --text "Bold and italic text" --markdown

**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
python3 scripts/telegram_fetch.py send --chat "@username" --text "Bold and italic text" --markdown

**格式说明（`--markdown`参数）：**
- 不使用`--markdown`：文本将按原样发送（纯文本，无格式）
- 使用`--markdown`：将markdown转换为Telegram HTML格式（`**bold**` -> 粗体，`_italic_` -> 斜体，`[text](url)` -> 链接，`## 标题` -> 粗体，`* 项目` -> 箭头列表）
- **重要提示**：当发送包含markdown格式的草稿内容时，请务必使用`--markdown`参数
- `publish`命令会自动处理markdown转换；而`send`命令只有在指定`--markdown`参数时才会进行转换

Send Files

发送文件

To send images, documents, or videos:
bash
undefined
发送图片、文档或视频：
bash
undefined

Send an image

发送图片

python3 scripts/telegram_fetch.py send --chat "John Doe" --file "/path/to/image.jpg"
python3 scripts/telegram_fetch.py send --chat "John Doe" --file "/path/to/image.jpg"

Send document with caption

发送带说明的文档

python3 scripts/telegram_fetch.py send --chat "@username" --file "report.pdf" --text "Here's the report"
python3 scripts/telegram_fetch.py send --chat "@username" --file "report.pdf" --text "Here's the report"

Reply with media

回复消息时附带媒体文件

python3 scripts/telegram_fetch.py send --chat "Group" --file "screenshot.png" --reply-to 12345

**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).
python3 scripts/telegram_fetch.py send --chat "Group" --file "screenshot.png" --reply-to 12345

**聊天匹配优先级：**
1. `@username` - 直接匹配Telegram用户名
2. 数字ID - 通过Telegram ID匹配聊天
3. 名称匹配 - 在现有对话中模糊搜索

返回包含发送状态、匹配到的聊天名称、消息ID和媒体文件信息（若发送媒体）的JSON数据。

Edit Messages

编辑消息

To edit an existing message:
bash
undefined
编辑已发送的消息：
bash
undefined

Edit a message by ID

通过消息ID编辑消息

python3 scripts/telegram_fetch.py edit --chat "@mentalhealthtech" --message-id 76 --text "Updated text"
python3 scripts/telegram_fetch.py edit --chat "@mentalhealthtech" --message-id 76 --text "Updated text"

Edit in a group/channel

在群组/频道中编辑消息

python3 scripts/telegram_fetch.py edit --chat "Mental health tech" --message-id 123 --text "Corrected content"

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

Returns JSON with edit status and message ID.
python3 scripts/telegram_fetch.py edit --chat "Mental health tech" --message-id 123 --text "Corrected content"

**注意：** 你只能编辑自己发送的消息。Telegram格式（如**粗体**等）会被保留。

返回包含编辑状态和消息ID的JSON数据。

Download Attachments

下载附件

To download media files from a chat:
bash
undefined
从聊天中下载媒体文件：
bash
undefined

Download last 5 attachments from a chat (default)

下载指定聊天的最后5个附件（默认设置）

python3 scripts/telegram_fetch.py download --chat "Tool Building Ape"
python3 scripts/telegram_fetch.py download --chat "Tool Building Ape"

Download last 10 attachments

下载指定聊天的最后10个附件

python3 scripts/telegram_fetch.py download --chat "Project Group" --limit 10
python3 scripts/telegram_fetch.py download --chat "Project Group" --limit 10

Download to custom directory

下载到自定义目录

python3 scripts/telegram_fetch.py download --chat "@username" --output "/path/to/folder"
python3 scripts/telegram_fetch.py download --chat "@username" --output "/path/to/folder"

Download from specific message

下载特定消息中的附件

python3 scripts/telegram_fetch.py download --chat "John Doe" --message-id 12345

**Default output:** `~/Downloads/telegram_attachments/`

Returns JSON with download results (file names, paths, sizes).
python3 scripts/telegram_fetch.py download --chat "John Doe" --message-id 12345

**默认输出目录：** `~/Downloads/telegram_attachments/`

返回包含下载结果（文件名、路径、大小）的JSON数据。

Fetch Forum Thread Messages

获取论坛话题消息

To get messages from a specific forum thread (topics in groups):
bash
undefined
获取指定论坛话题（群组中的话题）的消息：
bash
undefined

Fetch from thread 174 in Claude Code Lab

获取Claude Code Lab中话题ID为174的消息

python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174

Fetch with custom limit

自定义获取消息数量

python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --limit 50
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --limit 50

Save to file

保存到文件

python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 -o ~/thread.md
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 -o ~/thread.md

Append to daily note

追加到每日笔记

python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --to-daily
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --to-daily

JSON output

输出JSON格式

python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --json

**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.
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --json

**消息按时间倒序排列**（最新的消息在前）。

**如何查找话题ID：**
- 论坛话题ID会显示在话题URL中：`https://t.me/c/CHAT_ID/THREAD_ID`
- 使用指定聊天的`recent`命令查看话题中的消息ID

返回包含指定话题所有消息的markdown或JSON数据。

Publish Draft to Channel

将草稿发布到频道

To publish a draft from the klodkot channel to Telegram:
bash
undefined
将klodkot频道的草稿发布到Telegram：
bash
undefined

Dry run (preview without sending)

试运行（预览内容但不发送）

python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md" --dry-run
python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md" --dry-run

Publish to channel

发布到频道

python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md"

**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: "**[КЛОДКОТ](https://t.me/klodkot)** — 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)
python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md"

**工作流程：**
1. 解析草稿的前置元数据和正文
2. 验证频道字段（必须为"klodkot"）
3. 从前置元数据的`video:`字段和维基链接中提取媒体引用
4. 解析`Channels/klodkot/attachments/`或`Sources/`目录中的媒体路径
5. 移除草稿头部（如"# Title - Telegram Draft"）
6. 若未包含页脚则自动追加："**[КЛОДКОТ](https://t.me/klodkot)** — Claude Code и другие агенты: инструменты, кейсы, вдохновение"
7. 发送到@klodkot频道（多个媒体将作为相册发送）
8. 更新前置元数据，添加`published_date`和`telegram_message_id`字段
9. 将文件从`drafts/`目录移动到`published/`目录
10. 在频道索引顶部添加新条目

**媒体处理：**
- 前置元数据：`video: filename.mp4`
- 维基链接：`[[filename.mp4]]`、`[[image.png|alt text]]`
- 多个媒体将作为Telegram相册发送

**安全机制：**
- `--dry-run`参数可预览内容但不实际发送
- 发送前会进行验证
- 发送失败时会回滚（文件不会被移动）
- 发布后若出现错误（如文件已发送但移动/索引更新失败）会发出警告

**返回结果：** 包含发布状态、消息ID和警告信息（若有）的JSON数据。

Output Options

输出选项

Default (Markdown to stdout)

默认输出（Markdown格式输出到标准输出）

By default, outputs formatted markdown suitable for Claude to read and summarize.
默认输出适合Claude读取和总结的格式化markdown内容。

JSON Format

JSON格式

Add 
--json
flag for structured data:
bash
python3 scripts/telegram_fetch.py recent --json
添加
--json
参数获取结构化数据：
bash
python3 scripts/telegram_fetch.py recent --json

Append to Obsidian Daily Note

追加到Obsidian每日笔记

Add messages to today's daily note in the vault:
bash
python3 scripts/telegram_fetch.py recent --to-daily
python3 scripts/telegram_fetch.py search "project" --to-daily
Appends to 
~/Brains/brain/Daily/YYYYMMDD.md
将消息添加到Obsidian vault中的今日每日笔记：
bash
python3 scripts/telegram_fetch.py recent --to-daily
python3 scripts/telegram_fetch.py search "project" --to-daily
追加到
~/Brains/brain/Daily/YYYYMMDD.md
文件。

Append to Person's Note

追加到联系人笔记

Add messages to a specific person's note:
bash
python3 scripts/telegram_fetch.py recent --chat "John Doe" --to-person "John Doe"
Creates or appends to 
~/Brains/brain/{PersonName}.md
将消息添加到指定联系人的笔记中：
bash
python3 scripts/telegram_fetch.py recent --chat "John Doe" --to-person "John Doe"
创建或追加到
~/Brains/brain/{PersonName}.md
文件。

Save to File (Token-Efficient)

保存到文件（节省Token）

Save messages directly to file without consuming context tokens:
bash
undefined
直接将消息保存到文件，无需消耗上下文Token：
bash
undefined

Save 100 messages to markdown file

将100条消息保存到markdown文件

python3 scripts/telegram_fetch.py recent --chat "AGENCY: Community" --limit 100 -o ~/chat_archive.md
python3 scripts/telegram_fetch.py recent --chat "AGENCY: Community" --limit 100 -o ~/chat_archive.md

Save with media files downloaded to same folder

保存消息并将媒体文件下载到同一目录

python3 scripts/telegram_fetch.py recent --chat "Project Group" --limit 50 -o ~/project/archive.md --with-media
python3 scripts/telegram_fetch.py recent --chat "Project Group" --limit 50 -o ~/project/archive.md --with-media

Save search results to file

将搜索结果保存到文件

python3 scripts/telegram_fetch.py search "meeting" -o ~/meetings.md

Returns JSON with save status (file path, message count, media download results) - minimal token usage.
python3 scripts/telegram_fetch.py search "meeting" -o ~/meetings.md

返回包含保存状态（文件路径、消息数量、媒体下载结果）的JSON数据，消耗的Token极少。

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
当用户提出以下请求时：
  • "查看我的Telegram最近消息" -> 执行
    recent --limit 20
  • "我今天收到了哪些Telegram消息？" -> 执行
    recent --days 1
  • "在Telegram中搜索关于项目的消息" -> 执行
    search "project"
  • "获取Tool Building Ape的未读消息" -> 执行
    unread
    并过滤输出
  • "将我的Telegram消息添加到每日笔记" -> 执行
    recent --to-daily
  • "我在Telegram上有哪些聊天？" -> 执行
    list
  • "查找名为X的精确聊天" -> 执行
    list --search "X" --exact --limit 200
  • "给John发送Telegram消息说你好" -> 执行
    send --chat "John" --text "Hello!"
  • "给@username发送Telegram消息" -> 执行
    send --chat "@username" --text "..."
  • "回复那条消息说谢谢" -> 执行
    send --chat "..." --text "Thanks!" --reply-to <id>
  • "给John发送这张图片" -> 执行
    send --chat "John" --file "/path/to/image.jpg"
  • "发送report.pdf并附上说明" -> 执行
    send --chat "..." --file "report.pdf" --text "Here's the report"
  • "发送到群组的话题12" -> 执行
    send --chat "Group" --text "..." --topic 12
  • "下载Tool Building Ape的附件" -> 执行
    download --chat "Tool Building Ape"
  • "下载Project Group的最后10个文件" -> 执行
    download --chat "Project Group" --limit 10
  • "将AGENCY的最后100条消息保存到文件" -> 执行
    recent --chat "AGENCY: Community" --limit 100 -o ~/agency.md
  • "归档聊天并包含媒体文件" -> 执行
    recent --chat "Group" -o ~/archive.md --with-media
  • "编辑那条消息" -> 执行
    edit --chat "..." --message-id <id> --text "new text"
  • "修正消息123中的拼写错误" -> 执行
    edit --chat "..." --message-id 123 --text "corrected text"
  • "Telegram配置好了吗？" -> 执行
    setup
  • "如何设置Telegram？" -> 执行
    setup
    （若未配置则返回说明）
  • "将这篇草稿发布到klodkot" -> 执行
    publish --draft "Channels/klodkot/drafts/...md"
  • "发布前预览这篇草稿" -> 执行
    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.
该脚本内置速率限制（消息间隔0.1秒），并会自动处理Telegram的FloodWaitError错误，采用退避策略重试。

Dependencies

依赖项

Requires Python packages:
  • telethon
    - Telegram API client
  • pyyaml
    - YAML parsing for draft frontmatter
Install with: 
pip install telethon pyyaml
需要以下Python包：
  • telethon
    - Telegram API客户端
  • pyyaml
    - 用于解析草稿前置元数据的YAML解析库
安装命令：
pip install telethon pyyaml