WhatsApp 联系人备注：设置或清空私有显示名称

通过 UnifyPort 为 WhatsApp 联系人设置私有显示名称，使用 POST /v1/accounts/{account_id}/contacts/note，提交 contact_id 和字符串 note。清空时显式传入 note: ""。这个操作修改账号侧联系人备注，不是客户的公开资料、聊天消息，也不是某位客服独享的 CRM 别名。

核心要点

• 当前文档支持的是 whatsapp，不能扩展理解为所有渠道或 whatsapp-protocol。
• note 必填；空字符串表示清空，未编辑的表单则不应发送请求。
• “仅账号可见”不代表共享收件箱中具有按客服隔离的访问权限。
• 备注写入、通讯录姓名同步和消息发送需要分开处理。

先确定要改的是哪一种名称

WhatsApp 的联系人管理公告介绍了关联设备上的联系人管理。这是理解账号侧资料的背景，并不定义 UnifyPort 的备注接口。

面向跨境客服团队设计编辑器时，先划清以下边界：

想完成的修改	合适的层级
为已连接账号设置联系人自定义名称	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：联系人管理公告