用 API 更改 WhatsApp 群組管理員：提升與撤銷權限

要透過 UnifyPort 更改 WhatsApp 群組管理員，可呼叫 POST /v1/accounts/{account_id}/groups/members，傳入 group_id、以成員 LID 為值的 member_id，以及 action: "promote" 或 "demote"。每次請求只處理一名成員及一個動作。撤銷管理員權限不等於 remove 移出群組。請先讀取目前成員狀態，並將群組建立者排除在一般降級流程之外。

重點

• 同時選定訊息帳戶、群組及成員，不能以顯示名稱代替識別碼。
• 使用成員清單返回的 peer_id 中的 LID，不要以電話號碼拼接。
• 啟用按鈕前先區分 member、admin 及 superadmin。
• 請求後重新讀取狀態；逾時後不要自動執行相反動作。

先確定要更改甚麼角色

WhatsApp 的官方群組管理員說明介紹了撤銷管理員的方法，並指出群組建立者不能被移除，除非自行退出，否則會保留管理員身份。接入 API 不會改變這項規則。

以下是建議的應用程式策略，不是平台一定接受請求的保證：

目前角色	操作意圖	應用程式處理方式
member	設為管理員	檢查權限後提供 promote
admin	保留成員身份，撤銷管理權限	確認後提供 demote
superadmin	撤銷建立者權限	停止流程並解釋限制
已是目標角色	重複同一變更	更新畫面，不再發送請求
成員資料缺失、未知或不完整	仍然更改角色	重新讀取或交由人手核實

這不是入群審批流程。決定某人是否可以加入群組，請用 WhatsApp 入群申請審批隊列；需要分享邀請，則使用獨立的群組邀請連結流程。兩者都不會委任管理員。

保留目前選取的成員資料

在選定訊息帳戶下呼叫列出會話成員，傳入群組的 conversation_id，按 cursor 分頁，並保留選中項目的 peer_id 及 role。文件列出的角色是 member、admin、superadmin，最後一項代表群組擁有者或建立者。

以下讀取請求僅作示範；環境變數應由後端按照實際選取資料填入：

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

如 data.has_more 為真，使用返回的 data.next_cursor 繼續讀取。第一頁沒有某名成員，不能證明對方已退出。LID 必須原樣保留，不要從電話號碼、顯示名稱或不同格式的事件成員 ID 推算。

發送前，確認操作員有權管理這個帳戶及群組，亦要確認已連接的 WhatsApp 帳戶具有所需群組權限。工作空間 API 存取權不等於群組管理員權限。API Key 必須保留在伺服器端。

每次提交一個明確動作

管理群組成員文件列出 add、remove、promote、demote 四種動作。角色變更只使用後兩項，並傳入單數 member_id，不是入群審批介面的 member_ids 陣列。

以下 JavaScript 只從已選成員紀錄建立請求內容，不進行權限驗證，亦不發送網絡請求：

function roleChangeBody(groupId, selectedMember, action) {
  const expectedRole = { promote: 'member', demote: 'admin' };
  if (!Object.hasOwn(expectedRole, action) ||
      selectedMember?.role !== expectedRole[action]) {
    throw new Error('Refresh membership before changing this role');
  }
  if (!groupId || !selectedMember?.peer_id?.endsWith('@lid')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  return {
    group_id: groupId,
    member_id: selectedMember.peer_id,
    action
  };
}

後端以 X-Api-Key 將 JSON 發送至文件指定端點。字尾檢查只是本地防誤用措施，不代表已證明身份或權限。確認畫面應清楚顯示群組、成員及預定動作，不能從不斷變動清單的第一列推斷操作對象。

UnifyPort 為已連接帳戶提供非官方介面。目前渠道動作支援矩陣只將這項寫入操作對應至 whatsapp，不包括 LINE、Telegram 或獨立的 whatsapp-protocol。能讀取某渠道的成員或接收群組事件，不代表能更改其角色。

核對結果，不假設操作具備交易保證

端點文件的成功回應是 200 OK 及 data.ok: true。保存 HTTP 結果及 request_id，再讀取成員資料，將實際觀察到的角色與操作員意圖分開顯示。

建議採取以下保護措施：

1. 對同一帳戶、群組及成員的應用程式內變更依次處理。
2. 發送前再核對角色；確認視窗開啟後，其他管理員可能已作修改。
3. 逾時後將結果標記為待核實，再讀取目前成員資料。不要自動重發，也不要以相反動作補償。
4. 不要將多人交接視為原子交易。交接職責時，先確認新管理員的實際角色，再獨立考慮是否撤銷另一人的權限。

標準 group.updated 事件的 data.changes[] 可包含 kind: "promoted" 或 "demoted" 及 members[]。可以用它觸發重新核對，但不能視為每個請求必定產生的回執。事件成員 ID 不一定能直接用作下一次寫入所需的 LID。處理 webhook 時請遵循簽署及傳遞文件，先驗證再信任內容，並處理重複及次序不一致的傳遞。

常見問題

demote 會將成員移出群組嗎？

不會。角色降級與移除成員是不同動作。「撤銷管理員」按鈕不可呼叫 remove。

可以更改群組建立者的角色嗎？

不要在此流程提供該操作。WhatsApp 說明建立者除非自行退出，否則保留管理員身份；UnifyPort 成員清單以 superadmin 表示這個角色。

一次請求可以更改多名管理員嗎？

此端點不可以。每次只接受一個 member_id 及一個動作。應用程式批次操作必須分別記錄每項結果。

下一步與參考資料

先實作列出會話成員，再按照管理群組成員加入角色控制。正式啟用前，測試分頁、建立者目標、過期角色選取、權限不足及網絡結果不明等情況。這些是建議測試項目，不是已完成的測試結果。

資料核對日期：2026-10-17。

• WhatsApp：管理群組管理員
• UnifyPort：管理群組成員
• UnifyPort：標準 webhook 事件