WhatsApp 入群審核：透過 API 開啟或關閉

透過 UnifyPort 開啟或關閉 WhatsApp 入群審核，請呼叫 POST /v1/accounts/{account_id}/groups/join-approval-mode，提交 group_id 和必填布林值 enabled。true 表示需要審核，false 表示關閉這項要求。這是在變更群組設定，不是對待處理申請執行「全部核准」或「全部拒絕」。

重點整理

• 把開關視為明確的管理操作，不要在開啟審核清單時順便修改。
• 必須傳送 JSON 布林值，不能使用字串 "false"、遺漏的核取方塊值或自行設計的切換動作。
• 目前操作支援 whatsapp，不適用於獨立的 whatsapp-protocol 或其他管道。
• 分別記錄預期設定、API 回傳結果及後續驗證。

先區分群組設定與審核動作

Meta 的 WhatsApp 群組管理官方說明介紹了管理員在分享邀請連結或開放社群成員加入群組時，控制誰能加入的能力。平台設定與審核申請人的軟體屬於不同層次。

操作目的	對應操作
新加入者需要審核	設定 enabled: true
關閉入群審核要求	設定 enabled: false
核准或拒絕指定申請人	使用獨立的入群申請更新操作
取得邀請網址	使用邀請連結讀取操作

逐一審核請參考 WhatsApp 入群申請審核佇列；分發邀請請參考邀請連結讀取與重設的差異。這兩種流程都不應默默改變群組的加入規則。

設計明確的開啟與關閉表單

審核模式 API 文件要求提交 group_id 和布林值 enabled。管道動作矩陣將該操作限定為 WhatsApp。UnifyPort 使用已連線訊息帳號的非官方介面；這不是 WhatsApp Cloud API 請求。

同時選取帳號與群組，透過列出群組取得群組 ID，不要只靠名稱判斷目標。確認已連線身分具有群組管理員權限，並在自己的應用程式中驗證操作者是否有權修改加入規則。持有工作區 API Key 不等於具有群組管理員權限。

建議表單遵循以下規則：

1. 在確認畫面顯示所選帳號與群組。
2. 要求明確選擇開啟或關閉審核。
3. 目前設定未知時顯示「未知」，不能把缺少資訊當成「關閉」。
4. 僅在操作者確認後提交，不在頁面載入或清單重新整理時寫入。
5. 驗證與序列化時保留 false；簡單的真值判斷可能丟掉關閉操作。

公開的群組讀取範例沒有定義審核模式欄位。不要自行增加回應屬性來預填表單。沒有文件支持的回讀功能時，請授權管理員在 WhatsApp 內查看設定，並把應用程式儲存的值標示為「上次請求的設定」，而非目前狀態。

提交一次確認過的變更

以下伺服器端 JavaScript 範例使用真實請求欄位，未在此執行，也不包含自動重試：

export async function setJoinApproval({ apiKey, accountId, groupId, enabled }) {
  if (!apiKey || !accountId || !groupId || typeof enabled !== 'boolean') {
    throw new Error('Account, group, credential and boolean choice required');
  }

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/join-approval-mode`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ group_id: groupId, enabled })
    }
  );
  const requestId = response.headers.get('X-Request-Id');
  const body = await response.json();
  return { httpStatus: response.status, requestId, body };
}

API Key 必須留在後端。回傳物件中的 httpStatus、requestId 與 body 是應用程式變數，不是新增的 API 回應欄位。文件中的成功回應為 200 OK，包含 data.ok: true。先儲存目標布林值與結果，再顯示成功。呼叫端必須處理網路與 JSON 解析錯誤；沒有收到回應時應保持「結果未確認」，而非「已關閉」。

在應用程式內依帳號與群組循序處理修改。如果先有人要求開啟，另一人稍後要求關閉，舊請求的延遲重試可能恢復過時的選擇。本機鎖定或版本檢查是應用程式防護，不是上游提供的條件寫入功能；管理員仍可在原生應用程式獨立修改。

分別驗證設定與待處理申請

待處理清單為空不能證明審核已關閉，也可能只是沒有人等待。group.join_request 是申請訊號，不是設定變更的回執。公開事件契約沒有承諾專門確認審核模式的回呼。

開啟後，請授權管理員檢查設定，並在廣泛分發連結前進行受控邀請測試。審核流程繼續輪詢列出入群申請；文件明確說明推送訊號是盡力交付。

關閉前先檢查未處理申請，並指定之後負責核對的人員。審核模式契約沒有說明關閉對既有待審申請的影響。不要聲稱關閉會核准所有人、拒絕所有人、移除現有成員或重設邀請連結。針對個別申請人的決定應使用獨立審核操作。

請求逾時後，保留目標值與診斷紀錄，檢查原生設定，再要求重新確認是否提交。不要自動傳送相反值當作還原：其他管理員可能已變更規則。

常見問題

可以省略 enabled，表示保持不變嗎？

不行。此操作要求布林值。不需修改時就不要呼叫。

enabled=false 會拒絕所有等待者嗎？

文件沒有這項承諾。關閉設定與處理既有申請是不同任務。

審核背景工作可以每次輪詢都開啟審核嗎？

不建議。輪詢是讀取，加入規則設定是管理寫入。分開處理，才能避免背景工作撤銷管理員的主動選擇。

Telegram 或 LINE 可以使用此操作嗎？

目前 UnifyPort 動作矩陣未支援。相同的路由格式不代表所有管道都具備該能力。

下一步與參考資料

依據設定入群審核模式實作表單。建議測試兩種布林值、拒絕字串輸入、初始狀態未知、相反選擇同時提交及回應遺失。這些是建議的驗收項目，不是已執行的測試結果。

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

• Meta：WhatsApp 群組管理功能說明
• UnifyPort：設定入群審核模式
• UnifyPort：管道動作支援
• UnifyPort：列出入群申請