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：列出入群申請