WhatsApp 置顶聊天与置顶消息：API 应该怎么选？

WhatsApp 置顶聊天是让某个会话在聊天列表中更容易找到；置顶消息是突出会话内的一条具体内容。两者不是同一设置。在通过 API 管理的收件箱中，先明确要操作的对象：聊天需要会话 ID；消息还需要自身 ID，置顶别人发送的消息时也要明确发送者 ID。

核心结论

• 聊天置顶管理已连接账号的聊天列表，消息置顶选择聊天中的具体内容。
• UnifyPort 为两者提供不同接口，取消置顶的方式也不同。
• 会话置顶没有时长参数；消息置顶支持可选的 duration_seconds。
• conversation.updated 中的 pinned 表示聊天列表状态，不表示某条消息被置顶。

WhatsApp 置顶聊天和置顶消息有什么区别？

WhatsApp 的给自己发消息说明介绍了将聊天置于列表顶部；消息置顶说明则要求选择具体消息及置顶时长。虽然都叫“置顶”，操作对象并不相同。

需求	应选对象	不应推断
方便找到某个客户会话	聊天列表条目	客户的某条消息也会被突出显示
在群里突出操作说明	单条消息	群聊也会移到收件箱顶部
把紧急工单分配给客服	应用自己的工单或队列	平台置顶会自动建立负责人或截止时间

WhatsApp 官方帮助还说明，群内置顶消息会产生系统消息，显示由谁执行了置顶；管理员可以控制成员是否能置顶。不要把群消息置顶包装成客服的私人书签。官方也指出，缺失聊天历史可能导致用户看不到被置顶的消息，因此置顶不是恢复内容的办法。

如果只是希望在自建客服系统中保留私人提醒，建议使用应用自己的书签，而不是静默更改平台状态。这是应用设计建议，不是额外的 API 能力。

按对象选择 UnifyPort 接口

以下属于 UnifyPort 的非官方接口，不是 Meta Cloud API。

项目	置顶会话	置顶消息
方法与路径	POST /v1/accounts/{account_id}/conversations/pin	POST /v1/messages/pin
账号位置	URL 中的 account_id	JSON 中的 account_id
JSON 目标字段	conversation_id	conversation_id、message_id；别人的消息明确传 sender_id
状态选择	路径本身表示置顶	pinned: true 置顶，pinned: false 取消
时长	没有时长参数	置顶时可传 duration_seconds
取消操作	独立的取消会话置顶接口	同一消息接口传 pinned: false

构造请求前，核对置顶会话、取消会话置顶及置顶／取消置顶消息参考。

不要从原生应用的界面选项推导会话 API 的时长字段，也不要向会话置顶接口传入消息操作的 pinned: false，期待它取消置顶。必须遵循具体接口的契约。

当前平台操作支持矩阵将会话置顶和取消置顶映射到 WhatsApp、LINE，但消息置顶仅映射到 WhatsApp。不支持的组合返回 501 unsupported_by_provider。因此，面向东南亚市场同时接入 LINE 和 WhatsApp 的团队，应分别控制聊天和消息按钮，不能因为 LINE 支持前者就启用后者。

保留选中的消息，不要自动换成最新消息

对于从已存储 message.received 事件选中的消息，文档规定的映射为：

• 事件顶层 account_id → 请求的 account_id；
• data.conversation.id → conversation_id；
• data.message.id → message_id；
• data.sender.id → sender_id。

消息置顶接口在省略 sender_id 时默认使用已连接账号自身。置顶其他参与者发送的内容时，应明确传入对应发送者。群聊 ID 代表群，发送者 ID 代表作者，不能相互替代。

客服确认操作期间，应固定所选消息，不能因新消息到达而更换目标。发送请求前，还要检查操作人员是否有权操作该消息账号和会话。

引用消息也容易引起混淆：父消息 ID 并不等于当前消息 ID。WhatsApp 引用回复指南解释了这种关系。置顶需要选中消息自身的 ID，不需要 reply_token，也不应自动改用父消息 ID。

在正确层级确认结果

两个修改接口的成功示例均包含 data.ok: true。分别记录请求目标和实际返回结果，不要将点击按钮等同于操作成功。HTTP 超时意味着结果不确定；不要立即显示成功，也不要自动执行相反操作来“修正”。

事件参考中的 conversation.updated 使用 data.conversation.id 标识聊天，置顶状态变化可带 data.pinned。它描述已连接账号本地的聊天列表状态，并不指出会话内哪条消息被置顶。

只应用事件实际包含的设置：例如静音更新未包含 pinned 时，不应清除已保存的置顶状态。将事件视为观察结果，不要承诺每次 API 调用都一定产生确认事件。当前公开事件目录未记录专用的消息置顶事件，平台事件矩阵也未将 conversation.updated 映射到 LINE。

接收事件时，应遵守Webhook 投递契约完成验签和重复投递处理。事件用于校正视图，不应再次自动调用同一置顶操作。

置顶不是客服优先级系统

假设团队希望在等待答复期间置顶客户聊天，负责人、到期时间和解决状态仍应保存在应用中。取消置顶不能静默关闭工单。

WhatsApp 已读／未读同步和静音与屏蔽的区别也遵循同一边界：可见性、阅读状态、通知偏好及联系限制各有用途。

上线前建议测试聊天置顶、独立取消操作、其他群成员的消息、不支持的平台及 HTTP 响应丢失。这些是建议验收项，不是已执行的测试结果。人工操作足够时可直接使用原生应用；需要官方集成时，应另行评估对应官方契约。

常见问题

置顶聊天会同时置顶最新消息吗？

不会。两者操作不同对象，使用不同 API。

会话置顶能传 duration_seconds 吗？

UnifyPort 当前会话置顶契约没有该字段。它属于消息置顶操作。

conversation.updated 中的 pinned 能确认消息置顶吗？

不能。它表示已连接账号的聊天列表设置，而不是单条消息的置顶状态。

LINE 可以使用两种置顶吗？

当前矩阵支持 LINE 会话置顶和取消置顶，不支持消息置顶。应逐项核对能力。

下一步与来源

从置顶会话参考开始，先按目标对象命名界面按钮，再启用操作。

核对日期：2026-10-08。

• WhatsApp：给自己发消息
• WhatsApp：置顶消息
• UnifyPort：置顶／取消置顶消息
• UnifyPort：平台操作支持矩阵