即时通信 IM文档中心入门中心API 中心SDK 中心文档活动我的反馈文档反馈官招募中，报名立赚积分兑换代金券！> HOT文档中心>即时通信 IM>常见问题>消息相关问题消息相关问题最近更新时间：2025-10-16 09:30:31

微信扫一扫QQ新浪微博复制链接链接复制成功我的收藏本页目录：消息没有收到或消息丢失如何处理？收不到离线推送怎么处理？红包消息怎么处理？即时通信 IM 消息存储时长是多久？为什么发送者已经被拉入黑名单但消息依旧显示发送成功？如何通过 COS 将图片地址变成可下载的域名格式？即时通信 IM 的消息唯一标识的规则是怎样的？消息编辑 & 消息扩展 & 消息回应有什么区别？为什么同一秒级内的消息，接收方接收消息时，可能存在乱序？为什么弱网情况下发送消息失败（实际消息发送成功）？弱网情况下进入聊天“加载历史消息耗时久”，怎么优化？为什么调用 sendMessage 接口立刻并行设置 localCustomData 内容不生效？语音消息发送成功后，调用 convertVoiceToText 语音转文字接口报 40001 错误，如何解决？加载会话列表，实现会话 lastMessage 消息，对于当前登录的用户，如何判断显示已读或未读状态？在发消息失败的情况下，怎么获取到失败的 Code 码？TUIKit 接入时，群组解散、用户退群或被踢出群，群聊消息会都被清空，如何保留本地缓存的历史消息？iOS 客户端调用 SDK 的拉取历史消息，msgID 有重复，如何解决？Flutter Web 端 UIKit 集成，发送图片报 “Error from TUIKit: Only JPG/PNG/JPEG/GIF images can be uploaded, Code: 2252” 错误。图片格式是 jpg, 还是报错，要如何解决？Flutter UIKit 接入，发送消息必报错：The message read receipt feature is available only to the Premium Edition. Please upgrade.，如何解决？IM Harmony SDK 发送图片失败，是什么问题？将用户拉入黑名单，通过 REST API 指定“被拉黑的用户”给自己发消息时，自己依然能收到，是什么问题？消息没有收到或消息丢失如何处理？通过 控制台罗盘 进行自助接入排障。收不到离线推送怎么处理？请根据 推送服务（Push）> 常见问题 文档进行处理。红包消息怎么处理？红包消息与 @ 消息类似，可以通过 TIMCustomElem 来实现。需要应用在 UI 上做相应的特殊处理，例如检查到当前消息为红包消息后，消息展示为红包的样式。

另外，红包消息作为重要消息，最好在发送消息的时候将其设置为高优先级消息，以最大程度保证消息在触达频率限制的情况下仍可以送达（目前群内消息默认限制频率40条/s, 单聊消息默认限制频率为5条/s）。关于消息优先级相关的内容可以参考 消息优先级。注意：红包消息涉及支付的部分，请自行实现或集成第三方支付 SDK，IM SDK 暂不提供相关功能。一个简单的红包消息的构建过程如下（Android）：try { // 填充自定义的消息协议 JSONObject redPacket= new JSONObject(); redPacket.put("type", "RED_PACKET"); redPacket.put("amount", 2018); redPacket.put("msg", "Happy new year!"); V2TIMMessage message = V2TIMManager.getMessageManager().createCustomMessage( redPacket.toString().getBytes("utf-8"), "red packet", null);} catch (Exception e) { Log.e(TAG, "build custom message failed");}即时通信 IM 消息存储时长是多久？单聊消息及非直播群消息具备历史消息存储能力，您可以登录 即时通信 IM 控制台 修改相关配置。不同套餐包默认配置如下：体验版：7天，不支持延长。专业版：7天，支持延长。旗舰版：30天，支持延长。延长历史消息存储时长是付费增值服务，具体计费说明请参见 增值服务详情。为什么发送者已经被拉入黑名单但消息依旧显示发送成功？即时通信 IM 在控制台的 黑名单检查 管理中提供发送消息后展示发送成功功能，当启用该功能时被拉黑用户侧发消息后仍展示发送成功 (实际对方不会收到消息) 。RestAPI 接口下发消息，该接口不会检查发送者和接收者的好友关系（包括黑名单），需要加 WithBlackListCheck 表示该条消息会检查发送者和接收者的黑名单。停用本设置项，则被拉黑用户侧发消息后会提示失败，SDK 会收到 错误码 20007 。具体配置请参照文档 黑名单检查。如何通过 COS 将图片地址变成可下载的域名格式？上传需要用户自己处理。如果使用存储服务私有读，需要 URL 签名确保有下载权限（预签名下载）。即时通信 IM 的消息唯一标识的规则是怎样的？即时通信 IM 客户端单聊/群聊消息，Web 端单聊/群聊消息及服务端单聊消息唯一标识分别对应 msg_id，msgID 及 msgKey。各端不同类型消息唯一标识的规则不同，具体规则如下：客户端单聊/群聊消息 msg_id 的组成是：tinyid-clientTime-random。Web 端单聊/群聊消息 msgID 的组成是（v2.17.0及以下）：会话 id-msgSeq-random-1（我发送的消息） / 0（非我发送的消息）。Web 端单聊/群聊消息 msgID 的组成是（v2.18.0及以上）：tinyid-clientTime-random。服务端单聊消息 msgKey 的组成是：clientSeq_random_serverTime。服务端群聊消息通过群 id + msgSeq 来进行唯一标识。消息编辑 & 消息扩展 & 消息回应有什么区别？消息功能是否需要旗舰版存储方式拉取方式并发设置是否会冲突消息编辑不需要编辑信息直接存在消息体内，共用消息存储，单条消息最大 12K编辑信息直接通过消息体返回，无需单独拉取会有冲突消息扩展需要扩展信息独立存储，单条消息最大支持设置 300 个扩展，单个扩展最大支持 1K扩展信息需要单独拉取，仅支持逐条消息拉取同一个扩展设置会冲突，不同的扩展设置不会冲突消息回应需要回应信息独立存储，单条消息最大支持设置 10 个回应，单个回应最大支持 100 个用户回应信息需要单独拉取，支持多条消息批量拉取不会冲突消息编辑您可以调用 modifyMessage(Android / iOS & Mac / Windows) 接口对原始消息内容做编辑。优势：简单易用。劣势：如果多个用户同时编辑一条消息，可能会导致编辑冲突。如果编辑后的消息内容过大，可能会导致消息大小超限（单条消息最大支持 12K）。总结：消息编辑适合单个用户操作且存储需求较小的场景，例如订单消息场景，可以通过编辑消息的 cloudCustomData 字段来存储和修改订单的状态。消息扩展您可以调用 setMessageExtensions (Android / iOS & Mac / Windows) 接口为一条消息添加扩展信息。优势：单条消息可以设置多个扩展，不同的扩展同时设置不会冲突。扩展信息独立存储，不占用消息体大小，单条消息最大支持设置 300 个扩展，单个扩展最大支持 1K。劣势：同一个扩展同时设置，也会有冲突问题。扩展信息需要调用 getMessageExtensions (Android / iOS & Mac / Windows) 接口单独拉取。扩展信息不支持多条消息批量拉取。总结：消息扩展适合多个用户操作且存储量较大的场景，例如问卷调查场景，每个扩展信息都是 {userID : 问卷调查内容} 的集合，不同的用户填写问卷调查不会冲突。消息回应您可以调用 addMessageReaction (Android / iOS & Mac / Windows) 接口为一条消息添加回应信息。优势：单条消息可以添加多个回应，回应添加不冲突。回应信息独立存储，不占用消息体大小，单条消息最大支持添加 10 个回应，单个回应最大支持 100 个用户。回应信息支持多条消息批量拉取。支持单独拉取使用同一个回应的用户列表。劣势：回应信息需要调用 getMessageReactions (Android / iOS & Mac/ Windows) 接口单独拉取。回应信息只支持设置回应 ID，其他信息均不支持设置，SDK 会自动统计使用同一回应 ID 的用户列表。总结：消息回应适合需要统计用户列表的场景，例如表情回应场景，用户添加表情回应只需传入表情 ID，SDK 会自动统计使用同一表情 ID 的用户列表。聊天消息时间格式TUIKit 时间戳展示逻辑（以 Web & uni-app 为例） ：1. 若当前消息与上一条消息间隔超过10分钟，会进行新的时间戳展示，否则归为上一个聊天单元。2. 对于满足条件1，需要展示的时间戳会根据与当前时间的差值进行展示，计算和显示规则如下：差值计算结果显示规则今天时 + 分。示例：8:30昨天昨天 + 时 + 分。示例：昨天 8:30一周内（7天，以天为单位计算）星期 + 时 + 分。示例：星期一 8:30超过一周，在本年内月/日 + 时 + 分。示例：9/1 8:30不在本年年/月/日 + 时 + 分。示例：2024/9/1 8:30为什么同一秒级内的消息，接收方接收消息时，可能存在乱序？原因：1. 终端到 sso 接入机之间走 tcp，这两个节点之间的数据能保证顺序。2. sso 接口机和消息业务服务器之间走 udp，引起乱序的原因之一。3. 乱序不同消息也有可能分发给不同的消息业务服务器处理，引起乱序的原因之二。架构：终端 => sso => 消息业务服务器 => push 服务器 => sso => 终端为什么弱网情况下发送消息失败（实际消息发送成功）？原因：SDK 已经成功把请求包发给后台，但后台的回包在回来的路上被丢掉了。客户端因为没有收到回包，本地将消息状态重置为失败。解决方案：等网络恢复后，拉取漫游历史消息时 SDK 会覆盖之前发送失败的消息（实际发送成功的）。这个问题本质上是 ACK 确认问题。弱网情况下进入聊天“加载历史消息耗时久”，怎么优化？进入聊天页面拉取消息优化方案：1. 每次进入聊天页面，都同时调用 getHistoryMessageList 和（getC2CHistoryMessageList 或 getGroupHistoryMessageList 拉取消息）。2. getHistoryMessageList 接口设置仅拉取本地缓存，当本地存在消息缓存时，仅用于 UI 快速预览。3. getC2CHistoryMessageList 或 getGroupHistoryMessageList 返回的消息作为最终显示的消息（因为这两个接口是将本地和漫游消息做合并之后返回的，所以弱网情况下耗时会久一些）。4. 之后下拉查看历史消息只调用 getC2CHistoryMessageList 或 getGroupHistoryMessageList 即可。（查看历史消息时把 getC2CHistoryMessageList 或 getGroupHistoryMessageList 替换成 getHistoryMessageList 拉漫游也可以。）为什么调用 sendMessage 接口立刻并行设置 localCustomData 内容不生效？SDK 内部限制：不能在 sendMessage 之后同步调用设置，应在 sendMessage 之前或响应回调之后再设置。原因：sendMessage 发送时会将消息内容 Copy 一份，发送成功后才更新内容并存入数据库。语音消息发送成功后，调用 convertVoiceToText 语音转文字接口报 40001 错误，如何解决？IM 服务端针对语音转文字消息有限制，语音文件时长不能超过60s且大小不能超过3MB，否则会报 40001 错误。加载会话列表，实现会话 lastMessage 消息，对于当前登录的用户，如何判断显示已读或未读状态？拉取会话列表，V2TIMConversation 中会携带 getC2CReadTimestamp（已读时间戳、单聊使用）、getGroupReadSequence（已读Sequence，群聊使用）、lastMessage（最后一条消息，可能为空） 这三个。判断单聊会话 lastMessage 是否已读： getC2CReadTimestamp > lastMessage.getTimestamp 表示已读，反之未读。判断群聊会话 lastMessage 是否已读： getGroupReadSequence >= lastMessage.getSeq 表示已读，反之未读。在发消息失败的情况下，怎么获取到失败的 Code 码？在发送消息的回调 catch 里面打印 imError.code，点击查看 接口文档。TUIKit 接入时，群组解散、用户退群或被踢出群，群聊消息会都被清空，如何保留本地缓存的历史消息？以解散群为例，调了 dismissGroup 全员会 onGroupDismissed 回调，TUI 组件在收到 onGroupDismissed 回调里调了删除会话接口 deleteConversation，想保留群聊天记录的话可以注释掉 deleteConversation 的调用，退群或者被踢都类似，移除 deleteConversation 接口调用逻辑。iOS 客户端调用 SDK 的拉取历史消息，msgID 有重复，如何解决？客户端 msgID 由 tinyid + clientTime + random 拼接而成，主要关注下 random 字段赋值。看看消息是不是通过服务端接口发送，Rest API 接口参数 MsgRandom 为上层必填参数，发送时 MsgRandom 不能固定不变，否则会出现 msgID 重复。（通过客户端发送消息不需要设置 random，SDK 内部会确保 random 随机。）Flutter Web 端 UIKit 集成，发送图片报 “Error from TUIKit: Only JPG/PNG/JPEG/GIF images can be uploaded, Code: 2252” 错误。图片格式是 jpg, 还是报错，要如何解决？修改 image_picker 插件版本为：^0.8.5+3。此问题由客户自行解决。IM Flutter Demo Web 端发送无问题。问题原因：IM UIKit 组件中 image_picker 选择图片插件，客户升级使用高版本后报错。Flutter UIKit 接入，发送消息必报错：The message read receipt feature is available only to the Premium Edition. Please upgrade.，如何解决？点击查看 参考文档。IM Harmony SDK 发送图片失败，是什么问题？初始化 IM SDK 传入的 getContext() 要和 缓存是应用根目录传入的 context 一致，否则会报错。将用户拉入黑名单，通过 REST API 指定“被拉黑的用户”给自己发消息时，自己依然能收到，是什么问题？需要在发送消息时，设置对应检验字段才会生效，默认不开启。若要开启，请把消息发送控制选项设置为 WithBlackListCheck，详情请参考 单发单聊消息请求包字段 SendMsgControl 说明。上一篇: 用户资料与关系链相关问题下一篇: 群组相关问题Copyright © 2013-2025 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有深圳市腾讯计算机系统有限公司ICP备案/许可证号：粤B2-20090059粤公网安备44030502008569号腾讯云计算（北京）有限责任公司京ICP证150476号 | 京ICP备11018762号中国站中文International文档“捉虫”活动检视指定产品文档，发现和反馈有效问题，奖！API专项"捉虫"反馈API文档问题，代金券、周边好礼奖不停！文档建议，你提了吗快来使用腾讯云产品文档，提出有效建议，奖！在线咨询目录返回顶部