API で WhatsApp グループのメンバーを削除する：ID と結果確認

UnifyPort で WhatsApp グループの既存メンバーを削除するには、POST /v1/accounts/{account_id}/groups/members に group_id、action: "remove"、メンバーの LID を指定した member_id を送信します。LID はメンバー一覧の peer_id から取得します。1 回のリクエストが対象とするのは 1 人です。レスポンスを保存して一覧を再取得し、画面の行が消えただけで削除成功と判断しないでください。

要点

• メンバー削除、管理者権限の解除、参加申請の却下、接続アカウント自身の退出は別の操作です。
• メッセージングアカウント、グループ、メンバーをセットで確認します。電話番号から LID を組み立ててはいけません。
• 見覚えのない表示名を理由に自動削除せず、対象と意図を確認します。
• タイムアウトは結果不明を意味します。繰り返し削除を送信する理由にはなりません。

ボタンを操作目的に合わせる

WhatsApp の公式メンバー管理ガイドでは、グループ情報から特定の参加者を選び、削除を確認する流れが示されています。API の画面でも対象の選択と確認を残し、曖昧な「整理」ボタンに破壊的な操作を隠さない設計にします。

目的	対応する操作
参加済みのメンバーを削除する	メンバー管理の remove
メンバーとして残し、管理者権限だけ解除する	別のアクション demote
まだ参加していない申請者を断る	保留中の参加申請を却下する
接続アカウント自身がグループを離れる	グループ退出
自分のアプリで行を非表示にするだけ	ローカルの表示変更。メンバー変更ではない

権限解除は管理者ロール変更ガイド、未参加の申請者は参加申請の承認キューを参照してください。これらに共通の曖昧な「削除」ボタンを使わないようにします。

削除確認画面に必要な情報

削除ボタンを有効にする前に、選択したアカウントで会話メンバー一覧を取得します。グループ ID を conversation_id に指定し、type=group を渡します。必要な確認が終わるまで data.has_more と data.next_cursor に従ってページを取得してください。最初のページにいないことは、不在の証明ではありません。

返された peer_id、display_name、role を保持します。ロールは member、admin、superadmin で、最後は所有者または作成者です。表示名は人が対象を認識するための情報であり、識別子ではありません。

次はアプリ側の推奨安全策であり、追加の API 要件ではありません。

• 確認時に接続アカウント、対象グループ、メンバーを一緒に表示する。
• アプリ内の操作者権限と、接続アカウントのグループ管理権限を確認する。API キーの保有だけではグループ権限は証明できない。
• superadmin、接続アカウント自身、身元未確認の対象を通常のメンバー削除から除外し、別の審査や適切な操作へ回す。
• 古い選択情報を再照会し、同じアカウント・グループ・メンバーに対する削除の同時送信をバックエンドで防ぐ。

対象を返却された WhatsApp LID に対応付けられなければ停止します。電話番号、表示名、異なる形式のイベント参加者 ID で代用しないでください。

確認した 1 人に 1 リクエスト

グループメンバー管理リファレンスが受け付けるのは単数の member_id です。参加申請の判断に使う member_ids 配列ではありません。UnifyPort は非公式インターフェースを提供します。現在のプロバイダー別アクション表では、この操作は whatsapp のみが対象です。LINE、Telegram、whatsapp-protocol に同じ操作を展開しないでください。

次の JavaScript はリクエスト本文の構築例です。確認済みのグループ ID と、一覧で選択したメンバーレコードを渡します。権限確認やネットワーク送信は実装していません。

function removalBody(groupId, selectedMember) {
  if (!groupId || !/^\d+@lid$/.test(selectedMember?.peer_id ?? '')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  if (!['member', 'admin'].includes(selectedMember.role)) {
    throw new Error('This target requires separate review');
  }
  return {
    group_id: groupId,
    action: 'remove',
    member_id: selectedMember.peer_id
  };
}

ロールの制限はローカルの安全方針です。LID の形式チェックは身元や権限を保証しません。バックエンドから前述のエンドポイントへ JSON を送り、X-Api-Key と Content-Type: application/json を指定します。キーをブラウザーやログに出さないでください。複数人を一括削除するトランザクションは文書化されていないため、一括操作画面を用意しても各対象の結果を個別に追跡します。

画面の動きではなく証拠で判断する

操作者の意図、HTTP 結果、観測したメンバー状態を分離します。

得られた証拠	アプリが示せる内容
200 OK と data.ok: true	API が成功を返した。メンバーを再取得する
正常に完了した一覧取得で対象 LID が見つからない	その取得時には対象を観測しなかった。取得時刻を記録する
一覧取得が失敗、または未完了	検証は未解決
変更リクエストのタイムアウト、読み取れないレスポンス	結果不明。次の書き込み前に調査する

文書化された group.updated イベントには、data.changes[] の kind: "member_removed" と members[] が含まれる場合があります。再照会のきっかけとして使い、各リクエストに必ず対応する受領証とは扱わないでください。配信仕様に従って署名を検証してからイベントを信頼します。イベント参加者 ID をそのまま次のメンバー管理リクエストに使えるとも限りません。

request_id があれば調査用に保存しますが、冪等性キーにはしません。結果不明なら現在のメンバーを確認し、再変更には改めて承認を求めます。補償として自動的に add を送ることは、新たな参加判断であり、保証されたロールバックではありません。

FAQ

グループ作成時の電話番号を使えますか？

使えません。この操作では一覧の peer_id が返す WhatsApp LID を使います。グループ作成時の初期メンバー指定は別の契約です。

保存済みメッセージの削除や、永久的な再参加禁止もできますか？

この API からそのような保証を導かないでください。対象はメンバー管理であり、履歴消去や恒久的な参加制限ではありません。データ保持と今後の参加判断は別途管理します。

本番導入前に何をテストすべきですか？

管理下のアカウントで、同名の参加者、後続ページにいる対象、古い選択、権限不足、レスポンス喪失、再照会失敗を確認します。これは推奨テストであり、実施済みの結果ではありません。

次のステップと出典

会話メンバー一覧に基づいて対象確認を実装し、その後に削除ボタンをグループメンバー管理へ接続してください。

参照確認日：2026-11-01。

• WhatsApp：グループメンバーの追加と削除
• UnifyPort：グループメンバー管理
• UnifyPort：グループ更新イベント