WhatsApp 置頂聊天與置頂訊息：如何選對 API？

WhatsApp 置頂聊天是讓某個對話在聊天清單中更容易找到；置頂訊息則是突出對話內的一則內容。兩者並非同一項設定。在以 API 管理的收件箱中，應先確定操作對象：聊天需要對話 ID；訊息還需要本身的 ID，置頂其他人發送的訊息時，也要明確指定發送者 ID。

重點

• 聊天置頂管理已連接帳戶的聊天清單；訊息置頂選擇對話內的內容。
• UnifyPort 提供不同端點，取消置頂的方式亦不同。
• 對話置頂沒有時長參數；訊息置頂支援選填的 duration_seconds。
• conversation.updated 內的 pinned 是聊天清單狀態，不是訊息置頂狀態。

置頂聊天與置頂訊息有甚麼分別？

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 支援聊天置頂，不代表支援訊息置頂。

保留已選訊息，不要換成最新一則

從已儲存的 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，也不應自動改用父訊息。

在正確層級確認結果

兩個修改端點的成功範例均包含 data.ok: true。請分別記錄請求目標及實際回應，不要將按下按鈕當作操作成功。逾時代表結果未明；不要立即顯示成功，也不要自動執行相反操作。

事件參考中的 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：平台操作支援矩陣