单聊消息
单发单聊消息
- 管理员向账号发消息,接收方看到消息发送者是管理员。
- 管理员指定某一账号向其他账号发消息,接收方看到发送者不是管理员,而是管理员指定的账号。
- 该接口不会检查发送者和接收者的好友关系(包括黑名单),同时不会检查接收者是否被禁言。
- 该接口默认不会检查接收者对发送者是否设置了免打扰,如需检查,请在"SendMsgControl"字段填上"WithMuteNotifications"。
- 单聊消息 MsgSeq 字段的作用及说明:该字段在发送消息时由用户自行指定,该值可以重复,非后台生成,非全局唯一。与群聊消息的 MsgSeq 字段不同,群聊消息的 MsgSeq 由后台生成,每个群都维护一个 MsgSeq,从 1 开始严格递增。单聊消息历史记录对同一个会话的消息先以时间戳排序,同秒内的消息再以 MsgSeq 排序。
使用示例:
TIMTextMsgElement msg = new TIMTextMsgElement("hello world");
List<TIMMsgElement> msgBody = Collections.singletonList(msg);
SendMsgRequest request = SendMsgRequest.builder()
.fromAccount("test1")
.toAccount("test2")
.msgRandom(123L)
.msgBody(msgBody)
.syncOtherMachine(SyncOtherMachine.YES)
.msgTimeStamp(1631934058)
.msgLifeTime(604800)
.build();
SendMsgResult result = client.message.sendMsg(request);
批量发单聊消息
- 支持一次对最多 500 个用户进行单发消息。
- 与单发消息相比,该接口更适用于营销类消息、系统通知 tips 等时效性较强的消息。
- 若消息不需要计入未读数,也不需要存储聊天记录,则可将 MsgLifeTime 字段设置为 0,这样可以带来更快的消息下发速度。
- 管理员指定某一账号向目标账号批量发消息,接收方看到发送者不是管理员,而是管理员指定的账号。
- 该接口不触发回调请求。
- 该接口不会检查发送者和接收者的好友关系(包括黑名单),同时不会检查接收者是否被禁言。
- 该接口默认不会检查接收者对发送者是否设置了免打扰,如需检查,请在"SendMsgControl"字段填上"WithMuteNotifications"。
- 单聊消息 MsgSeq 字段的作用及说明:该字段在发送消息时由用户自行指定,该值可以重复,非后台生成,非全局唯一。与群聊消息的 MsgSeq 字段不同,群聊消息的 MsgSeq 由后台生成,每个群都维护一个 MsgSeq,从 1 开始严格递增。单聊消息历史记录对同一个会话的消息先以时间戳排序,同秒内的消息再以 MsgSeq 排序。
使用示例:
List<String> toAccount = Arrays.asList("test1", "test2");
TIMTextMsgElement msg = new TIMTextMsgElement("hi bingo");
List<TIMMsgElement> msgBody = Collections.singletonList(msg);
BatchSendMsgRequest request = BatchSendMsgRequest
.builder()
.toAccount(toAccount)
.msgRandom(123L)
.msgBody(msgBody)
.syncOtherMachine(SyncOtherMachine.NO)
.msgSeq(28460L)
.build();
BatchSendMsgResult result = client.message.batchSendMsg(request);
导入单聊消息
- 导入历史单聊消息到即时通信 IM。
- 平滑过渡期间,将原有即时通信实时单聊消息导入到即时通信 IM。
- 该接口会更新会话。
- 该接口不会触发回调。
- 对于同一个单聊会话的消息,该接口会根据 MsgSeq , MsgRandom , MsgTimeStamp 字段的值对导入的消息进行去重。仅当这三个字段的值都对应相同时,才判定消息是重复的,消息是否重复与消息内容本身无关。 另外,若两条消息的 MsgSeq , MsgRandom , MsgTimeStamp 字段对应相同,而 from_account 和 to_account 相反,则这两条消息也认为是重复的。
- 重复导入的消息不会覆盖之前已导入的消息(即消息内容以首次导入的为准)。
- 单聊消息 MsgSeq 字段的作用及说明:该字段在发送消息时由用户自行指定,该值可以重复,非后台生成,非全局唯一。与群聊消息的 MsgSeq 字段不同,群聊消息的 MsgSeq 由后台生成,每个群都维护一个 MsgSeq,从 1 开始严格递增。单聊消息历史记录对同一个会话的消息先以时间戳排序,同秒内的消息再以 MsgSeq 排序。
使用示例:
TIMTextMsgElement msg = new TIMTextMsgElement("hello bingo");
List<TIMMsgElement> msgBody = Collections.singletonList(msg);
ImportMsgRequest request = ImportMsgRequest.builder()
.fromAccount("bingo")
.toAccount("test1")
.msgRandom(122L)
.msgTimeStamp(1557387418)
.msgBody(msgBody)
.build();
ImportMsgResult result = client.message.importMsg(request);
查询单聊消息
- 管理员按照时间范围查询某单聊会话的消息记录。
- 查询的单聊会话由请求中的 From_Account 和 To_Account 指定。查询结果包含会话双方互相发送的消息,具体每条消息的发送方和接收方由每条消息里的 From_Account 和 To_Account 指定。
- 一般情况下,请求中的 From_Account 和 To_Account 字段值互换,查询结果不变。但通过 单发单聊消息 或 批量发单聊消息 接口发送的消息,如果指定 SyncOtherMachine 值为 2,则需要指定正确的 From_Account 和 To_Account 字段值才能查询到该消息。 例如,通过 单发单聊消息 接口指定账号 A 给账号 B 发一条消息,同时指定 SyncOtherMachine 值为 2。则调用本接口时,From_Account 必须设置为账号 B,To_Account 必须设置为账号 A 才能查询到该消息。
- 查询结果包含被撤回的消息,由消息里的 MsgFlagBits 字段标识。
- 若想通过 撤回单聊消息 接口撤回某条消息,可先用本接口查询出该消息的 MsgKey,然后再调用撤回接口进行撤回。
- 可查询的消息记录的时间范围取决于漫游消息存储时长,默认是 7 天。支持在控制台修改消息漫游时长,延长消息漫游时长是增值服务。具体请参考 漫游消息存储。
- 若请求时间段内的消息总大小超过应答包体大小限制(目前为 13K)时,则需要续拉。您可以通过应答中的 Complete 字段查看是否已拉取请求的全部消息。
使用示例:
AdminGetRoamMsgRequest request = AdminGetRoamMsgRequest.builder()
.fromAccount("test1")
.toAccount("test2")
.maxCnt(123)
.minTime(1631934000)
.maxTime(1631934060)
.build();
AdminRoamMsgResult result = client.message.getRoamMsg(request);
List<MsgListItem> msgList = result.getMsgList();
if (msgList != null && msgList.size() > 0) {
for (MsgListItem item : msgList) {
List<TIMMsgElement> msgBody = item.getMsgBody();
if (msgBody != null && msgList.size() > 0) {
for (TIMMsgElement msgElement : msgBody) {
// 根据 msgType 强转为对应的子类
if (Objects.equals(msgElement.getMsgType(), MsgType.TIM_CUSTOM_ELEM)) {
TIMCustomMsgElement t = (TIMCustomMsgElement) msgElement;
System.out.println(t.getMsgContent().getDesc());
} else if (Objects.equals(msgElement.getMsgType(), MsgType.TIM_TEXT_ELEM)) {
TIMTextMsgElement t = (TIMTextMsgElement) msgElement;
System.out.println(t.getMsgContent().getText());
}
}
}
}
}
撤回单聊消息
- 管理员撤回单聊消息。
- 该接口可以撤回所有单聊消息,包括客户端发出的单聊消息,由 单发 和 批量发 接口发出的单聊消息。
- 若需要撤回由客户端发出的单聊消息,您可以开通 发单聊消息之前回调 或 发单聊消息之后回调 ,通过该回调接口记录每条单聊消息的 MsgKey ,然后填在本接口的 MsgKey 字段进行撤回。您也可以通过 查询单聊消息 查询出待撤回的单聊消息的 MsgKey 后,填在本接口的 MsgKey 字段进行撤回。
- 若需要撤回由 单发 和 批量发 接口发出的单聊消息,需要记录这些接口回包里的 MsgKey 字段以进行撤回。
- 调用该接口撤回消息后,该条消息的离线、漫游存储,以及消息发送方和接收方的客户端的本地缓存都会被撤回。
- 该接口可撤回的单聊消息没有时间限制,即可以撤回任何时间的单聊消息。
注意
使用该接口撤回单聊消息后,被撤回的消息不能恢复,请谨慎调用该接口。
使用示例:
AdminMsgWithdrawRequest request = AdminMsgWithdrawRequest.builder()
.fromAccount("test1")
.toAccount("bingo")
.msgKey("31906_833502_1572869830")
.build();
AdminMsgWithdrawResult result = client.message.msgWithdraw(request);
设置单聊消息已读
- 设置用户的某个单聊会话的消息已读。
使用示例:
AdminSetMsgReadRequest request = AdminSetMsgReadRequest.builder()
.reportAccount("test1")
.peerAccount("test2")
.build();
AdminSetMsgReadResult result = client.message.setMsgRead(request);
查询单聊未读消息计数
App 后台可以通过该接口查询特定账号的单聊总未读数(包含所有的单聊会话)或者单个单聊会话的未读数。
使用示例:
GetC2cUnreadMsgRequest request = new GetC2cUnreadMsgRequest("test2");
List<String> peerAccount = Arrays.asList("test1", "bingo");
request.setPeerAccount(peerAccount);
C2cUnreadMsgNumResult result = client.message.getC2cUnreadMsgNum(request);
修改单聊历史消息
- 管理员修改单聊历史消息。
- 可以单独修改消息中的 MsgBody 或 CloudCustomData 字段,也可以同时修改这两个字段。以请求中指定的字段值覆盖历史消息对应的字段。
- 待修改的单聊消息的 MsgKey 可通过以下方式获取:
注意
使用该接口修改消息后,被修改的消息不能恢复,请谨慎调用该接口。
使用示例:
TIMTextMsgElement msg = new TIMTextMsgElement("test modify c2c msg");
List<TIMMsgElement> msgBody = Collections.singletonList(msg);
ModifyC2cMsgRequest request = ModifyC2cMsgRequest.builder()
.fromAccount("test1")
.toAccount("test2")
.msgKey("1353691732_123_1653995506")
.msgBody(msgBody)
.build();
ModifyC2cMsgResult result = client.message.modifyC2cMsg(request);
拉取单聊消息扩展
App 管理员和会话成员可以拉取消息扩展,消息扩展为一组自定义的键值对。
注意
- 此功能需 旗舰版套餐,并且已开通“消息扩展功能”功能(控制台“登录与消息”配置)。
- 单条单聊消息可设置的最大键值对数量为 300 条。
- 被设置的单聊消息需要在发送时指定“支持消息扩展”,参见 单发单聊消息。
使用示例:
GetKeyValuesRequest request = GetKeyValuesRequest.builder()
.fromAccount("test1")
.toAccount("bingo")
.msgKey("1353691732_123_1653995506")
.startSeq(1L)
.build();
GetKeyValuesResult result = client.message.getKeyValues(request);
设置单聊消息扩展
App 管理员和会话成员可以为单聊普通消息设置消息扩展,消息扩展为一组自定义的键值对。
注意
- 此功能需 旗舰版套餐,并且已开通“消息扩展功能”功能(控制台“登录与消息”配置)。
- 单条单聊消息可设置的最大键值对数量为 300 条。
- 被设置的单聊消息需要在发送时指定“支持消息扩展”,参见 单发单聊消息。
使用示例:
SetKeyValuesRequest request = SetKeyValuesRequest.builder()
.fromAccount("test1")
.toAccount("bingo")
.msgKey("1353691732_123_1653995506")
.build();
SetKeyValuesResult result = client.message.setKeyValues(request);
单向删除单聊历史消息
- App 管理员调用该接口单向删除一个单聊会话的多条消息。
- 只能以消息的发送方或接收方的身份去删除单聊会话的历史消息。
- 只能单向删除(以会话其中一方的身份去删除某条消息后,自己看不到这条消息,会话的对方仍然可以看到这条消息)
使用示例:
DeleteC2cMsgRambleRequest request = DeleteC2cMsgRambleRequest.builder()
.operatorAccount("test1")
.peerAccount("test2")
.msgKeyList(Collections.singletonList("1353691732_123_1653995506"))
.build();
DeleteC2cMsgRambleResult result = client.message.deleteC2cMsgRamble(request);
清空群聊历史消息
该 API 接口的作用是清空群聊中用户发送的历史消息。
此接口通过打标记实现 SDK 无法拉取的效果,并没有真的执行删除操作,Admin 用户仍然可以通过“拉取群聊历史消息”接口拉取已清空的历史消息。
使用示例:
ClearGroupMsgRequest request = ClearGroupMsgRequest.builder()
.groupId("test_group")
.msgSeq(123L)
.build();
ClearGroupMsgResult result = client.message.clearGroupMsg(request);