telegram-userbots

Telegram ユーザーボット — MTProto とその代償

ボットトークンはソフトウェアに発行されます。MTProto セッションは、ログイン済みの人間そのものです。その人と同じ権限がファイルに保存され、トークンにある保護は何もありません。このスキルに含まれるすべての内容は、この違いに由来します。

2026-08-25 時点の Telethon 1.44.0 および core.telegram.org に基づいています。Telethon のマイナーリリースでは、セッションやエンティティキャッシュの動作が変わります。使用中のバージョンは、決めつけずに確認すべき事実です。

詳細な資料は必要に応じて読み込んでください。

読むもの	読むタイミング
references/sessions-and-auth.md	ログイン、セッションの保存やローテーション、またはマシン間の移行を行うとき
references/rate-and-flood.md	チャット、ユーザー、メッセージをループ処理するとき — FloodWait、ペーシング、テイクアウト
references/entities-and-history.md	ピアの解決、履歴の反復処理、大規模なメディアのダウンロードを行うとき

---

まず、本当に必要ですか？

コードを1行でも書く前に答え、その答えを書き留めてください。

用途	Bot API でできること	結論
ボットが参加しているチャットのメッセージに反応する	はい	ボットを使う
ボットを開始したユーザーにメッセージを送る	はい	ボットを使う
管理者になっている公開チャンネルを読む	はい	ボットを使う
管理者ではないチャンネルの履歴を読む	いいえ	ユーザーボット
参加する前のチャットの過去ログを読む	いいえ	ユーザーボット
特定の人物として操作する	いいえ	ユーザーボット
20 MB を超えるファイルをダウンロードする	いいえ	ユーザーボット、またはローカル Bot API サーバー
グループのメンバーを大規模に列挙する	いいえ	ユーザーボット。以下のリスクも確認してください

ローカル Bot API サーバーを使えば、アカウントなしでファイルサイズの上限を解消できます。 21 MB の動画を理由にユーザーセッションを使うのは、いずれにせよ必要になるインフラ作業の代わりに、恒久的なリスクを抱え込むことです。

拒否すべき理由です。これは形式的な注意喚起ではありません。 ユーザーアカウントは制限または禁止されることがあり、Telegram はその理由を説明せず、迅速な異議申し立てもできず、アカウントにあったものを復元することもありません。実在する人物のアカウントなら、影響範囲はその人のメッセージ、グループ、ログインに及びます。個人アカウントの自動化は、責任者を明確にしたうえで下す決定でなければ、決定とは言えません。

セッションファイルは認証情報です

import os
from telethon import TelegramClient
from telethon.sessions import StringSession

client = TelegramClient(
    session=StringSession(os.environ["TG_SESSION"]),   # from the secret store
    api_id=int(os.environ["TG_API_ID"]),
    api_hash=os.environ["TG_API_HASH"],
)

• .session ファイルがあれば、パスワードも2FAの入力もなしにアカウントへ完全にアクセスできます。 別のマシンにコピーすると、そのマシンがログインします。.gitignore に追加し、シークレットストアに保管し、パスワードと同じ扱いをするバックアップに含め、イメージレイヤーやログには決して保存しないでください。
• api_id/api_hash は my.telegram.org から取得するもので、アカウントではなく アプリケーション を識別します。 セッションではなく、同じレベルの秘密情報でもありませんが、公開してはいけません。
• セッションを失くした場合は復旧できますが、漏えいした場合はインシデントです。 アカウント自身の デバイス 画面から失効させると、そのセッションはすべての場所で終了します。
• ログアウトしても締め出しにはならず、他のセッションを終了させるには古いセッションが必要です。 auth.logOut は、次回のログインコード入力を省略できる future_auth_token を返す場合があります。そのため、実際の防壁となるのは2段階認証のパスワードです。また、24時間未満のセッションから他のセッションを終了することはできません（FRESH_RESET_AUTHORISATION_FORBIDDEN）。tg://login?token= リンクを承認すると、そのリンクを生成したユーザーがログインします。セッションの一覧表示、監視（UpdateNewAuthorization）、終了については、次を参照してください。 references/sessions-and-auth.md。
• このマシンで2026-08-25に確認済み：5つの Telethon プロジェクトすべてでセッションが gitignore されており、gitで追跡されているものはありません — この環境で実際に防げた唯一の落とし穴です。この状態を維持してください。

FloodWaitErrorは API の正常動作です

from telethon.errors import FloodWaitError

try:
    await client.send_message(peer, text)
except FloodWaitError as e:
    if e.seconds > MAX_ACCEPTABLE:      # a decision, not a sleep
        raise
    await asyncio.sleep(e.seconds + 1)
    await client.send_message(peer, text)

• **無視して握りつぶすべきエラーでも、むやみに再試行する合図でもありません。**待機すべき時間が正確に示されています。それ以外の時間を設定するのは、Telegram がすでに伝えた値を推測し直すことになります。
• **secondsの値が非常に大きい場合は、別の事象です。**数分ならペースが速すぎます。数時間ならアカウントに制限がかけられており、そのまま続ければ制限が BAN につながります。上限を設定し、アラートを出して、停止してください。
• **リクエストハンドラー内で待機すると、1件のフラッドがサービス停止につながります。**待機は、ユーザーが応答を待っている処理経路ではなく、キューを持つワーカーに任せてください。
• 2026-08-25 にここにある 6 つの Telethon プロジェクトを調査したところ、FloodWaitErrorを処理しているのは 6 つ中 3 つだけでした。残りの 3 つは最初の制限に達するまで動き続け、その時点の状態のまま停止します。

マイナーバージョンを固定し、その理由を把握する

この環境では 4 つのボットがtelethon==1.37.0に固定され、5 つ目は1.44.0を実行しています。この固定の理由はrequirements.txtに記されています。マイナーリリースではセッションやエンティティキャッシュの動作が変わるため、稼働中のボットで 7 つ先のマイナーバージョンに移行するなら、独立した変更と検証が必要です。

これは適切な方針であり、原則として明記する価値があります。**ユーザーボットの依存関係は単なるライブラリではなく、ログイン状態を保持するプロトコルクライアントです。**アップグレードによってセッション形式が無効になったり、get_entityのコストが変わったり、例外のモジュールが移動したりする可能性があります。慎重に、ボットを 1 つずつ、再作成できるセッションを使ってアップグレードしてください。

エンティティの解決にはコストがかかります

get_entityはネットワークアクセスを伴う場合があり、ループ内で呼び出すのは、原因不明に見える FloodWait を招く最も一般的な方法です。

• **すでに取得している ID を優先してください。**キャッシュ済みのInputPeerならコストはかかりませんが、ユーザー名を使うとリクエストが発生します。
• **PeerIdInvalidErrorは通常、そのアカウントがまだそのピアを認識していないことを意味します。**ID が間違っているという意味ではありません。ユーザーアカウントからアクセスできるのは、これまでに遭遇した相手だけです。
• ライブラリ独自のイテレーター（iter_messages、iter_dialogs）で反復し、ページングはライブラリに任せてください。独自にオフセットを管理すると、リクエストが重複し、制限にも再度引っかかります。
• 一括エクスポートには、正規の手段としてtakeoutが用意されています。この用途に限って制限が緩和され、実行内容も Telegram に伝わります。

詳細はreferences/entities-and-history.mdをご覧ください。

2 つのアカウント、2 つのライフサイクル

ユーザーボットには、ボットにはない 2 つ目の障害モードがあります。**ユーザーが別の場所でログインしたり、パスワードを変更したり、セッションを終了したりすると、プロセスは無効になったセッションを保持したまま動作不能になります。**これは一時的な状態ではなく、終端状態／失効状態です。プロセス自体は LIVE でも、READY ではありません。再起動しても、成功するはずのないログイン処理を繰り返すだけです。アカウント名を含めてアラートを出し、新しい認証（電話番号が必要な再ログイン）が済むまで作業を停止してください。クラッシュループにはしないでください。これは、長期間使う認証済み接続に対してsheleg-devがエラー追跡で定めている 3 状態の契約、すなわち liveness、readiness、degraded_auth（一時的な再試行、終端状態では停止）と同じ考え方です。**スーパーバイザーによる再起動はrecoverableポリシーの場合に限ります。**失効したセッションはterminalであり、このスキルの復旧契約テーブルにある「停止してアラート」の行に該当します。これにより、同じ事象に対して 2 つのパックが正反対の対応を取ることを防げます。ボットで対応できる重要な処理のクリティカルパスに、ユーザーボットを使わないでください。

リリース前の確認事項

1. ユーザーアカウントが必要な理由が文書化されており、ボット API で代替できないか確認済みです（§ まず、本当に必要ですか？）。
2. セッションはシークレットストアに保管され、Git の追跡対象から除外され、失効可能です（§ セッションファイルが認証情報です）。
3. FloodWaitError を捕捉し、上限を設けて、アラートを通知します。上限なく待機して解決しようとしてはいけません（§ FloodWaitError は API が正常に動作している証拠です）。
4. クライアントのバージョンを固定し、アップグレードは個別の変更として行います（§ マイナーバージョンを固定する）。
5. セッションが無効になったときは、人間に通知します。無限に再起動してはいけません（§ 2つのアカウント、2つのライフサイクル）。
6. アカウントに2段階認証のパスワードを設定し、誰かがセッションを監視します。新しい UpdateNewAuthorization が人間に通知され、信頼済みセッションのうち最も古いものが終了するようにします（§ セッションファイルが認証情報です）。

トリガー

ここに分類されるその他のフレーズ：「ユーザーアカウント」、「チャンネル履歴の読み取り」、「api_hash」、「телетон」。

0.5.4 の説明からこちらに移動した語句：「pyrogram」、「мтпрото」、「сессия телеграм」。