消息常见问题

本页覆盖收发消息、顺序与去重、撤回、已读、离线补收与高级消息能力的常见问题。消息相关的硬限制：单条 5120 字节、文本 5000 字符、历史分页默认 20/上限 100、撤回窗口 120 秒。

为什么会收到重复消息？​

投递语义是 at-least-once（客户端按 messageId 去重），客户端必须按 messageId 去重。建议在内存 Set 之外再持久化已处理 messageId（Android/Electron 可落本地库），避免重启后重复渲染。

重发消息会不会产生两条？​

不会——只要重试时复用同一个 clientMsgId（同用户 10 分钟内幂等）。换 clientMsgId 就会产生两条，这是最常见的“重复消息”来源。

消息顺序乱了怎么修？​

  • 同一会话内以服务端分配的 seq 排序，不要用本地接收时间排序。
  • 离线补发与在线推送可能交错到达：统一按 seq 插入。
  • 跨会话没有全局顺序，不要试图做全局时间线。

离线期间的消息能补发多少？​

协议声明单会话补发上限 500；重连后 hello 给出游标并补发，补发完成下发 sync_done。若消息量超过补发范围，用历史分页兜底（默认 20/页，最多 100）。

聊天室消息为什么不补发？​

聊天室是“在线态”会话：消息不持久化、不补发、断连即离开。需要留存的场景请用群组，或在业务侧通过回调归档。

撤回后消息内容还能搜到吗？​

不能。撤回会把消息内容替换为撤回占位（原文本不再保留在消息体里），因此文本搜索与本地搜索都不会命中撤回消息。

撤回返回 1022/1023 是什么？​

1022 = 超过撤回窗口（默认 120 秒，可在控制台调整）；1023 = 消息已被撤回，重复撤回是幂等提示，不是系统故障。

已读回执怎么算的？​

接收方上报已读后，发送方查询已读人数/已读用户列表；群聊按消息维度统计已读人数与会话总人数。已读状态与未读数是两套状态：已读影响展示，未读影响角标。

正在输入状态会一直显示吗？​

不会。typing 状态默认数秒后自动过期，且受输入状态限频（每分钟 60 次）约束；超限的 typing 会被丢弃，不要重试。

单条消息最大能发多大？​

序列化后 5120 字节（超限 1007）；文本最多 5000 字符。图片/文件请先上传拿 URL，再发结构化内容。

消息扩展/回应/流式/合并有什么限制？​

  • 扩展：仅单聊/群聊/超级群，发送时开启可扩展；单次 ≤20 对、单条 ≤300 对、value ≤4096 字节。
  • 回应：单条最多 50 种、每种最多 100 人；reactionId 1-16 字符。
  • 流式：单聊/群聊/系统通知，聊天室不支持；仅发送者可追加/结束。
  • 合并转发：条目 1..100、标题 ≤64 字，序列化后仍受 5120 字节限制。

发送返回 1008（限频）怎么办？​

单用户发送限频 120 次/分钟。按 Retry-After/指数退避重试，并合并高频消息（例如输入状态不要每次按键都发）。

消息历史被清理了，本地还有吗？​

本地库不会随服务端清理自动删除：Android/Electron 的本地消息仍在。需要一致时由业务侧同时清理本地库（Electron 提供 clearMessages/deleteMessagesByTime）。

相关链接​