WhatsApp 聯絡人備註：設定或清除私人顯示名稱

透過 UnifyPort 為 WhatsApp 聯絡人設定私人顯示名稱，請呼叫 POST /v1/accounts/{account_id}/contacts/note，提交 contact_id 與字串 note。清除時明確傳入 note: ""。這會修改帳號端的聯絡人備註，不是客戶的公開個人資料、聊天訊息，也不是個別客服專用的 CRM 別名。

重點整理

• 目前文件支援的是 whatsapp，並非所有管道或 whatsapp-protocol。
• note 為必填；空字串表示清除，未編輯的表單不應送出請求。
• 「僅帳號可見」不等於共用收件匣具有依客服人員隔離的權限。
• 備註寫入、通訊錄姓名同步與訊息傳送應分開處理。

先決定要改哪一種名稱

WhatsApp 的聯絡人管理公告介紹了連結裝置上的聯絡人管理。這是帳號端資料的背景，並非 UnifyPort 備註 API 的規格。

想要的修改	適合的層級
為已連結帳號設定聯絡人的自訂名稱	UnifyPort 聯絡人備註
只有某位客服能看到的別名	應用程式自己的儲存與權限
接收管道通訊錄的姓名變更	獨立的姓名同步檢視
在聊天中分享聯絡資料	聯絡人名片訊息

接收通訊錄變更請參考 contact.updated 姓名同步指南。該事件不會覆寫暱稱，也不是文件保證的備註寫入確認訊號。如果目的是儲存或分享聯絡人，請看新增聯絡人與傳送 vCard 的差異。

介面應明確區分「帳號備註」與「我的別名」，避免兩個欄位都叫「私人名稱」，儲存位置卻不同。

設定與清除 WhatsApp 聯絡人備註

設定聯絡人備註文件定義方法、請求及成功回應。啟用管道的儲存按鈕前，先核對管道操作支援矩陣。

在伺服器端準備工作區 API 金鑰與選定的訊息帳號，依聯絡人查詢文件在相同帳號下確認目標。將識別碼保留為不透明字串，不要從顯示名稱自行產生，也不要假設每種操作接受相同格式。

請求欄位	用途
contact_id	此操作的目標聯絡人
note	自訂顯示名稱；"" 清除既有備註

以下 JavaScript 函式示範文件中的呼叫。由後端傳入實際選取的帳號和聯絡人識別碼，並從安全設定載入金鑰。範例不會自動重試，也不是完整的收件匣應用程式。

async function setContactNote({ apiKey, accountId, contactId, note }) {
  if (typeof note !== 'string') throw new TypeError('note must be a string');
  if (!accountId || !contactId) throw new Error('Select account and contact');

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

儲存時傳入使用者確認的文字；清除時呼叫相同函式並傳入空字串。不要把缺少的表單值預設成空字串，否則「未修改」會變成清除操作。在本地拒絕 null，不要自行設計另一種清除方式。

文件的成功回應是 200 OK 並包含 data.ok: true。檢查結果後才標示已儲存；fetch 完成並不等於操作成功。

避免舊請求覆蓋新編輯

以下為應用程式設計建議，不是 API 額外欄位或伺服器並行控制保證：

1. 依工作區、訊息帳號及聯絡人限定編輯器與工作佇列的範圍。同名不是相同身分。
2. 區分未變更、已編輯與明確清除三種狀態；必要時要求確認清除。
3. 在應用程式內循序執行同一目標的寫入，防止重複點擊，並在送出前拒絕過時工作。
4. 依資料保留政策記錄要求值、結果及 request_id，不要記錄 API 金鑰。
5. 請求逾時時顯示結果未知，不要直接宣告失敗或自動重送舊值；另一位編輯者可能已儲存新備註。

應用程式內的循序處理無法協調所有連結用戶端。公開文件沒有定義版本前置條件、專用備註回讀欄位，或保證送達的備註變更 webhook。不要以自行假設的欄位建立確認迴圈。先用受控測試確認帳號端行為；無法觀察結果時，保留不確定狀態。

錯誤參考將伺服器或上游備註操作失敗定義為 set_contact_note_failed，未支援操作為 unsupported_by_provider。能力不支援不是無限重試的理由。

驗收檢查與常見問題

建議測試設定、替換、明確清除、未編輯表單、非字串輸入、兩筆競爭編輯、未支援管道及逾時。這是測試清單，不是已驗證的正式環境成果。

這是客服工單的私人筆記嗎？

不是。文件將其定義為私人聯絡人備註，也就是自訂顯示名稱。長篇案件紀錄和敏感客服評論應留在具權限控制的 CRM，而非顯示名稱欄位。

清除備註會刪除聯絡人嗎？

不會。文件中的操作只清除備註，不是刪除聯絡人或訊息。

可以用於 LINE、Zalo 或 WhatsApp Protocol 嗎？

目前操作矩陣僅為 whatsapp 列出這項寫入能力。UnifyPort 非官方介面採統一 API 形式，不代表各管道功能相同。

可以用 contact.updated 確認備註儲存嗎？

不行。它描述通訊錄姓名變更，不是自訂備註的保證回執。

下一步與資料來源

閱讀設定聯絡人備註，先對一位受控聯絡人測試，再於共用收件匣開放帳號端編輯。

核對日期：2026-10-13。

• UnifyPort：設定聯絡人備註
• UnifyPort：管道操作支援
• UnifyPort：標準事件
• WhatsApp：聯絡人管理公告