透過 API 更改 WhatsApp 群組名稱、描述及頭像

透過 UnifyPort 更改 WhatsApp 群組名稱、描述或頭像，可呼叫 POST /v1/accounts/{account_id}/groups/update-info，提交 group_id，以及 name、description、avatar_url 中至少一個欄位。此端點要求群組管理員權限。只傳送操作人員打算更改的欄位，之後重新讀取群組資料；不要把開啟編輯器時的舊快照當成現時狀態。

重點

• 群組資料不是 CRM 內的私人標籤，儲存前要說明更改範圍。
• 編輯期間固定已選訊息帳戶及群組 ID。
• 只提交明確的修改，不要將整份查詢回應直接寫回。
• 逐欄核對結果；逾時或沒有收到 webhook 都不代表沒有更改。

先選欄位，不要混用設定操作

WhatsApp 的群組資料修改說明介紹了原生應用程式的編輯方式。群組管理員設定說明亦介紹允許成員編輯群組設定的權限。不過，原生設定不會擴大 UnifyPort 的契約：更新群組資料文件明確要求管理員權限。

更改目的	請求欄位	應分開處理
更改群組名稱	name	收件箱內的私人別名
更改群組描述	description	客服工單或訊息內容
更換群組頭像	avatar_url	成員的個人頭像

更改成員角色請使用群組管理員提升及降級流程；分享邀請則使用群組邀請連結流程。這些操作不應混入群組資料表單。

UnifyPort 提供的是非官方介面。渠道操作矩陣將此寫入操作對應至 whatsapp，不包括 LINE、Telegram 或獨立的 whatsapp-protocol。能夠讀取群組資料或接收群組事件，不代表能夠修改群組資料。

用最新讀取結果建立編輯器

先在目標訊息帳戶下透過列出群組選擇群組，並處理分頁。保留傳回的 id；群組的 conversation_id 與 id 相同。名稱只是顯示值，不是唯一識別碼。

再使用取得群組資料讀取現時內容。在應用程式中分開保存：

1. 最近觀察到的值。
2. 操作人員實際編輯的欄位。
3. 提交後重新觀察到的值。

如果只改描述，就不要連同舊名稱及舊頭像一起傳送。若重新讀取發現別人已修改正在編輯的欄位，應要求操作人員重新確認。這是應用程式層面的保障，不是伺服器端版本檢查。

確認畫面應顯示訊息帳戶、群組及已更改欄位。API key 保留在後端，操作人員權限亦由後端檢查。

只提交預期的群組更改

以下 JavaScript 示範後端單次請求。傳入實際選取的識別碼和伺服器保存的 API key。範例刻意只支援非空替換，不定義清空欄位或移除頭像的行為。

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

edits 只包含已編輯欄位。頭像需要公開可存取的圖片 URL：使用你可控制並有權公開的圖片，不要提交本機檔案路徑或需要瀏覽器登入的頁面。這是以 URL 為輸入的請求，不是圖片上載端點。

文件定義的成功回應是 200 OK 且 data.ok: true，顯示成功前要同時檢查。正式程式還要處理網絡錯誤及非 JSON 回應，保留可取得的 request_id，避免記錄憑證。本範例未在此實際執行。

逐欄核對，不要重送整份表單

請求後重新讀取同一群組，比較名稱及描述的提交值與觀察值。頭像應檢查傳回的圖片或原生應用程式，不要要求傳回 URL 必須等於提交的來源 URL；契約沒有保證網址相同。

標準事件文件說明，group.updated 的 data.changes[] 可以包含多個項目：

• renamed 帶有 name。
• description_changed 帶有 description。
• WhatsApp 的 avatar_changed 帶有 removed 及可選的 picture_id，沒有圖片 URL。

把事件當作核對訊號，而不是每次請求必有的回執。按照webhook 傳送契約驗證簽署、處理重複及次序不一致的事件，不要因為事件省略欄位就清空其他資料。

逾時後將結果標記為未確認，先檢查現時狀態，再決定還有哪些欄位需要修改。不要自動重送舊的多欄位表單，也不要直接還原舊快照。公開文件未提供多欄位原子還原或版本前置條件。上游權限拒絕會顯示為 update_group_info_failed；仍要檢查錯誤詳情，不能假設此錯誤只有一種原因。

常見問題

可否用空值清除描述或移除頭像？

本流程不作此假設。引用的端點未說明清除慣例；確認操作契約前，不應開放相關按鈕。

能讀取群組資料，就一定能編輯嗎？

不一定。讀取權限、渠道操作支援及群組管理員權限是三項獨立檢查。

必須提交全部三個欄位嗎？

不用。提交 group_id 及至少一個支援的編輯欄位即可。表單未修改時不應發出寫入請求。

下一步及參考資料

按照更新群組資料文件實作。啟用前測試只改名稱、未編輯表單、原生端同時修改、圖片無法存取、權限拒絕及逾時。這些是建議測試，不是已完成的結果。

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

• WhatsApp：修改群組資料
• WhatsApp：修改群組管理員設定
• UnifyPort：更新群組資料
• UnifyPort：標準事件