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：聯絡人管理公告