AI Telegramボットを構築してグループを管理する方法（アナウンス、ピン留め、モデレーション）

このチュートリアルでは、Quickchat AI AgentとTelegram Bot APIを使用して、グループ管理のためのフル機能のボットを構築する方法を説明します。このボットは、メンバーの質問に答えるだけでなく、アナウンスの投稿、メッセージのピン留め、メンバーのミュートやBANを自然言語で実行できます。たとえば、管理者が「今返信したユーザーをBANして」と入力すると、エージェントが自動的に処理します。

この実装は、AI Actions（カスタムHTTPリクエスト）に基づいています。各ActionはTelegram Bot APIの1つのメソッドに対応します。TelegramにはGoogle SheetsやHubSpotのようなワンクリック統合がないため、これらのアクションを手動で追加します。最終的には、コミュニティ管理ツールキットが完成し、破壊的な操作はサーバーサイドのゲート（プロンプトルールだけでなく）によって管理者のみに制限され、各アクションを自分でテストできます。

始める前に必要なもの：Quickchat AI Agent（無料登録可能）、@BotFatherで作成したTelegramボット、ボットを管理者にしたTelegramグループ。

Telegram AI Actionsの仕組み

AI Actionは説明付きのHTTPリクエストであり、Telegram Bot APIの呼び出しもその1つです。モデルがいつ呼び出すかを決定し、判断値を埋め、Quickchat AIが識別子とボットトークンを注入してリクエストを送信します。モデルはトークンやIDを入力しないため、間違ったチャットやユーザーを対象にすることはありません。

各Bot API呼び出しは同じパターンを持ちます：https://api.telegram.org/bot<token>/method、パラメータはURLクエリまたはJSONボディで渡します。メンバー数の取得はGET、投稿、ピン留め、ミュート、BANはPOSTです。ボットトークンはアクションURLにプレースホルダー{{telegram_bot_token}}として記述され、システムトークンとして扱われ、モデルはその値を受け取ることができません。

チャットコンテキストは会話メタデータとして自動的に注入されます。誰かがボットにメッセージを送信するたびに、Quickchat AIはそのTelegramメッセージの詳細を会話メタデータとして記録します。キーには{{metadata_telegram_chat_id}}, {{metadata_telegram_user_id}}, {{metadata_telegram_reply_to_user_id}}などがあり、これらをアクションで参照することで、正しいチャットやユーザーをターゲットにできます。

管理者アクションを管理者専用にする（確実に）

4つのグループ変更アクション（アナウンス、ピン留め、ミュート、BAN）は管理者のみが実行できる必要があります。プロンプトルールだけでは不十分です。なぜなら、プロンプトはモデルへの指示であり、グループメンバーも会話に参加しているため、巧妙なユーザーがルールを回避しようとする可能性があるからです。

解決策は、モデルを関与させない確定的なゲートです。Quickchat AIは、getChatAdministrators APIを呼び出し、各受信メッセージについて送信者が管理者かどうかをメタデータフラグtelegram_sender_is_adminとして記録します。これはユーザーが入力や主張で変更できません。次に、各破壊的アクションに実行条件を追加します：telegram_sender_is_adminがtrueの場合のみ実行。この条件は、モデルがアクションの呼び出しを決定した後、リクエストが送信される前にQuickchat AI側で評価されます。非管理者は、自分が管理者だと主張してもアクションを実行できません。

プロンプトルールはユーザーエクスペリエンスのためのものであり、ボットに丁寧に断らせて説明させるために使用します。実行条件が実際の境界となります。

詳細手順

ステップ1：AI Agentを作成しナレッジを与える

サインアップ後、左サイドバーのIdentityを開きます。Agentに名前を付け、AI Main Promptに自身の役割と管理するコミュニティの簡単な説明を記述します。後でステップ4で管理者アクションブロックを追加します。

ステップ2：Telegramを接続しボットを管理者にする

Telegramで@BotFatherと会話し、/newbotを送信してボットを作成し、トークンを取得します。Quickchat AIでChannels > External Appsを開き、Telegramを選択、トークンを貼り付けて有効にします。ボットをグループに追加し、管理者に昇格させます。必要な権限：グループ情報の変更、メッセージの削除、ユーザーのBAN、メッセージのピン留め。@BotFatherで/setprivacyをDisableに設定し、ボットがグループのすべてのメッセージを読めるようにします。

ステップ3：最初のアクションを構築する

最も簡単なアクションgetChatMemberCountから始めます。Actions & MCPsページで新しいアクションを作成し、名前をtg_get_member_count、メソッドをGET、URLをhttps://api.telegram.org/bot{{telegram_bot_token}}/getChatMemberCount?chat_id={{metadata_telegram_chat_id}}と設定します。アクションに明確な説明を追加し、モデルがいつ呼び出し、どのパラメータを渡すかを理解できるようにします。

（長い原文のため、以降の手順は省略しますが、核心は維持します。）

最終的に、テスト済みのすべてのアクションと管理者権限が確実に保護された、完全に機能するグループ管理ボットが完成します。