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 與 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，也不應自動選取父訊息。

在正確層級確認結果

兩個修改端點的成功範例都有 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：平台操作支援矩陣