チュートリアル August 24, 2026

Telegramグループの参加リクエストを確実に処理する承認キューの作り方

Telegramグループの承認キューは、プッシュイベントだけに依存させてはいけません。保留中の参加リクエストを定期的に取得し、返された各項目の id を審査対象の識別子として使い、approve または reject を明示的に送信します。group.join_request webhookは画面を素早く更新するために使えますが、この通知はベストエフォートです。正しい状態は一覧APIで確認します。

要点

Telegram公式Bot APIは chat_join_request 更新を提供します。ただし、Botは管理者で、can_invite_users 権限を持つ必要があります。
UnifyPortでは、group_id と enabled: true で承認制を有効にし、同じ group_id で保留中の一覧を取得します。
承認・拒否時の member_ids には、一覧で返された項目の id を入れます。
group.join_request は低遅延の合図として使い、必ず一覧取得で整合させます。
参加条件が明確で監査可能な場合を除き、人による判断を残します。

実装前にアイデンティティを選ぶ

Botによる管理で問題なければ、Telegramの公式Bot APIには ChatJoinRequest、approveChatJoinRequest、declineChatJoinRequest が用意されています。Botはグループ管理者であり、can_invite_users 管理者権限を持つ必要があります。Telegramだけを対象とし、最初からBot管理を想定したグループに適しています。

既存のTelegramアカウントで審査したい場合や、LINEなど他のメッセージング運用と同じ接続パターンにそろえたい場合は、接続済みのUnifyPort messaging accountを利用できます。選択前にTelegramのAPI ID・API HashとBot Tokenの違いを確認してください。

これらは別のモデルです。Bot TokenはBotを表し、API IDとAPI HashはTelegramクライアントアプリを識別します。UnifyPortのmessaging accountは、API操作を行う接続済みアカウントを表します。

Telegram参加リクエスト承認キューの実装

1. 参加承認モードを有効にする

保留キューを作るには、グループ側で参加承認を必須にします。接続済みアカウントID、対象の group_id、真偽値の enabled を送信します。

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-approval-mode" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "enabled": true
  }'

この操作にはグループ管理者権限が必要です。設定操作は、定期実行する審査workerから分離してください。workerが実行のたびにグループ方針を切り替える必要はありません。現在のリクエスト仕様は参加承認モードの設定で確認できます。

2. 保留一覧を定期取得し、正とする

group_id をクエリパラメーターとして渡します。

curl \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests?group_id=group_example" \
  -H "X-Api-Key: <YOUR_API_KEY>"

ローカルには、申請ID、対象グループ、判断状態、審査担当者、ローカル時刻など、アプリに必要な情報だけを保存します。一覧に項目が現れる前に、必ず対応するwebhookが届くとは考えないでください。

重要な対応関係は単純です。グループ参加リクエスト一覧で返された項目の id を、更新APIの member_ids に入れます。表示名や推測したTelegram識別子で置き換えてはいけません。

3. 審査結果を明示する

ローカルでは最低でも次の4状態を持たせます。

状態	意味	次の処理
`pending`	上流に存在し、未審査	管理者に表示
`approved`	審査担当者が承認	`approve` を送信
`rejected`	審査担当者が拒否	`reject` を送信
`stale`	再取得時には存在しない	追加操作せず終了

外部フォームの回答、許可リスト、手動確認を判断材料にしても構いません。ただし、それらはアプリ独自のルールであり、TelegramやUnifyPortのフィールドではないことを明確にします。信頼できない表示名や自己紹介だけで自動承認しないでください。

4. まとめて承認または拒否する

一覧から得た1件以上のID、対象グループ、明示的なアクションを送信します。

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests/update" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "action": "approve",
    "member_ids": ["member_example", "member_other"]
  }'

拒否する場合は同じ形式で "action": "reject" を指定します。このルートにもグループ管理者権限が必要です。再試行やバッチ設計の前に、参加リクエストの承認・拒否の最新仕様を確認してください。

更新後は必ず一覧を再取得します。複数の管理者がほぼ同時に操作しても、ローカルUIを現在の上流状態へ戻せます。

5. `group.join_request` はworkerを起こす合図にする

審査画面をすぐ更新したい場合は、webhookで group.join_request を購読します。承認制グループへの参加申請を示すイベントですが、配信はベストエフォートです。安全な流れは次のとおりです。

イベントを受信する。
webhookを検証して応答する。
審査フローの再取得をキューに入れる。
一覧APIを呼び出す。
返された保留一覧から画面を作る。

プッシュは遅延を減らし、再取得は正しい状態を回復します。受信側を作る際は、WebhookのHMACリプレイ対策と再試行も合わせて実装してください。

参加申請とメンバー変更を分離する

参加リクエストは、メンバー追加の完了通知ではありません。group.join_request を受け取った時点で申請者をメンバーとして記録しないでください。承認、再取得を行い、その後のメンバー変更は別のイベント経路で処理します。

監査ログでも「参加申請」「管理者による承認」「メンバー追加」は別々の事実です。承認後の処理はTelegram Communitiesの追加・削除イベントを参照してください。

本番運用チェックリスト

接続済みアイデンティティにグループ管理者権限があることを確認する。
X-Api-Key はサーバー側のシークレットとして保存する。
承認制の有効化は独立した管理操作にする。
webhookが届かない場合でも保留一覧を定期取得する。
member_ids には一覧で返された申請 id だけを使う。
審査担当者と判断理由を独自の監査ログへ記録する。
承認・拒否後は毎回一覧を再取得する。
更新通知として使う前にwebhook署名を検証する。
参加申請イベントをメンバー変更の証拠にしない。

制約と選び方

管理者Botが想定どおりのアイデンティティで、Telegramだけを扱うなら、公式Bot APIが適しています。公式ドキュメントがあり、承認と拒否の専用メソッドを利用できます。

既存アカウントのアイデンティティや、LINEを含む複数チャネルで共通のAPIパターンを優先するなら、UnifyPortのunofficial interfaceを検討できます。ただし、管理者権限、明確な審査方針、API Keyの安全な管理、一覧による整合処理は引き続き必要です。誰を信頼するかをインターフェースが決めるわけではなく、イベントがベストエフォートである以上、定期取得経路も残します。

よくある質問

Telegram Botはグループ参加リクエストを承認できますか？

はい。公式Bot APIに承認・拒否メソッドがあります。Botはグループ管理者で、can_invite_users 権限を持つ必要があります。

`group.join_request` webhookだけを処理すればよいですか？

いいえ。素早い通知として使い、その後に保留一覧を取得してください。UnifyPortの仕様ではこの通知はベストエフォートで、一覧取得が信頼できる情報源です。

`member_ids` には何を入れますか？

一覧APIの各項目が返す id を使います。表示名から推測しないでください。

複数の申請を1回で承認できますか？

はい。更新APIは1件以上の member_ids と、approve または reject の action を受け取ります。

承認後に必要な処理は何ですか？

保留一覧を再取得してローカルキューを更新し、その後のメンバー変更を元の申請とは別に処理します。

次のステップ

まずグループ参加リクエスト一覧のAPIリファレンスを確認し、その整合ループの周囲に承認モードと更新APIを実装してください。

情報源

2026年8月24日に確認：

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。

API Key を取得 API リファレンスを見る