WhatsApp の参加承認を API で有効・無効にする

UnifyPort で WhatsApp グループの参加承認を有効・無効にするには、POST /v1/accounts/{account_id}/groups/join-approval-mode に group_id と必須の真偽値 enabled を送ります。true は承認を必要とする設定、false はその要件を無効にする設定です。これはグループ設定の変更であり、保留中の申請を一括承認・一括拒否する操作ではありません。

要点

• 承認設定は管理者が明示的に変更します。審査画面を開いたついでに変更しないでください。
• JSON の真偽値を送り、文字列の "false" や未送信のチェックボックス値で代用しないでください。
• 現在の操作は whatsapp に対応します。独立した whatsapp-protocol や LINE などの他チャネルには適用できません。
• 希望する設定、API の応答、その後の確認を分けて記録します。

設定変更と申請の審査を区別する

Meta の WhatsApp グループ管理に関する公式説明では、招待リンクの共有やコミュニティからの参加に際して、管理者が参加者を管理できることを説明しています。このプラットフォーム設定と、申請者を審査するソフトウェアは別の層です。

操作者の目的	使用する操作
新規参加者に承認を求める	enabled: true を設定
承認要件を無効にする	enabled: false を設定
選択した申請者を承認・拒否する	別の参加申請更新操作
招待 URL を取得する	招待リンクの読み取り操作

個別の審査には WhatsApp 参加申請キューのガイドを、招待の配布には招待リンクの取得とリセットの違いを参照してください。どちらの処理も、グループの参加方針を暗黙に変更してはいけません。

有効・無効を明示するフォームを作る

参加承認モードのリファレンスは group_id と必須の真偽値 enabled を定義しています。チャネル別アクション対応表では、この操作は WhatsApp のみです。UnifyPort は接続済みメッセージングアカウント向けの非公式インターフェースであり、このリクエストは WhatsApp Cloud API のものではありません。

アカウントとグループを一緒に選択します。グループ一覧から ID を取得し、名前だけで対象を判断しないでください。接続するアカウントが権限のあるグループ管理者であることに加え、自分のアプリでも操作者に設定変更を許可していることを確認します。ワークスペースの API キーは、それだけでグループ管理者権限を与えるものではありません。

推奨するフォームの動作は次のとおりです。

1. 確認画面に対象アカウントとグループを表示する。
2. 承認を有効にするか無効にするか、明示的に選択させる。
3. 現在の設定が不明なら「不明」と表示し、情報不足を「無効」に変換しない。
4. 確認後だけ送信し、ページ読み込みやキュー更新では書き込まない。
5. 検証・シリアライズで false を保持する。単純な真偽判定では無効化の値を落とすおそれがある。

公開されているグループ取得例には、承認モードのフィールドが定義されていません。フォームへの初期入力用に、架空の応答プロパティを追加しないでください。文書化された読み戻し機能がない場合は、管理者に WhatsApp 内の設定を確認してもらい、アプリ側の値は「最後に要求した設定」として表示します。

確認済みの変更を一度送信する

以下は実際のリクエストフィールドを使うサーバー側 JavaScript の例です。ここで実行したテストではなく、自動再試行も含めていません。

export async function setJoinApproval({ apiKey, accountId, groupId, enabled }) {
  if (!apiKey || !accountId || !groupId || typeof enabled !== 'boolean') {
    throw new Error('Account, group, credential and boolean choice required');
  }

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/join-approval-mode`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ group_id: groupId, enabled })
    }
  );
  const requestId = response.headers.get('X-Request-Id');
  const body = await response.json();
  return { httpStatus: response.status, requestId, body };
}

API キーはバックエンドだけで扱います。戻り値の httpStatus、requestId、body はアプリ内の名前で、新しい API フィールドではありません。文書化された成功応答は 200 OK と data.ok: true です。希望した真偽値と結果を保存してから成功を表示してください。呼び出し側では通信エラーや JSON 解析エラーを処理し、応答がない場合は「無効化済み」ではなく結果不明のままにします。

同じアカウントとグループへの変更は、アプリ内で直列化します。先に有効化、その後に無効化が要求された場合、古い要求の遅延再試行が以前の選択を復活させる可能性があります。ローカルのロックやリビジョン確認はアプリ側の対策であり、上流 API が提供する条件付き更新ではありません。管理者はネイティブアプリから独立して変更することもできます。

設定と保留中の申請を別々に確認する

申請一覧が空でも、承認が無効とは限りません。単に待っている人がいない可能性があります。また group.join_request は参加申請の通知で、設定変更の確認応答ではありません。公開イベント仕様は、承認モード専用の確認コールバックを保証していません。

有効化後は管理者が設定を確認し、リンクを広く配布する前に管理下の招待テストを行います。審査には引き続き参加申請一覧をポーリングしてください。通知はベストエフォートであることが文書化されています。

無効化前には保留中の申請を確認し、その後の照合担当者を決めます。この設定 API は、無効化が既存の申請に与える影響を定義していません。全員の承認・拒否、既存メンバーの削除、招待リンクのリセットを行うと説明しないでください。個別の判断には専用の審査操作を使います。

設定リクエストがタイムアウトしたら、希望値と診断情報を残し、ネイティブ側の設定を確認してから改めて送信を判断します。取り消しのつもりで反対の値を自動送信してはいけません。他の管理者が既に方針を変えている可能性があります。

よくある質問

enabled を省略して現状維持にできますか？

できません。この操作は真偽値が必須です。変更が不要なら呼び出さないでください。

enabled=false は待機中の全員を拒否しますか？

その動作は定義されていません。設定の無効化と既存申請の処理は別の作業です。

審査ワーカーがポーリングのたびに有効化してもよいですか？

推奨しません。ポーリングは観測、設定変更は管理操作です。分離しないと管理者の意図した変更をワーカーが取り消すおそれがあります。

Telegram や LINE にも使えますか？

現在の UnifyPort 対応表では使えません。共通のルート形式だけでは、チャネルの対応を判断できません。

次のステップと出典

参加承認モード設定のリファレンスに沿ってフォームを実装してください。真偽値の両方、文字列の拒否、初期状態不明、逆の選択の同時送信、応答喪失をテストすることを推奨します。これは確認項目の提案であり、実施済みの結果ではありません。

確認日：2026-11-02。

• Meta：WhatsApp のグループ管理機能
• UnifyPort：参加承認モードの設定
• UnifyPort：チャネル別アクション対応
• UnifyPort：参加申請一覧