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 投遞