telegram

📬 Telegram CLI

メッセージの閲覧、検索、送信に使える高速な Telegram CLI です。

🎯 使用する場面

以下のような場合にこのスキルを使用します。

• Telegram のメッセージや受信トレイを確認したい
• トピックやキーワードで Telegram を検索したい
• Telegram メッセージを送信したり、返信したりしたい
• Telegram のグループ、連絡先、チャットについて知りたい
• 未読メッセージを確認したい
• グループのメンバーや管理者を調べたい
• 騒がしいチャットやグループをミュート／ミュート解除したい
• グループからユーザーをキック／削除したい
• メンバーを管理者に昇格させたい
• グループ／チャンネルの所有権をほかの人に移したい
• チャット履歴をファイルにエクスポートまたは同期したい
• チャットをフォルダーに整理したい
• ログイン中のアカウントやセッションの状態を確認したい

📦 インストール

npm install -g @skillhq/telegram

🔐 認証

初回のセットアップには、https://my.telegram.org/apps で取得できる API 認証情報が必要です。

telegram auth                                # First-time login
telegram logout                              # Clear saved session
telegram check                               # Verify session is valid
telegram whoami                              # Show logged-in account
telegram whoami --json                       # Account info as JSON

📖 コマンド

メッセージを読む

telegram inbox                               # Unread messages summary
telegram chats                               # List all chats
telegram chats --type group                  # Filter: user, group, supergroup, channel
telegram chats -n 200                        # List up to 200 chats
telegram read "ChatName" -n 50               # Read last 50 messages
telegram read "ChatName" --since "1h"        # Messages from last hour
telegram read "ChatName" --until "2h"        # Messages up to 2 hours ago
telegram read @username -n 20                # Read DM with user
telegram read 123456789 -n 10               # Read by chat ID

検索

telegram search "query" --chat "ChatName"    # Search within chat
telegram search "query" --all                # Search all chats (global)
telegram search "query" -n 20               # Limit results

メッセージを送信

telegram send @username "message"            # Send DM
telegram send "GroupName" "message"          # Send to group
telegram reply "ChatName" 12345 "response"   # Reply to message ID

連絡先とグループ

telegram contact @username                   # Get contact info
telegram members "GroupName"                 # List group members
telegram members "GroupName" -n 500          # Fetch up to 500 members
telegram admins "GroupName"                  # List admins only
telegram groups                              # List all groups
telegram groups --admin                      # Groups where you're admin
telegram kick "GroupName" @username           # Remove user from group
telegram promote "GroupName" @username        # Promote a member to admin
telegram promote "GroupName" @username --rank "Mod"  # Promote with a custom admin title
telegram promote "GroupName" @username --add-admins  # Allow them to add admins too
telegram transfer-owner "GroupName" @username # Hand over ownership (prompts for 2FA password)

transfer-owner に関する注意事項：

• 元に戻せません。通常の管理者／メンバーになり、所有権を再度移せるのは新しい所有者だけです。
• アカウントで2段階認証（クラウドパスワード）が必要です。実行時に安全な方法で入力を求められます。
• スーパーグループとチャンネルのみが対象です。通常のグループは、先にスーパーグループに変換してください。
• 対象者はすでにメンバーである必要があります。また、Telegram は新しいログインから約24時間、2FA パスワードの設定／変更から約7日間、所有権の移転を制限します。
• 確認のためにグループ名を再入力するよう求められます。この確認をスキップするには -y を渡してください。

ミュート

telegram mute "ChatName"                     # Mute forever
telegram mute "ChatName" -d 1h               # Mute for 1 hour
telegram mute @username -d 8h                # Mute DM for 8 hours
telegram mute "GroupName" -d 1d              # Mute for 1 day
telegram unmute "ChatName"                   # Unmute

フォルダー

telegram folders                             # List all folders
telegram folder "Work"                       # Show chats in folder
telegram folder-add "Work" "ProjectChat"     # Add chat to folder
telegram folder-remove "Work" "ProjectChat"  # Remove chat from folder

同期／エクスポート

telegram sync                                # Sync last 7 days to ./telegram-sync
telegram sync --days 30                      # Sync last 30 days
telegram sync --since "12h"                  # Sync messages from last 12 hours
telegram sync --until "2d"                   # Sync messages up to 2 days ago
telegram sync --all                          # Sync entire chat history (no time limit)
telegram sync --chat "ChatName"              # Sync specific chat only
telegram sync --output ~/exports             # Custom output directory
telegram sync --resume                       # Incremental: only fetch new messages
telegram sync --resume --all                 # Keep a complete archive up to date

差分同期（--resume）：

• チャットごとに最後に同期したメッセージ ID を .sync-meta.json に記録します
• 2回目以降の実行では、最後に同期したメッセージより新しいメッセージのみを取得します
• 既存の Markdown ファイルに新しいメッセージを追記します
• 完全で最新のアーカイブを維持するには、--all と組み合わせてください

📤 出力形式

ほとんどのコマンドは複数の出力形式に対応しています。

フラグ	用途
(default)	人が読みやすいターミナル出力
--json	プログラム処理用の構造化 JSON
--markdown	表示またはエクスポート用の Markdown 形式

telegram inbox --json                        # JSON format
telegram inbox --markdown                    # Markdown format
telegram read "Chat" --json                  # JSON with messages array
telegram read "Chat" --markdown              # Markdown with messages
telegram chats --json                        # JSON with chat list
telegram members "Group" --markdown          # Markdown member list

対応コマンド： inbox、read、search、chats、members、groups、contact、whoami

📎 メディアのメタデータ

メディア（写真、動画、ドキュメント、音声メッセージ、ステッカーなど）を含むメッセージには、「(no text)」の代わりにメタデータが表示されるようになりました。

メディアの種類	表示
写真	[📷 Photo]
動画	[🎥 Video (2.1 MB)]
ドキュメント	[📎 report.pdf (540.0 KB)]
音声	[🎤 Voice message]
オーディオ	[🎵 song.mp3 (3.2 MB)]
ステッカー	[😀 Sticker]
GIF	[🎬 GIF]
位置情報	[📍 Location]
連絡先	[👤 Contact]
投票	[📊 Poll]

JSON 出力では、メディアが含まれるメッセージに mediaType、fileName、fileSize フィールドが含まれます。

🤖 AI エージェント向けガイダンス

この CLI を AI エージェントとして使用する場合：

• データ処理（カウント、フィルタリング、抽出）には、--json を使用してください
• ユーザーへの表示には、デフォルトまたは --markdown を使用してください
• チャットの識別：名前は部分一致します（例：「MetaDAO」は「MetaDAO Community」に一致します）。ユーザー名は @ で始まる必要があります。数値 ID も使用できます
• 読み取り操作は安全なので、確認なしで実行できます
• 書き込み操作（send、reply、kick、promote、transfer-owner）は、実行前にユーザーに確認してください
• transfer-owner は取り消しできず、対話形式で実行されます（2FA パスワードの入力と、確認文字列の入力を求められます）。そのため無人では実行できません。明示的な指示なしに、ユーザーに代わってスクリプトで実行しないでください
• レート制限：短時間に連続して呼び出さないでください。Telegram API にはレート制限があります
• 大規模なグループ：非常に大規模なグループで members の出力を制限するには、-n を使用してください
• 完全なアーカイブ：telegram sync --all --chat "Name" を使用して、チャット履歴全体をエクスポートしてください
• アーカイブを最新の状態に保つ：telegram sync --resume を使用すると、以前のエクスポートを増分更新できます
• メディアが多いチャット：写真、動画、ファイルを含むメッセージには、「（テキストなし）」だけでなく、メタデータも表示されるようになりました

💡 例

未読メッセージを確認します：

telegram inbox

グループの最近のメッセージを読み取ります：

telegram read "MetaDAO Community" -n 20

直近 2 時間のメッセージを取得します：

telegram read "Project Chat" --since "2h"

すべてのチャットからトピックを検索します：

telegram search "futarchy" --all

特定のチャット内を検索します：

telegram search "deadline" --chat "Work Team"

メッセージを送信します：

telegram send @username "Hello, checking in!"

チャットの履歴全体をエクスポートします：

telegram sync --all --chat "Project Chat" --output ~/exports

既存のエクスポートを増分更新します：

telegram sync --resume --output ~/exports

種類でチャットを絞り込みます：

telegram chats --type channel --json

グループからユーザーを退出させます：

telegram kick "My Group" @spammer

メンバーを管理者に昇格させます：

telegram promote "My Group" @trustedmember

グループの所有権を別のユーザーに移します：

telegram transfer-owner "My Group" @newowner

📝 注意事項

• チャット名は部分一致します（例：「MetaDAO」は「MetaDAO Community」に一致します）
• ユーザー名は @ で始まる必要があります（例：@username）
• チャット ID（数値）は、チャット名を指定できる場所であればどこでも使用できます
• メッセージは新しいものから古いものの順に返されます
• 時間指定フラグ（--since、--until）では、"1h"、"30m"、"7d" などの形式を使用できます
• sync コマンドは、出力ディレクトリにチャットごとに 1 つの Markdown ファイルを作成します
• 同期メタデータ（.sync-meta.json）を使うと、--resume による増分同期が可能になります
• 同期を高速化するため、送信者名はリクエストごとにキャッシュされます（重複した API 呼び出しを回避します）
• メッセージは自動的にページ分割されます。大量のチャットでも、通知なしに一部が切り捨てられることはありません