WhatsApp 会话列表缺少聊天？先检查标签筛选

通过 UnifyPort 查询 WhatsApp 会话时，如果结果比预期少，先检查查询条件，不要立即重新连接账号。文档明确：省略 label_id 时，WhatsApp 只返回已加星标／“特别关注”的会话。 即使分页已结束，也不代表读取了账号内所有聊天。发现会话、查询通讯录和获取历史消息，是三个不同任务。

核心要点

• 不传 label_id 不等于“全部 WhatsApp 聊天”。
• 标签目录返回标签定义，不是标签下的会话记录。
• 一轮分页必须保持消息账号和筛选条件一致。
• 不要因为会话未出现在筛选结果中，就删除本地会话。

先确认你查询的是哪种列表

WhatsApp 帮助中心将列表定义为可自定义的聊天筛选器。这有助于理解筛选视图，但不能据此推导 UnifyPort 的接口行为，也不意味着应用内每种列表都有对应 API。

集成时应以 List conversations 文档为准。它查询的是平台实时数据，而不是 UnifyPort 本地数据库中的聊天档案。

查询操作	返回内容	不能据此推断
WhatsApp 会话列表，不传 label_id	加星标／特别关注会话	账号内全部聊天
会话列表，传入选定的 label_id	指定标签视图	账号的完整会话清单
查询会话标签	含 id、name 的标签对象	每个标签下的聊天
查询联系人	平台通讯录条目	全部会话或消息
查询群组	已加入的群组，包括没有聊天记录的群	私聊或群消息历史

从当前消息账号的标签目录获取标签 ID，不要用显示名称代替。六月 API 更新介绍了创建标签和修改成员关系的操作；本文解决的是读取范围问题：如何得到目标视图，而不是误认为拿到了完整清单。

按顺序排查 WhatsApp 会话缺失

1. 核对消息账号与查询范围

确认请求使用的工作区凭据和 account_id。从另一个消息账号取得的标签 ID，不是当前账号可靠的筛选依据。API key 应保留在后端，诊断记录不得包含凭据。

记录 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 帮助中心：如何使用列表