WhatsApp 對話清單少了聊天？先檢查標籤篩選

透過 UnifyPort 查詢 WhatsApp 對話時，如果結果比預期少，先檢查查詢條件，不要立刻重新連線。文件明確說明：省略 label_id 時，WhatsApp 只回傳已加星號／「特別關注」的對話。 即使分頁已結束，也不代表讀取了帳號內所有聊天。探索對話、查詢通訊錄及取得歷史訊息，是不同的工作。

重點整理

• 不傳 label_id 不等於「全部 WhatsApp 聊天」。
• 標籤目錄回傳標籤定義，不是標籤下的對話紀錄。
• 一輪分頁必須維持相同的訊息帳號與篩選條件。
• 不要因為對話未出現在篩選結果中，就刪除本機資料庫的對話。

先確認查詢的是哪種清單

WhatsApp 說明中心將清單描述為可自訂的聊天篩選器。這有助於理解篩選檢視，但不能據此推論 UnifyPort 的 API 行為，也不表示應用程式中的每種清單都有對應 API。

整合時應以 List conversations 文件為準。它即時查詢平台資料，不是讀取 UnifyPort 本機資料庫中的聊天檔案。

查詢操作	回傳內容	不能據此推論
WhatsApp 對話清單，不傳 label_id	加星號／特別關注對話	帳號內全部聊天
對話清單，傳入選定的 label_id	指定標籤的檢視	帳號的完整對話清單
查詢對話標籤	含 id、name 的標籤物件	每個標籤下的聊天
查詢聯絡人	平台通訊錄項目	全部對話或訊息
查詢群組	已加入的群組，包括沒有聊天紀錄的群組	私人聊天或群組訊息歷史

從目前訊息帳號的標籤目錄取得標籤 ID，不要用顯示名稱取代。六月 API 更新介紹建立標籤及調整成員關係的操作；本文聚焦讀取範圍：如何取得目標檢視，而不是誤以為取得完整清單。

依序排查 WhatsApp 對話缺漏

1. 核對訊息帳號與查詢範圍

確認要求使用的工作區憑證及 account_id。另一個訊息帳號的標籤 ID，不是目前帳號可靠的篩選依據。API 金鑰應保留於後端，診斷紀錄不得包含憑證。

記錄 label_id 是未提供，還是含有實際標籤 ID。不要假設空字串、萬用字元或自行指定的「all」代表全部對話；此處沒有文件化的全量選取值。

選用的 type 接受精確的 user、group、channel，多個值以逗號分隔，不會自動去除空白。例如 user,group 符合文件語法，不要產生 user, group。只查詢群組時，看不到私人聊天不代表連線故障。

2. 在相同範圍內完成分頁

limit 的文件範圍為 1–100，預設 20。只要 data.has_more 表示還有結果，就使用 data.next_cursor 繼續，並維持帳號、標籤及類型篩選不變。游標是不透明值，不要解碼、修改或在不同查詢之間共用。

無效或過期游標可能被拒絕，也可能讓平台重新開始分頁。建議用戶端偵測重複游標，依帳號範圍內的 conversation_id 合併重複項目；發現循環時停止並顯示診斷資訊，不要無限查詢。確實需要重跑時，以相同篩選開始新一輪並再次去重。

has_more: false 只代表目前查詢的分頁結束。它不能證明已包含其他標籤、未選取的聊天或歷史訊息。即時查詢跨越多頁，也不應被視為文件承諾的不變快照。

3. 直接查詢已知但未出現在清單中的聊天

如果應用程式已從可信事件或先前 API 回應取得對話識別碼，可使用取得單一對話，將 conversation_id 放在查詢參數。透過 URL 編碼工具建立參數，不要把平台對話識別碼直接放入路徑區段。

單一對話查詢成功、清單卻沒有該項目時，應優先調查清單範圍，而不是認定帳號斷線。查詢回傳找不到時，也需先核對帳號與識別碼；不能据此刪除本機歷史。不要從顯示名稱或電話號碼自行組出對話 ID。

4. 選擇符合問題的讀取介面

通訊錄問題使用聯絡人清單，其範圍涵蓋通訊錄項目，不以是否有訊息歷史為前提。聊天操作應使用回傳的 conversation_id 對應，不要假設聯絡人 id 與對話識別碼可以互換。聯絡人名稱同步指南詳細說明這個身分邊界。

查詢已加入的群組時，群組清單也可涵蓋從未用來傳訊的群組。兩種讀取都不能取代訊息封存；合併結果，也無法證明已發現所有私人對話。

讓收件匣正確呈現範圍

在應用程式中分開維護三個概念：已觀察到的對話、目前的平台篩選結果，以及自行保存的訊息。這些是建議的本機資料邊界，不是額外 API 欄位。

實際只顯示標籤或特別關注對話時，畫面應標示「所選標籤」或「特別關注對話」，而不是「全部對話」。項目從篩選結果消失，只應影響該檢視，不應自動刪除本機對話和訊息紀錄。讀取失敗也應與成功但結果為空分開呈現。

持續接收訊息時，UnifyPort 的非官方介面提供 message.received 等標準化事件。依照 webhook 投遞契約設定 signing_secret，以 HMAC-SHA256 驗證 X-Device-Timestamp、英文句點與原始要求本文組成的內容，檢查時間戳新鮮度，在持久化接收後才回傳 2xx。保存實際觀察到的帳號與對話識別碼，以供後續查詢。

這不能保證發現未觀察到訊息流量的聊天。UnifyPort 不提供 REST 訊息歷史讀取 API，也不保證遺漏事件重播。WhatsApp 隨需歷史流程針對已知且符合條件的私人對話，非同步要求可用的舊訊息；它不是列舉所有聊天的操作。

常見問題

增加 limit 能顯示所有 WhatsApp 聊天嗎？

不能。它調整目前查詢的每頁大小，不會取消預設的特別關注範圍。

可以把標籤 ID 當作對話 ID 嗎？

不可以。標籤識別分類，對話識別聊天，兩者是不同資源。

空清單是否表示帳號需要重新授權？

不是。先核對帳號選擇、篩選、分頁與回傳錯誤，不要只因篩選檢視為空就開始新的授權流程。

下一步與參考資料

使用受控測試帳號，對照對話清單文件檢查要求，再比較已知對話的直接查詢結果與篩選可見性。用於共用收件匣資料核對之前，測試切換標籤、重複游標及空結果。這些是建議測試，不是已取得的正式環境成果。

核對日期：2026-10-03。

• UnifyPort：對話清單
• UnifyPort：對話標籤清單
• WhatsApp 說明中心：如何使用清單