telegram

Telethon を使って、MTProto 経由で個人用の Telegram を操作します。 これはユーザー自身のアカウント（「ユーザーボット」）として動作するため、Bot API とは異なり、完全な履歴を読み取り、すべての会話を一覧表示し、ユーザーがアクセスできる相手に対して操作できます。

認証情報はコネクターによって環境変数として注入されます。

• TELEGRAM_API_ID — アプリ ID
• TELEGRAM_API_HASH — アプリハッシュ — シークレットです。絶対にそのまま出力しないでください
• TELEGRAM_SESSION_STRING — Telethon の StringSession = アカウントへの完全なアクセス権です。絶対にログ、エコー、または出力しないでください。 アカウントのパスワードと同様に扱ってください。

CLI

このスキルには scripts/tg.py が含まれています。自己完結型で、サードパーティー依存関係は telethon のみです（サンドボックスにプリインストール済み）。同梱されたパスを変数に設定して呼び出してください。呼び出しのたびにヒアドキュメントで再作成する必要がないため、複数ステップのワークフロー（ドライラン → 確認）でも、呼び出しの間にヘルパーが失われることはありません。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block below).
TG="$SKILL_DIR/scripts/tg.py"; [ -f "$TG" ] || TG=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tg.py' 2>/dev/null | head -1)
[ -f "$TG" ] || { echo "telegram script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TG" whoami

状態を変更するすべてのコマンド（send、reply、send-file、forward、edit、delete、react、mark-read、join、leave）にはゲートが設けられています。末尾に --confirm がない場合は、DRY-RUN のみを実行し（実行する操作を表示しますが、変更は加えません）、読み取りコマンドはそのまま実行されます。--confirm が有効になるのは最後の引数として指定された場合のみです。そのため、メッセージやキャプションに「--confirm」が含まれているだけで、誤って確認扱いになることはありません。

まず接続を確認する

python3 "$TG" whoami
# → {"id": 100000000, "username": "<the connected handle>", "name": "<display name>", "phone": "..."}

認証またはセッションのエラーが発生した場合、保存済みのセッションは無効です。https://studio.acedata.cloud/console/connectors で再接続するようユーザーに伝えてください。

読み取りレシピ

目的	コマンド
最近の会話	python3 "$TG" list-chats 20
未読があるチャットのみ（優先順位順）	python3 "$TG" unread
チャットの履歴（古い順→新しい順）	python3 "$TG" get-messages <target> 50
1 つのチャット内を検索	python3 "$TG" search <target> "kw" 30
すべてのチャットを検索	python3 "$TG" search-global "kw" 30
連絡先を一覧表示	python3 "$TG" contacts
チャット／ユーザーの情報	python3 "$TG" chat-info <target>
フォーラムグループのトピック（スレッド）を一覧表示	python3 "$TG" list-topics <target>
メッセージの t.me リンク	python3 "$TG" message-link <target> <msg_id>

<target> は数値 ID（list-chats で取得でき、最も確実）、@username、電話番号、またはチャットの正確な名前です。メッセージ行の out:true はユーザーが送信したことを示し、media:true は添付ファイルがあることを示します。

未読の要約パターン：unread → 重要なチャットを選ぶ → 各チャットで get-messages <id> N を実行 → 要約します。2 万件のメッセージをすべて出力せず、未読数が多いものや関連性の高いものをサンプルしてください。

メディア

# Download an attachment from a message → returns the saved path
python3 "$TG" download-media <target> <msg_id> ./tg_downloads
# Send a local file OR an http(s) URL (optional caption) — GATED
python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm

http(s) URL はまず実際のローカルファイルにダウンロードされます（URL または Content-Type から適切な拡張子を取得）。その後アップロードされるため、リモート画像はドキュメントではなく写真として送信され、何も起きないということもありません。画像を送るには、CDN URL を send-file にそのまま渡すのが確実です。

ダウンロードしたファイルをリンクとしてユーザーに返すには、download-media の後に CDN へアップロードしてください（cos-upload スキルを参照）。

投稿レシピ — すべて要確認（末尾に --confirm がない限りドライラン）

送信／編集／削除は、実際のユーザーとして実行されます。必ず最初にドライランを実行し、実行内容をユーザーに正確に示して、明示的な「はい」を得てから、最後の引数に --confirm を付けて再実行してください。一括送信は絶対にしないでください。

python3 "$TG" send    <target> "text"                          # → dry_run; add --confirm to send
python3 "$TG" send    <target> "text" --topic <top_message> --confirm  # into a forum topic thread
python3 "$TG" reply   <target> <msg_id> "text" --confirm
python3 "$TG" forward <from_target> <msg_id> <to_target> --confirm
python3 "$TG" edit    <target> <msg_id> "new text" --confirm   # own messages
python3 "$TG" delete  <target> <msg_id> --confirm              # destructive
python3 "$TG" react   <target> <msg_id> "👍" --confirm
python3 "$TG" mark-read <target> --confirm                     # sends read receipts
python3 "$TG" join    <@username|t.me/link|t.me/+invite> --confirm  # join a public group/channel or a private invite
python3 "$TG" leave   <target> --confirm                       # leave a group/channel (not private chats)

join は、公開されている @username／t.me/<name>（→ JoinChannelRequest）または非公開の招待リンク t.me/+HASH／t.me/joinchat/HASH（→ ImportChatInviteRequest）を受け付けます。他人のグループに参加することは、アカウントのメンバーシップに実際の変更を加える操作です。他の書き込みと同様に扱ってください。ドライランを実行し、確認を得てから、--confirm を指定します。自動で参加してから一括メッセージを送ることは絶対にしないでください。アカウントがスパム制限を受けます。

フォーラムグループへの投稿。 一部のスーパーグループはフォーラムです。メッセージはトピック（スレッド）内に投稿されるため、グループのルートに通常の send を実行すると TOPIC_CLOSED で拒否されます。最初に list-topics <target> を実行し、"closed": false のトピック（開いているチャット／オフトピックのスレッド。タイトルは Беседка／Флуд／Chat／Offtopic／General など）を選んでから、send <target> "text" --topic <top_message> --confirm で投稿してください（top_message はスレッドのアンカーとなる ID です）。

ドライランは {"dry_run": true, "command": ..., "args": [...]} を返します。これをそのまま確認のプロンプトとしてユーザーに提示してください。

注意点 — ユーザーが困る前に伝えること

• これはユーザーの実際のアカウントです。 書き込みの前に確認してください。読み取りによって非公開チャットの内容が見られます。
• FloodWaitError：Telegram はユーザーボットにレート制限をかけます。N 秒のフラッド待ちが発生した場合は、N 秒後に再試行するようユーザーに伝えてください。何度も繰り返し再試行してはいけません（制限が強化され、禁止につながります）。
• 期限切れセッション：Telegram の「設定」→「デバイス」から取り消された場合、または約 6 か月間利用されなかった場合に発生します。AuthKeyError／未認証の場合は、コネクターを再接続してください（再試行しないでください）。
• TELEGRAM_SESSION_STRING／TELEGRAM_API_HASH は絶対に表示しないでください。アカウント全体に関わる秘密情報です。
• 宛先：list-chats の数値 id を優先してください（ヘルパーがダイアログをスキャンしてアクセスハッシュを取得します）。名前は完全一致が必要です。ユーザー名には先頭に @ が必要です。
• message-link が機能するのは、公開チャンネル／スーパーグループのみです。非公開の 1 対 1 チャット／基本グループではエラーになります（共有可能なリンクが存在しません）。
• 送信時の TOPIC_CLOSED ＝ フォーラムのスーパーグループです。ルートには投稿できません。list-topics を実行し、開いている（"closed": false）スレッドを選んで、send ... --topic <top_message> を実行してください。
• 送信時の ChatWriteForbiddenError ＝ 通常はチャンネルにリンクされたディスカッショングループです。グループ自体で投稿が禁止されていなくても、コメントグループに書き込むには、親チャンネル（join <parent_channel>）を先に購読する必要があります。
• edit／delete は通常、ユーザー自身のメッセージにのみ適用されます（管理者は管理するグループ内の他人のメッセージも削除できます）。

出力を記録する

公開に成功し、公開結果の URL を取得したら、ユーザーがこの成果物を My Outputs で追跡できるよう、組み込みの publish_artifact ツールを 1 回だけ呼び出してください。

publish_artifact(kind="message", channel="telegram", title="<title>", url="<the REAL returned URL>", status="delivered")

実際に返された URL を使用してください。作り上げた URL を使ってはいけません。公開された項目ごとに 1 回、配信が確認された後にのみ呼び出してください。公開に失敗した場合は呼び出さないでください（または status="failed" を使用してください）。_shared/artifacts.md を参照してください。