APIでWhatsAppグループを退出する：安全な実装手順
UnifyPortで接続済みのWhatsAppアカウントをグループから退出させるには、POST /v1/accounts/{account_id}/groups/leave を呼び出し、JSON本文に group_id を渡します。これは選択したアカウントの参加状態を変更する操作であり、全員のグループや自社のサポートデータベースを削除するものではありません。送信前に対象を確認し、そのグループへの自動返信キューを停止してください。
要点
- メッセージングアカウントとグループをセットで選択します。グループ名だけでは対象を特定できません。
- 退出、他のメンバーの削除、通知のミュート、保存済みメッセージの削除は別の操作です。
- 現在の退出操作は
whatsappのみ対応です。グループ一覧を取得できることと、退出できることは同義ではありません。 - タイムアウト時は結果不明として扱い、現状を確認してから次のリクエストを判断します。
本当に退出が必要かを確認する
WhatsAppの公式の退出・削除ガイドは、履歴を残す Exit group と、ローカルの履歴も消す Exit and delete for me を区別しています。曖昧な「削除」ボタンにまとめないでください。コミュニティに属するグループでは、メンバー向け退出ガイドを確認し、コミュニティへの影響を別途検討します。
| 担当者の目的 | 適切な操作 |
|---|---|
| 接続済みアカウントの参加を終了する | 明示的なグループ退出 |
| 通知を減らす | 通知のミュート |
| 参加は継続し、自動返信だけ止める | アプリ側の一時停止 |
| 他のメンバーの管理者権限を変更する | 独立したロール変更 |
| 保存したサポートデータを削除する | 自社の保存・削除ポリシーに従う処理 |
通知の判断には共有受信箱のミュートとブロックの違いを参照してください。管理者の引き継ぎが必要なら、管理者の昇格・降格ガイドに沿って別途対応し、その後で退出を判断します。引き継ぎや履歴削除は退出リクエストに含まれません。
確認画面を開く前に対象を固定する
選択したアカウントでグループ一覧の取得を行います。このAPIはメッセージを送ったことのないグループも含め、参加中のグループを返します。項目には id、conversation_id、name があり、グループでは conversation_id と id が一致します。最初のページだけで判断せず、has_more と next_cursor に従って取得してください。
返されたIDは変更せず保存します。確認画面にはアカウントの識別情報とグループ名を両方表示し、対応するIDはサーバー側で保持します。別アカウントにある同名グループを同じ操作対象にしてはいけません。
推奨するアプリ側の制御は次のとおりです。
- 権限を持つ担当者に、今回の具体的な退出を確認してもらう。
- このアカウントとグループの組み合わせへの新規自動送信を止め、待機中・送信中のジョブを点検する。
- 署名付きwebhookの受信は継続する。送信を止めるために受信データの保存を止める必要はない。
- 担当者、対象、理由を自社の監査記録に残す。APIに存在しないフィールドとして送らない。
これはアプリの安全策であり、エンドポイントが追加で保証する機能ではありません。
退出リクエストを一度送る
UnifyPortは非公式インターフェースです。グループ退出リファレンスは、以下のリクエストと、data.ok: true を含む 200 OK の成功応答を定義しています。プロバイダー別アクション対応表では、この操作は whatsapp のみです。LINEやTelegram、別プロバイダーの whatsapp-protocol は含まれません。LINEとWhatsAppを同じ受信箱にまとめても、この操作の対応範囲は変わりません。
次はサーバー側JavaScriptの例です。環境変数には確認済みの選択と安全に管理されたAPIキーを設定します。自動再試行は行いません。
const accountId = process.env.UNIFYPORT_ACCOUNT_ID;
const groupId = process.env.WHATSAPP_GROUP_ID;
const apiKey = process.env.UNIFYPORT_API_KEY;
if (!accountId || !groupId || !apiKey) {
throw new Error('Missing confirmed target or credential');
}
const response = await fetch(
`https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/leave`,
{
method: 'POST',
headers: {
'X-Api-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({ group_id: groupId })
}
);
const outcome = await response.json();
if (!response.ok || outcome.data?.ok !== true) {
throw new Error('Exit not confirmed; review the response');
}本番ではHTTPステータスと request_id を安全に保存し、通信・解析エラーを処理してください。実行前の担当者の権限確認も必要です。応答が得られないことは、WhatsAppが操作を拒否した証拠ではありません。
退出の確認とデータ削除を分離する
成功後は、参加中のグループ一覧を更新します。タイムアウト後は結果不明のまま現在の参加状態を確認し、APIの読み取りで判断できない場合は公式アプリでも確認します。読み取りエラーや不完全なページは退出の証拠ではありません。補償処理として自動で再参加したり、同じリクエストを再送したりしないでください。
担当者が解決するまでは返信ジョブの停止を維持します。遅れて届いたイベントによって送信を自動再開させてはいけません。退出してもアプリが保存済みのメッセージは消えないため、保存ポリシーは別途適用します。
グループイベントを状態確認のきっかけにする場合は、webhook配信仕様に沿って署名検証と重複処理を実装します。仕様にない group.left イベントに依存したり、退出ごとのコールバックを保証したりしないでください。
FAQ
全員に対してグループを削除しますか？
いいえ。接続済みアカウントを退出させる操作です。グループ解散やデータベース削除のAPIではありません。
メンバー削除で自分を退出させられますか？
接続済みアカウントには専用の退出操作を使用してください。他のメンバーの管理は別のリクエストで、入力も異なります。
LINEのグループを一覧表示できれば、このAPIで退出できますか？
いいえ。読み取りと書き込みの対応範囲は異なります。一覧への表示だけでなく、アクション対応表を確認してください。
次のステップと出典
グループ退出リファレンスに沿って実装してください。公開前に、自分で管理するアカウントで誤ったアカウントの選択、ページ分割、二重クリック、返信キュー、通信結果不明のケースを確認します。これらは推奨テストであり、実施済みの結果ではありません。
確認日：2026-10-22。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。