透過 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 事件