WhatsApp 清空與刪除對話：同步正確的 Webhook 狀態

清空 WhatsApp 對話會清除本機記錄，但保留對話；刪除對話則是另一項對話列表操作。在 UnifyPort 中，conversation.cleared 及 conversation.deleted 分別回報已連接訊息帳戶的這些變化。兩者都不代表為所有人刪除訊息。共用收件匣應分開管理記錄內容與對話的顯示狀態，再按明確政策處理自行儲存的副本。

重點

• 這是帳戶本機變更通知，不是刪除客戶訊息的指令。
• 目標對話由 data.conversation.id 識別，而非最外層事件 id。
• delete_media 描述本機媒體移除，不證明物件儲存或 CRM 的副本已清理。
• 阻止舊記錄重新顯示，不應等於永久拒絕這個對話的新訊息。

清空、刪除對話與收回訊息有何分別？

WhatsApp 的清空對話說明指出，清空不會將對話移出列表，也不會令你退出群組。刪除對話說明則把刪除視為另一項操作，並說明刪除群組對話前須先退出群組。整合時，不要將任何一項操作解讀成「清除所有業務系統的一切資料」。

觀察事件	文件定義的範圍	建議的收件匣處理
conversation.cleared	已連接帳戶清空本機記錄；遠端對話及群組成員身分不變	保留對話入口，按政策隱藏受影響的本機記錄
conversation.deleted	已連接帳戶在本機刪除對話	從一般鏡像列表移除，只保留政策容許的核對中繼資料
message.deleted	單一訊息被刪除或收回	定位指定訊息，不處理整個對話
conversation.updated	本機對話設定改變	更新提供的設定，不推斷記錄已被刪除

最後一欄是應用程式設計建議，不是 UnifyPort 自動執行的操作。若目的是收回已發送訊息，請參考編輯、收回與本機隱藏指南。對話刪除事件不是收回請求的回執。

按對話事件解析，不要套用訊息結構

清空事件文件與刪除事件文件提供對話目標及 delete_media，沒有提供受影響訊息 ID 清單，也沒有定義精確的記錄截止點。

以下範例使用文件欄位與虛構識別碼，不是實際擷取的流量：

{
  "id": "evt_c4d0b7a2e5",
  "type": "conversation.cleared",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-10-29T08:15:00Z",
  "data": {
    "conversation": {
      "id": "8600000000000@s.whatsapp.net",
      "type": "user"
    },
    "delete_media": true,
    "event": { "kind": "conversation_cleared" }
  }
}

本機查詢須同時限定工作空間、渠道、account_id 及 data.conversation.id。保留收到的識別碼，不要從電話號碼自行組合，也不要因對話名稱相同而合併。這是對話事件，不應要求 data.message.id。

渠道事件矩陣目前將這兩項事件對應至 whatsapp，不包含獨立的 whatsapp-protocol 或所有其他渠道。矩陣描述解析器支援，不保證每個上游帳戶或部署都會發出事件。

分開儲存三類應用程式狀態

先定義產品承諾，再實作清理。鏡像收件匣可以跟隨帳戶隱藏本機記錄；受獨立政策管理的個案檔案可能有不同保留要求。應向操作人員說明差異，不能默默將原生清空視為「毋須處理」或「刪除所有業務記錄」。

在自己的儲存層分別維護：

1. 對話列表可見性：對話是否出現在鏡像列表。
2. 記錄可見性及清理狀態：哪些舊內容被隱藏，哪些自有副本仍待清理。
3. 後續訊息接納規則：何時讓新活動重新開啟對話，而不恢復舊記錄。

這些是建議的本機概念，不是新增 Webhook 欄位。保留最少量的帳戶範圍標記及清理決定，不要刪除所有對話身分資料，否則延遲歷史批次可能重建可見記錄。

兩種事件均須遵循 Webhook 投遞契約：設定 signing_secret，對 X-Device-Timestamp、一個句點及原始請求本文驗證 HMAC-SHA256，並檢查時間戳新鮮度。在同一本機交易中完成一般事件去重、可見性變更及清理工作入列；持久化接收後回傳 2xx，不必等候所有外部系統完成。

不要讓歷史載入撤銷清空決定

投遞順序沒有保證。occurred_at 記錄事件時間，但清空／刪除契約沒有把它定義為所有受影響訊息的精確截止時間。HTTP 到達時間亦不能證明內容是新訊息。

可採用以下保守策略：

後續輸入	隱藏規則仍有效時的建議處理
同一清空或刪除事件重試	維持決定，繼續未完成的清理
歷史批次含有已隱藏內容	不自動重新顯示
即時事件含有已隱藏的訊息 ID	保持隱藏
看似新訊息，但與清空的先後關係不明	暫停自動回覆並覆核範圍
已確認的新對話活動	按明訂規則重新顯示對話，不恢復舊記錄

已知訊息 ID 能保護已儲存內容，但無法識別從未收到的舊訊息。缺乏可信邊界時，應選擇明確覆核或保守隱藏，不要聲稱能完美重建時間順序。新的事件 ID 本身不代表新的訊息內容。

若收件匣提供歷史載入，應把這項政策加入 WhatsApp 按需歷史載入的合併流程。歷史批次需要逐項訊息合併，僅按最外層事件 ID 去重可能丟失合法分塊。載入歷史不應自動重設清空決定。

媒體清理與驗收

delete_media=true 表示本機媒體亦已清除或移除，不證明下載附件、搜尋索引、AI 上下文或轉發副本已刪除。false 也不代表可以無限期保留所有內容。應執行已向用戶說明的保留與存取政策，分開追蹤清理完成狀態及 Webhook 確認。

使用自己控制的帳戶測試：

• 清空後保留對話入口，但搜尋不包含已隱藏內容。
• 刪除對話後鏡像列表隱藏它，不自動封鎖聯絡人或請求退出群組。
• 舊歷史批次或重複事件到達後，不自動恢復內容。
• 已確認的新活動可按規則重新開啟對話，不帶回舊記錄。
• 媒體清理失敗時顯示「待清理」，而非「已完全刪除」。

這些是建議測試，不是已取得的結果。UnifyPort 提供非官方介面，沒有保證重播，也沒有回傳訊息歷史的 REST 讀取 API。未收到事件不代表沒有發生本機變更。

常見問題

conversation.deleted 會刪除對方的訊息嗎？

不會。文件定義的是已連接帳戶在本機刪除對話，不是為所有人刪除。

conversation.cleared 代表退出群組嗎？

不是。文件明確指出群組成員身分不變。

可以用這些事件實作清空對話 API 按鈕嗎？

事件文件描述觀察結果，不是發起清空或刪除的操作。不要從事件名稱推導不存在的端點。

下一步與來源

先閱讀 conversation.cleared 文件，明訂可見性、保留及重新開啟規則，再連接具破壞性的清理工作。

資料核對日期：2026-10-29。

• WhatsApp：清空對話
• WhatsApp：刪除對話
• UnifyPort：conversation.deleted
• UnifyPort：Webhook 投遞