用 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：標準事件