透過 API 退出 WhatsApp 群組：安全操作流程

要透過 UnifyPort 讓已連線的 WhatsApp 帳號退出群組，請呼叫 POST /v1/accounts/{account_id}/groups/leave，並在 JSON 本文傳入 group_id。這會變更所選帳號的群組成員資格，不是替所有人刪除群組，也不會清空客服資料庫。送出前，請確認目標，並停止應用程式中針對該群組的待發回覆。

重點整理

• 訊息帳號與群組必須一起選定；群組名稱不是唯一識別碼。
• 退群、移除其他成員、靜音通知與清理儲存的訊息是不同操作。
• 目前 UnifyPort 退群操作僅支援 whatsapp，不能從群組讀取能力推論寫入能力。
• 逾時代表結果尚未確認；先觀察目前狀態，再決定是否重新請求。

先確認真正需要的是退群

WhatsApp 的官方退出與刪除說明區分了保留聊天紀錄的 Exit group，以及從本機移除紀錄的 Exit and delete for me。不要將兩者合併成模糊的「移除」按鈕。如果群組隸屬社群，操作前應查看成員退出說明，另外評估社群相關影響。

操作者的目的	適合的流程
讓已連線帳號停止參與群組	明確的退群操作
減少通知干擾	靜音通知
保留成員資格但停止自動回覆	應用程式自行管理的暫停控制
變更其他成員的管理員角色	獨立的角色變更
刪除客服系統儲存的內容	自訂資料保留與刪除流程

通知設定可參考共用收件匣的靜音與封鎖差異。若群組仍需要管理員，先依管理員升級與降級指南完成職責交接，再確認是否退出。交接與資料清理都不是退群請求的一部分。

確認前固定帳號與群組

對所選帳號使用列出群組。此介面列出已加入的群組，包括未曾傳送訊息的群組；回傳 id、conversation_id 與 name，群組的 conversation_id 等於 id。請依 has_more 與 next_cursor 逐頁讀取，不要只查看第一頁。

完整保留回傳的 ID。在確認視窗同時顯示帳號身分與群組名稱，並在伺服器端保留對應 ID。不同帳號中的同名群組不能共用同一個操作目標。

建議加入以下應用程式控制：

1. 要求有權限的操作者確認這次具體退群。
2. 暫停此帳號與群組組合的新自動發送，檢查佇列中及正在送出的工作。
3. 保持簽章 webhook 接收器運作；暫停發送不需要停用接收與儲存。
4. 在自己的稽核紀錄保存操作者、目標與原因，不要將它們當成 API 欄位傳入。

這些是應用程式防護建議，不是端點額外保證的行為。

送出一次退群請求

UnifyPort 提供非官方介面。退出群組參考文件記載以下請求，以及包含 data.ok: true 的 200 OK 成功回應。渠道動作矩陣僅將此動作對應到 whatsapp，不包括 LINE、Telegram 或獨立的 whatsapp-protocol 渠道。

以下為伺服器端 JavaScript 範例。環境變數應取自已確認的目標與機密儲存空間。範例只呼叫一次，不自動重試：

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 事件，也不要承諾每次退群都有回呼。

常見問題

這會替所有人刪除群組嗎？

不會。文件中的動作讓已連線帳號退出，不是解散群組或刪除資料庫的 API。

能用移除成員操作讓自己退群嗎？

已連線帳號應使用專用退群動作。管理其他成員是不同請求，輸入也不同。

能列出 LINE 群組，就能透過此 API 退出嗎？

不能。讀取與寫入支援不同，應查看動作矩陣，而非只看群組是否出現在清單中。

下一步與來源

依退出群組參考文件實作。開放控制前，使用自己管理的帳號測試選錯帳號、分頁、重複點擊、佇列回覆及不確定的網路結果。這些是建議測試，不是已完成的測試結果。

來源核對日期：2026-10-22。

• WhatsApp：管理員退出與刪除群組
• WhatsApp：成員退出群組
• UnifyPort：退出群組
• UnifyPort：渠道動作支援