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 說明中心：如何使用列表