透過 API 建立 WhatsApp 群組：確認群組 ID 與初始成員

透過 UnifyPort 建立 WhatsApp 群組時，呼叫 POST /v1/accounts/{account_id}/groups/create，傳入必要的 name 與選填的 members 陣列。在這個建立請求中，WhatsApp 初始成員使用電話號碼識別。成功回應會傳回 data.id，而非成員加入明細。請立即儲存群組 ID，再讀取群組資料與成員清單，最後才啟動依賴這些結果的自動化。

重點整理

• 建立群組、邀請他人與管理既有成員是不同操作。
• 初始 members 使用電話號碼，後續成員管理採用另一套識別碼契約。
• 公開事件目錄沒有 group.created，不要等待這個回呼來結束流程。
• 未收到回應代表結果不確定；自動重試建立可能產生另一個群組。

先讀建立契約，再設計表單

建立群組參考文件定義了以下契約。UnifyPort 為已連線的訊息帳號提供非官方介面，此處不是 WhatsApp Cloud API 端點。渠道操作支援表目前僅將建立群組對應到 whatsapp，不包括 LINE、Telegram 或獨立的 whatsapp-protocol 渠道。

值	意義	不可用來替代的值
路徑中的 account_id	執行建立的訊息帳號	工作區 ID
請求中的 name	必填群組名稱，最多 100 個字元	唯一資源識別碼
請求中的 members	選填初始成員；WhatsApp 使用電話號碼	直接複製的成員 LID 陣列
回應中的 data.id	新建立的群組 ID	邀請碼或操作 ID

建立回應的 data 只包含新群組 ID，沒有逐人加入結果。應分別儲存「預期的初始成員」與「後續實際觀察到的成員」。

WhatsApp 的官方成員管理說明分別介紹新增成員、邀請成員，以及啟用審核後查看待處理申請。這些使用者流程不能互相替代，也不能全部視為「已加入」的證據。如果希望使用者自行決定是否進入既有群組，應使用邀請連結流程，而非再建立一個群組。

準備一次經過確認的建立請求

依照帳號生命週期參考文件，先確認所選訊息帳號已授權，且執行狀態為 running。API Key 只存於後端，操作人員的權限也要在後端檢查。

建議應用程式採用以下防護：

1. 確認畫面顯示所選帳號、預定名稱與參與者。只加入知情且預期參與的人。
2. 送出前儲存本地建立意圖。操作人員與預期參數記錄在自己的應用程式，不要作為額外 API 欄位傳送。
3. 後端阻止同一意圖同時送出多次；僅停用瀏覽器按鈕並不足夠。
4. 只送出一次請求，先保存結果，再開放後續操作。

以下伺服器端 JavaScript 根據已確認的輸入組成請求。本範例未在此執行，也不含自動重試：

async function createGroupOnce({ apiKey, accountId, name, phones }) {
  if (!apiKey || !accountId || typeof name !== 'string' || !name.trim()) {
    throw new Error('Missing credential, account, or group name');
  }
  const body = { name };
  if (phones !== undefined) {
    if (!Array.isArray(phones) ||
        phones.some(p => typeof p !== 'string' || !/^[0-9]+$/.test(p))) {
      throw new Error('Use confirmed phone-number strings');
    }
    body.members = phones;
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/create`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

請依文件格式使用實際確認過的電話號碼。數字檢查只是本地輸入防護，不代表號碼對應的使用者一定能加入。也需驗證文件規定的名稱長度。正式環境的程式必須處理網路例外與非 JSON 回應，在可用時安全保存 request_id，並避免將憑證或參與者電話清單寫入日誌。

將群組 ID 與成員驗證分開

收到 200 OK 且有 data.id 後，將回傳 ID 與所選帳號、本地建立意圖一起持久化。接著呼叫取得群組，以該 ID 作為 group_id。

查看參與者時，使用列出對話成員，將群組 ID 作為 conversation_id，並設定 type=group。依 has_more 與 next_cursor 完成分頁；某人未出現在第一頁，不代表成員核對已完成。原樣保留回傳的 peer_id 與 role，不要從電話號碼推算 LID。

後續管理群組成員採用不同契約：每次請求只有單一 member_id 與一個動作，WhatsApp 使用成員清單以 peer_id 傳回的 LID。不要直接重用建立請求。若下一步是指定管理員，請參考管理員角色調整指南。

觀察結果	建議的應用程式狀態	下一步
成功回應且已保存群組 ID	已建立，成員尚未驗證	讀取群組資料及所有成員分頁
群組可讀取，但預期成員尚未核清	群組存在，成員待確認	檢查身分對應或於原生應用程式核對
逾時、回應無法解析或缺少預期 ID	建立結果未確定	先查核，再考慮重新建立

這些是應用程式內部狀態，不是額外的 API 回應值。

復原時避免重複建立群組

標準事件目錄不包含 group.created，建立成功不保證有這個回呼。group.updated 也不是每次建立請求必定收到的回執。

若回應遺失，在相同帳號下檢查群組清單，並完成分頁。清單包括尚未傳送訊息的已加入群組。結合可用資料與原生應用程式調查；名稱相同不足以證明是同一群組，讀取失敗或分頁不完整也不足以證明建立失敗。

公開建立契約未記載冪等鍵。本地意圖紀錄可減少應用程式自己的重複送出，但無法保證上游操作恰好執行一次。結果未明時，暫停相關邀請與自動訊息；再次建立前，要求操作人員複核。

常見問題

可以省略 members 嗎？

可以，API 將 members 定義為選填。不過這只是請求結構的屬性，並非保證每個上游帳號的行為，仍須確認實際結果。

HTTP 成功是否代表所有人都已加入？

不是。文件定義的結果是群組 ID，不是逐人成員結果。請獨立讀取成員清單。

建立時能一起傳群組說明與頭像嗎？

它們不是文件中的建立欄位。建立後使用獨立的群組資料編輯流程。

下一步與參考資料

依建立群組參考文件實作。正式啟用前，以自己控制的帳號測試重複點擊、回應遺失、同名群組、成員分頁與無法加入的參與者。這些是建議測試項目，不是已完成的測試結果。

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

• WhatsApp：新增與移除群組成員
• UnifyPort：建立群組
• UnifyPort：列出對話成員
• UnifyPort：標準事件