チュートリアル September 2, 2026

WhatsAppグループ参加リクエストの承認キューをUnifyPortで作る

WhatsAppグループの参加リクエストを自動処理したい場合、webhookだけを唯一の状態として扱わないでください。WhatsApp側のグループ承認設定が、参加前の承認が必要かどうかを決めます。UnifyPortでは group.join_request を低遅延の通知として受け取り、GET /v1/accounts/{account_id}/groups/join-requests で確実な保留リストを読み、POST /v1/accounts/{account_id}/groups/join-requests/update で対象者を承認または拒否します。

要点

WhatsApp公式ヘルプによると、Approve new members はデフォルトではオフです。オンにすると、グループ管理者が参加希望者を承認または却下します。
group.join_request は通知として使います。UnifyPortのドキュメントでも、承認UIでは List group join requests をポーリングして信頼できる状態にすることを勧めています。
承認前に account_id、グループid、申請者id、申請方法、社内の判断ログを保存してください。
LINE中心の日本チームでも、越境販売や海外サポートでWhatsAppグループを併用することがあります。入站イベントの扱い方は Webhook-First Inbound Integration Checklist と同じです。

WhatsApp側が管理する範囲

グループ参加承認は、WhatsAppのグループ管理者機能です。公式Help Centerの How to approve new members as a group admin は、Approve new members がオンのとき、参加希望者は管理者の承認を待つと説明しています。また、この設定はデフォルトでオフです。

つまり、バックエンドはWhatsAppの設定を置き換えるものではありません。バックエンドが担うべきなのは、申請が出たら誰が見るのか、何を根拠に判断するのか、どの申請者idに承認または拒否を送るのか、という運用フローです。

承認キューの構成

署名付きwebhook endpointでグループイベントを受け、一覧APIで状態を照合します。

webhook endpointを作成し、subscribed_events に group.join_request を含めます。すべての公開イベントを集める運用なら ["*"] も使えます。選び方は UnifyPort Webhook Event Filters を参照してください。
group.join_request を受けたら、account_id と data.conversation.id をキーに同期ジョブを作ります。
List group join requests を呼び出し、現在の保留申請を取得します。レスポンス項目の id が、後で member_ids に渡す値です。
保留申請をモデレーターに見せるか、社内ルールを適用します。
更新APIで action: "approve" または action: "reject" を送ります。

Telegramグループ参加リクエストの承認キューを実装したことがあるなら、考え方は同じです。pushイベントはワーカーを起こすための合図で、信頼する状態は一覧APIから取得します。

イベントとリクエスト例

WhatsAppの参加リクエストは、次のような標準イベントで届きます。

{
  "id": "evt_gjr_5e1c8a3f9b",
  "type": "group.join_request",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T13:10:30Z",
  "data": {
    "conversation": { "id": "120363041234567890@g.us", "type": "group" },
    "requester": { "id": "8613912345678@lid", "type": "user" },
    "request_method": "invite_link",
    "event": { "kind": "group_join_request" }
  }
}

承認前に一覧を取得します。

curl "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests?group_id=120363041234567890%40g.us" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

返ってきたidを使って承認または拒否します。

curl -X POST "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests/update" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "120363041234567890@g.us",
    "action": "approve",
    "member_ids": ["8613912345678@lid"]
  }'

小さなNode.jsワーカー

const pending = new Map();

app.post('/webhook', verifyUnifyPortSignature, async (req, res) => {
  const event = req.body;
  if (event.type !== 'group.join_request') return res.status(200).end();

  const groupId = event.data.conversation.id;
  const key = `${event.account_id}:${groupId}`;
  pending.set(key, { accountId: event.account_id, groupId });

  res.status(200).end();
});

本番環境では、webhook delivery に従い、signing_secret、X-Device-Timestamp、X-Device-Signature を使って raw body の HMAC-SHA256 署名を検証してください。

制限とトレードオフ

この仕組みは、管理権限のないアカウントに管理権限を与えるものではありません。また、group.join_request は best-effort の通知なので、承認UIは表示前または送信前に保留一覧を再取得するべきです。UnifyPortはイベントと操作を標準化しますが、誰をグループに入れるかはチームのルールとWhatsAppの権限で決まります。

FAQ

webhookだけでWhatsAppグループ参加リクエストを承認できますか？

推奨しません。webhookはワーカーを起動する合図です。実際の承認前に GET /v1/accounts/{account_id}/groups/join-requests を呼び、返ってきた項目のidを更新APIへ渡してください。

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

List group join requests のレスポンス項目にある id を使います。表示名や推測した電話番号形式を使わないでください。

WhatsApp Business APIは必要ですか？

このチュートリアルは、グループ権限を持つWhatsAppアカウントをUnifyPortのunofficial interfaceで接続する前提です。参加申請が発生するかどうかは、WhatsApp公式のグループ承認設定で決まります。

次に読むべきドキュメントは？

まず List group join requests を確認し、モデレーターUIができたら Approve / reject join requests を接続してください。

Sources checked on 2026-09-02

WhatsApp Help Center: How to approve new members as a group admin
UnifyPort API reference: Webhook events and List group join requests

UnifyPort API

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

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

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