用 API 移除 WhatsApp 群組成員：識別碼與結果核實

透過 UnifyPort 移除現有 WhatsApp 群組成員，應呼叫 POST /v1/accounts/{account_id}/groups/members，傳入 group_id、action: "remove"，以及放在 member_id 的成員 LID。LID 應取自群組成員列表傳回的 peer_id。每次請求只針對一個人。儲存回應後重新讀取成員狀態，不要將介面中一行消失視為移除成功。

重點

• 移除成員、取消管理員身份、拒絕待批申請，以及連線帳戶自行退出群組，是不同操作。
• 一併確認訊息帳戶、群組和成員，不要用電話號碼拼出 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 Key 不等於擁有群組管理權限。
• 將 superadmin、連線帳戶本身及身份未明的對象排除於一般成員移除流程，交由獨立審核或使用對應操作。
• 重新讀取過時的選取資料，並在後端阻止同一帳戶、群組、成員的並行移除請求。

無法將目標對應至傳回的 WhatsApp LID 時，請停止操作。不要改用電話號碼、顯示名稱，或其他格式的事件參與者識別碼。

一位已確認的成員，一次請求

管理群組成員參考文件接受單數 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[]。將它視為重新核對狀態的提示，不要當作每個請求必定產生的回執。信任事件前，按投遞規格驗證簽署。事件參與者識別碼亦不一定能直接用於下一次成員管理請求。

有 request_id 時請保存以便排查，但不要當作冪等鍵。結果不明時先檢查目前成員狀態，再次變更前要求重新審核。自動傳送 add 作為補償，是新的成員管理決定，不是保證有效的還原。

常見問題

可以使用建立群組時的電話號碼嗎？

不可以。此操作要求成員列表 peer_id 傳回的 WhatsApp LID；建立群組的初始成員識別碼採用不同規格。

移除是否會刪除已儲存訊息，或永久阻止再次加入？

不要根據這個 API 作出上述承諾。它管理成員，不是歷史資料刪除或永久准入政策。資料保留及日後加入決策應另外處理。

上線前應測試甚麼？

使用受控帳戶測試重名、目標位於後續分頁、選取資料過時、權限不足、回應遺失及核實讀取失敗。這些是建議測試，不是已執行結果。

下一步與參考資料

先依列出對話成員實作確認選取，再將具破壞性的操作接駁至管理群組成員。

資料核對日期：2026-11-01。

• WhatsApp：新增及移除群組成員
• UnifyPort：管理群組成員
• UnifyPort：群組更新事件