← 全記事
チュートリアル

WhatsAppグループ管理者をAPIで変更：昇格と権限解除

UnifyPortでWhatsAppグループの管理者を変更するには、POST /v1/accounts/{account_id}/groups/members に group_id、メンバーのLIDを指定した member_id、action: "promote" または "demote" を送ります。1回の呼び出しで扱うのは1人と1つの操作です。管理者権限の解除は、メンバーを削除する remove とは異なります。まず現在のメンバー情報を読み取り、グループ作成者は通常の降格処理の対象外にしてください。

要点

  • メッセージングアカウント、グループ、メンバーをセットで選択します。表示名は識別子ではありません。
  • メンバー一覧の peer_id として返されるLIDを使い、電話番号から生成しません。
  • ボタンを有効にする前に member、admin、superadmin を区別します。
  • リクエスト後は状態を再取得します。タイムアウト時に逆の操作を自動送信しないでください。

変更したい役割を先に決める

WhatsAppの公式管理者ガイドは管理者の解除方法を説明し、グループ作成者は削除できず、自ら退出しない限り管理者であり続けるとしています。API連携でもこのルールは変わりません。

以下はアプリケーション側の推奨ルールです。すべてのリクエストがプラットフォームに受け入れられる保証ではありません。

現在の役割操作者の意図アプリケーションの判断
member管理者にする権限確認後に promote を提示
admin在籍したまま管理権限を外す確認後に demote を提示
superadmin作成者の権限を外す処理を止め、作成者の制約を説明
すでに目的の役割同じ変更を繰り返す再送せず表示を更新
メンバー情報が不明・不完全そのまま変更する再取得または手動確認

これは参加承認の処理ではありません。参加を認めるかどうかはWhatsApp参加申請の承認キュー、招待を共有する場合はグループ招待リンクの取得フローを使います。どちらも管理者の任命とは別の操作です。

最新の一覧から対象を選ぶ

選択したアカウントで会話メンバー一覧を取得します。グループの conversation_id を渡し、cursor でページを進め、対象行の peer_id と role を保持してください。役割は member、admin、superadmin で、最後の値は所有者または作成者を意味します。

以下は読み取りリクエストの例です。環境変数にはバックエンドで実際に選択した値を設定します。

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

data.has_more が真なら、返された data.next_cursor で続けます。最初のページにいないだけでは退出した証拠になりません。LIDはそのまま保持し、電話番号、表示名、形式の異なるイベント内の参加者IDから作らないでください。

送信前に、操作者がそのアカウントとグループを管理できること、接続中のWhatsAppアカウントに必要なグループ権限があることを確認します。ワークスペースのAPIアクセス権は、グループ管理者権限を意味しません。APIキーはサーバー内で管理します。

明示的な変更を1件ずつ送る

グループメンバー管理リファレンスは add、remove、promote、demote を定義しています。役割変更には後ろの2つだけを使い、単数の member_id を渡します。参加承認用の member_ids 配列ではありません。

次のJavaScriptは選択済みレコードから本文を組み立てる例です。認可の確認やネットワーク送信は行いません。

function roleChangeBody(groupId, selectedMember, action) {
  const expectedRole = { promote: 'member', demote: 'admin' };
  if (!Object.hasOwn(expectedRole, action) ||
      selectedMember?.role !== expectedRole[action]) {
    throw new Error('Refresh membership before changing this role');
  }
  if (!groupId || !selectedMember?.peer_id?.endsWith('@lid')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  return {
    group_id: groupId,
    member_id: selectedMember.peer_id,
    action
  };
}

JSONはバックエンドから、X-Api-Key を付けて文書化されたエンドポイントへ送ります。接尾辞の確認はローカルな誤操作防止にすぎず、本人性や権限を証明しません。確認画面にはグループ、参加者、操作を明示してください。更新中の一覧で先頭にある行から対象を決めてはいけません。

UnifyPortは接続アカウント向けの非公式インターフェースです。現在のチャネル別操作対応表では、この書き込みは whatsapp のみが対象です。LINE、Telegram、別プロバイダーの whatsapp-protocol は含まれません。LINEなどでメンバーを読めることやグループイベントを受け取れることから、役割変更まで可能だと判断しないでください。

結果を確認し、トランザクションを仮定しない

成功レスポンスは 200 OK と data.ok: true として文書化されています。HTTP結果と request_id を保存し、メンバー情報を再取得して、観測した役割と操作者の意図を分けて表示します。

推奨する対策は次のとおりです。

  1. 同じアカウント・グループ・メンバーへのアプリ内操作を直列化する。
  2. 送信直前に役割を再確認する。ダイアログを開いた後に他の管理者が変更している可能性がある。
  3. タイムアウト時は結果を未確定とし、現在のメンバー情報を確認する。自動再送や逆操作による補償をしない。
  4. 複数人の引き継ぎを不可分な処理と考えない。新しい管理者の役割を確認してから、別の操作として旧担当者の権限解除を検討する。

標準の group.updated では、data.changes[] に kind: "promoted" または "demoted" と members[] が含まれる場合があります。再確認のきっかけには使えますが、各リクエストに必ず届く受領通知ではありません。イベントの参加者IDをそのまま次の書き込み用LIDに使えるとも限りません。Webhookを処理する場合は署名と配信のリファレンスに従い、本文を信頼する前に検証し、重複や順序の入れ替わりに対応してください。

よくある質問

demote はグループからの削除ですか？

いいえ。管理者権限の解除とメンバー削除は別です。「管理者を解除」ボタンに remove を割り当てないでください。

グループ作成者の役割も変更できますか？

このフローでは提供しないでください。WhatsAppでは作成者は自ら退出するまで管理者です。UnifyPortのメンバー一覧では superadmin として表されます。

1回で複数の管理者を変更できますか？

このエンドポイントではできません。1つの member_id と1つの操作を受け付けます。アプリ側でまとめて処理する場合も結果は個別に記録します。

次のステップと資料

まず会話メンバー一覧を実装し、グループメンバー管理に沿って操作ボタンを追加してください。本番導入前に、ページング、作成者の選択、古い役割情報、権限不足、ネットワーク結果不明をテストします。これは推奨テスト項目であり、実行済みの結果ではありません。

確認日：2026-10-17。

UnifyPort API

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

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

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