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