透過 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：渠道動作支援