telegram

Telegram Message Skill

柔軟なフィルタリングと出力オプションを使って、Telegram メッセージを取得、検索、ダウンロード、送信、公開します。

前提条件

認証は ~/.telegram_dl/ に設定する必要があります。setup コマンドを実行して、ステータスを確認するか手順を取得してください。

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 で確認します

クイックスタート

適切なコマンドを指定して、scripts/telegram_fetch.py のスクリプトを実行します。

# List available chats
python3 scripts/telegram_fetch.py list

# Get recent messages
python3 scripts/telegram_fetch.py recent --limit 20

# Search messages
python3 scripts/telegram_fetch.py search "meeting"

# Get unread messages
python3 scripts/telegram_fetch.py unread

コマンド

チャットの一覧表示

利用可能な Telegram チャットを確認するには、次を実行します。

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。チャットが見つからない場合は増やしてください）

重要： 特定のチャットを正確な名前で検索して見つからない場合は、チャットが直近の30件に含まれていない可能性があるため、--limit を100または200に増やしてください。

チャット ID、名前、種類、未読数を含む JSON を返します。

最近のメッセージを取得

最近のメッセージを取得するには、次を実行します。

# From all chats (last 50 messages across top 10 chats)
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

# With limits
python3 scripts/telegram_fetch.py recent --limit 100
python3 scripts/telegram_fetch.py recent --days 7

メッセージを検索

メッセージの内容を検索するには、次を実行します。

# Global search across all chats
python3 scripts/telegram_fetch.py search "project deadline"

# Search in specific chat
python3 scripts/telegram_fetch.py search "meeting" --chat-id 123456789

# Limit results
python3 scripts/telegram_fetch.py search "important" --limit 20

未読メッセージを取得

未読メッセージのみを取得するには、次を実行します。

python3 scripts/telegram_fetch.py unread
python3 scripts/telegram_fetch.py unread --chat-id 123456789

メッセージを送信

チャットにメッセージを送信するには、次を実行します。

# Send to existing chat by name
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!"

# Reply to a specific message (use message ID from recent/search output)
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

# Send with markdown formatting (converts **bold**, _italic_, [links](url) to Telegram HTML)
python3 scripts/telegram_fetch.py send --chat "@username" --text "**Bold** and _italic_ text" --markdown

書式設定（--markdown フラグ）：

• --markdown なし：テキストはそのまま送信されます（プレーンテキスト、書式設定なし）
• --markdown あり：Markdown を Telegram HTML に変換します（**bold** → 太字、_italic_ → 斜体、[text](url) → リンク、## Header → 太字、* item → 矢印付きリスト）
• 重要： Markdown の書式設定を含む下書きの内容を送信するときは、必ず --markdown を使用してください
• publish コマンドは Markdown を自動的に変換しますが、send コマンドは --markdown を指定しない限り変換しません

ファイルを送信

画像、ドキュメント、動画を送信するには、次を実行します。

# Send an image
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"

# Reply with 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 a message by ID
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"

注： 編集できるのは自分のメッセージのみです。Telegram の書式設定（太字 など）は保持されます。

編集ステータスとメッセージ ID を含む JSON を返します。

添付ファイルをダウンロード

チャットからメディアファイルをダウンロードするには、次を実行します。

# Download last 5 attachments from a chat (default)
python3 scripts/telegram_fetch.py download --chat "Tool Building Ape"

# Download last 10 attachments
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"

# Download from specific message
python3 scripts/telegram_fetch.py download --chat "John Doe" --message-id 12345

デフォルトの出力先： ~/Downloads/telegram_attachments/

ダウンロード結果（ファイル名、パス、サイズ）を含む JSON を返します。

フォーラムのスレッドメッセージを取得

特定のフォーラムスレッド（グループ内のトピック）からメッセージを取得するには、次を実行します。

# Fetch from thread 174 in Claude Code Lab
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

# Save to file
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

# JSON output
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 で返します。

チャンネルに下書きを公開する

klodkot チャンネルの下書きを Telegram に公開するには：

# Dry run (preview without sending)
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"

ワークフロー：

1. 下書きのフロントマターと本文を解析します
2. チャンネルフィールドを検証します（「klodkot」である必要があります）
3. フロントマターの video: フィールドとウィキリンクからメディアへの参照を抽出します
4. Channels/klodkot/attachments/ または Sources/ 内のメディアパスを解決します
5. 下書きのヘッダー（例：「# Title - Telegram Draft」）を削除します
6. フッターがない場合は追加します：「КЛОДКОТ — 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

出力オプション

デフォルト（標準出力への Markdown）

デフォルトでは、Claude が読み取って要約しやすい形式の Markdown を出力します。

JSON 形式

構造化データを出力するには --json フラグを追加します。

python3 scripts/telegram_fetch.py recent --json

Obsidian のデイリーノートに追加

今日のデイリーノートにメッセージを追加します。

python3 scripts/telegram_fetch.py recent --to-daily
python3 scripts/telegram_fetch.py search "project" --to-daily

~/Brains/brain/Daily/YYYYMMDD.md に追記します

人物のノートに追加

特定の人物のノートにメッセージを追加します。

python3 scripts/telegram_fetch.py recent --chat "John Doe" --to-person "John Doe"

~/Brains/brain/{PersonName}.md を作成するか、既存のファイルに追記します

ファイルに保存（トークン効率の向上）

コンテキストトークンを消費せずに、メッセージを直接ファイルに保存します。

# Save 100 messages to markdown file
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

# Save search results to file
python3 scripts/telegram_fetch.py search "meeting" -o ~/meetings.md

保存ステータス（ファイルパス、メッセージ数、メディアのダウンロード結果）を含む JSON を返します。トークンの使用量は最小限です。

ユーザーリクエストの例

ユーザーが次のように尋ねた場合：

• 「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
• 「Telegram で John に hello を送って」 -> send --chat "John" --text "Hello!"
• 「Telegram で @username にメッセージを送って」 -> 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"
• 「Group のトピック 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

レート制限

このスクリプトにはレート制限（メッセージ間隔 0.1 秒）が組み込まれており、Telegram の FloodWaitError に自動的にバックオフして対処します。

依存関係

以下の Python パッケージが必要です。

• telethon - Telegram API クライアント
• pyyaml - 下書きのフロントマターの YAML 解析

次のコマンドでインストールします：pip install telethon pyyaml