本地最近会话

功能概述

最近会话列表，即最近联系人列表。当收到新联系人的消息时，SDK会自动生成这个消息对应的本地最近会话。它记录了包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。

原型是RecentContact，接口说明如下：

返回值	RecentContact 接口	说明
MsgAttachment	getAttachment()	获取最近一条消息的附件内容
String	getContactId()	获取最近联系人的 ID（好友帐号，群 ID 等）
String	getContent()	获取最近一条消息的缩略内容
Map	getExtension()	获取最近会话对象的扩展字段
String	getFromAccount()	获取最近一条消息的发送方的帐号
String	getFromNick()	获取与该联系人的最近一条消息的发送方的昵称
MsgStatusEnum	getMsgStatus()	获取最近一条消息状态
MsgTypeEnum	getMsgType()	获取最近一条消息的消息类型
String	getRecentMessageId()	获取最近一条消息的客户端ID，即 IMMessage#getUuid()
SessionTypeEnum	getSessionType()	获取会话类型，是单聊还是群聊等
long	getTag()	获取标签属性
long	getTime()	获取最近一条消息的时间，单位为 ms
int	getUnreadCount()	获取未读消息条数
void	setExtension(Map extension)	设置最近会话对象的扩展字段
void	setMsgStatus(MsgStatusEnum msgStatus)	设置最近一条消息的状态
void	setTag(long tag)	设置一个标签，用于做联系人置顶、最近会话列表排序等扩展用途。

获取最近会话

获取最近会话列表，一般用于首页显示会话列表

获取最近会话列表

异步接口：

/**
 * 查询最近联系人列表数据
 *
 * @return InvocationFuture
 */
public InvocationFuture<List<RecentContact>> queryRecentContacts();

同步接口：

/**
 * 查询最近联系人列表数据(同步接口)
 *
 * @return InvocationFuture
 */
public List<RecentContact> queryRecentContactsBlock();

示例

NIMClient.getService(MsgService.class).queryRecentContacts()
     .setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
       @Override
       public void onResult(int code, List<RecentContact> recents, Throwable e) {
            // recents参数即为最近联系人列表（最近会话列表）
       }
    });

获取最近会话列表(自定义)

过滤指定消息类型

当希望返回的会话的最近一条消息不是某一类消息时，可以使用以下过滤接口。

如希望最近一条消息为非文本消息时，使用该接口的返回的会话，将取最近的一条非文本的消息作为最近一条消息。

异步接口：

/**
 * 查询最近联系人列表数据
 *
 * @return InvocationFuture
 */
public InvocationFuture<List<RecentContact>> queryRecentContacts(MsgTypeEnum filterMsgType);

同步接口：

/**
 * 查询最近联系人列表数据, 过滤指定消息类型(同步接口)
 *
 * @return InvocationFuture
 */
public List<RecentContact> queryRecentContactsBlock(MsgTypeEnum filterMsgType);

示例

 NIMClient.getService(MsgService.class).queryRecentContacts(MsgTypeEnum.text)
     .setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
       @Override
       public void onResult(int code, List<RecentContact> recents, Throwable e) {
            // recents参数即为最近联系人列表（最近会话列表）
       }
    });

获取少量会话

可以获取指定数量的最近会话：

异步接口

/**
 * 查询最近联系人会话列表数据, 可以设置limit， 防止本地会话过多时，导致第一次加载慢
 *
 * @param limit 获取本地会话的数量，最大100，超过100修正到100
 * @return InvocationFuture
 */
InvocationFuture<List<RecentContact>> queryRecentContacts(int limit);

同步接口

/**
 * 查询最近联系人会话列表数据(同步接口)，可以设置limit， 防止本地会话过多时，导致第一次加载慢
 *
 * @param limit 获取本地会话的数量，最大100，超过100修正到100
 */
List<RecentContact> queryRecentContactsBlock(int limit);

示例

NIMClient.getService(MsgService.class).queryRecentContacts(10);

获取指定的最近会话

v5.9.0版本开始，支持通过会话id获取对应的会话。

/**
 * 查询最近联系人会话列表数据(同步接口)，可以设置limit， 防止本地会话过多时，导致第一次加载慢
 * @param contactId - 会话id ，对方帐号或群组id。
 * @param sessionType - 会话类型。
 */
RecentContact queryRecentContact(java.lang.String contactId, SessionTypeEnum sessionType);

创建最近会话

创建一个空的最近会话:

/**
 * @param contactId - 会话id ，对方帐号或群组id。
 * @param sessionType - 会话类型。
 * @param tag - 会话tag ， eg:置顶标签（UIKit中的实现： RECENT_TAG_STICKY） ，用户参照自己的tag 实现即可， 如不需要，传 0 即可。
 * @param time - 会话时间 ，单位为ms。
 * @param saveToDB - 是否需要将会话保存在DB中，注意以下两点：
1，如果已经存在相同的会话（contactId 、sessionType 一样），则不会保存在db中；
2，如果之前不存在相同的会话，且needSaveToDB为true 会触发MsgServiceObserve.observeRecentContact(Observer, boolean)通知；
 */
RecentContact createEmptyRecentContact(java.lang.String contactId,
                                       SessionTypeEnum sessionType,
                                       long tag,
                                       long time,
                                       boolean saveToDB);

此外，当某条消息无对应的本地最近会话时，可以使用以下接口根据消息创建本地最近会话。

/**
 * @param message - 消息。
 * @param needNotify - 是否需要触发MsgServiceObserve.observeRecentContact(Observer, boolean)的通知
 */
void updateRecentByMessage(IMMessage message, boolean needNotify);

更新最近会话

/**
 * 更新一条最近联系人会话的属性。目前可设置的属性有：tag, extension。
 * @param recent - 待更新的最近联系人会话数据
 */
void updateRecent(RecentContact recent);

如果想收到 MsgServiceObserve.observeRecentContact(Observer, boolean) 的通知，可使用以下接口进行更新：

/**
 * 更新一条最近联系人会话的属性。目前可设置的属性有：tag, extension。
 * @param recent - 待更新的最近联系人会话数据
 */
void updateRecentAndNotify(RecentContact recent);

监听最近会话变更

当最近会话对象以及其属性发生变更时，SDK 会更新对应聊天对象的最近联系人资料，并发出最近联系人更新通知。

API 原型

/**
 * 注册/注销最近联系人列表变化观察者
 * @param observer 观察者，参数为变化的最近联系人列表
 * @param register true为注册，false为注销
 */
public void observeRecentContact(Observer<List<RecentContact>> observer, boolean register);

示例

//  创建观察者对象
Observer<List<RecentContact>> messageObserver = new Observer<List<RecentContact>>() {
        @Override
        public void onEvent(List<RecentContact> messages) {

        }
    }
//  注册/注销观察者
NIMClient.getService(MsgServiceObserve.class).observeRecentContact(messageObserver, register);

未读数

获取未读数

获取总未读数

/**
 * 获取未读数总数
 */
public int getTotalUnreadCount();

示例

int unreadNum = NIMClient.getService(MsgService.class).getTotalUnreadCount();

获取单个会话未读数

通过 RecentContact - getUnreadCount() 方法获取。

重置未读数

调用以下接口重置当前会话，SDK会自动管理消息的未读数。该接口会自动调用clearUnreadCount(String, SessionTypeEnum)将正在聊天对象的未读数清零。如果有新消息到达，且消息来源是正在聊天的对象，其未读数也不会递增。

/**
 * 设置当前会话
 * @param account, - 聊天对象帐号，或者以下两个值：MSG_CHATTING_ACCOUNT_ALL与MSG_CHATTING_ACCOUNT_NONE。

 *  @param sessionType  会话类型。如果account不是具体的对象，该参数将被忽略
 */
void setChattingAccount(java.lang.String account, SessionTypeEnum sessionType);

一般在退出聊天界面时，需要恢复更新未读数：

// 恢复更新未读数
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);

如果需要不进入聊天窗口就将未读数清零，可以调用如下接口来实现：

/**
 * 将指定最近联系人的未读数清零(标记已读)。<br>
 * 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
 *
 * @param account     聊天对象帐号
 * @param sessionType 会话类型
 */
void clearUnreadCount(String account, SessionTypeEnum sessionType);

/**
 * 将指定最近联系人的未读数清零(标记已读)。<br>
 * 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
 *
 * @param sessionKeyList     聊天对象帐号，第一个元素为account, 第二个元素为会话类型
 */
void clearUnreadCount(List<Pair<String, SessionTypeEnum>> sessionKeyList);


/**
 * 将所有联系人的未读数清零(标记已读)
 * 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
 */
void clearAllUnreadCount();

未读数多端同步

开启会话的未读数多端同步后，在其中一个客户端读过的会话在其它端也会被标记为已读。

开启方法：设置 SDKOptions - sessionReadAck 属性为 true 。

删除最近会话

SDK 支持删除指定的本地和云端最近会话。但会保留会话内的消息。调用时，总未读消息数会减去当前会话的未读数。

API 介绍

MsgService 提供了三种方法：其中deleteRecentContact(RecentContact) 和 deleteRecentContact2(String, SessionTypeEnum)的区别在于后者会触发 MsgServiceObserve#observeRecentContactDeleted 通知。另一个接口不会触发MsgServiceObserve#observeRecentContactDeleted，而且可以配置是否同时删除漫游消息

API 原型

不触发观察者通知版本:

/**
 * 从最近联系人列表中删除一项。
 * 调用这个接口删除数据后，不会引发观察者通知。
 *
 * @param recent 待删除的最近联系人项
 */
public void deleteRecentContact(RecentContact recent);

触发观察者通知版本:

/**
 * 删除最近联系人记录。
 * 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContactDeleted(Observer, boolean)}通知
 *
 * @param account
 * @param sessionType
 */
public void deleteRecentContact2(String account, SessionTypeEnum sessionType);

可配置版本：

/**
 * 删除最近联系人记录。<br>
 *
 * @param account     会话ID
 * @param sessionType 会话类型，只能选{@link SessionTypeEnum#P2P}和{@link SessionTypeEnum#Team}会删漫游消息
 * @param deleteType  删除类型，决定是否删除本地记录和漫游记录，
 *                    如果为null，视为{@link DeleteTypeEnum#REMAIN}
 * @param sendAck     如果参数合法，是否向其他端标记此会话为已读
 */
InvocationFuture<Void> deleteRecentContact(String account, SessionTypeEnum sessionType, DeleteTypeEnum deleteType, boolean sendAck);

示例

// 不触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact(recent);
//触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact2(account, SessionTypeEnum.P2P);
// 可配置版本，配置既删本地会话，也删除漫游消息。而且要发送ACK
NIMClient.getService(MsgService.class).deleteRecentContact(sessionId, sessionType, DeleteTypeEnum.LOCAL_AND_REMOTE, true)
                    .setCallback(deleteRecentCallback);

删除漫游消息

SDK 支持删除指定联系人的漫游消息，可以通过以下方法实现：

API 原型

/**
 * 删除指定最近联系人的漫游消息。
 * 不删除本地消息，但如果在其他端登录，当前时间点该会话已经产生的消息不漫游。
 *
 * @return InvocationFuture 可设置回调函数，监听删除结果。
 */
public InvocationFuture<Void> deleteRoamingRecentContact(String contactId, SessionTypeEnum sessionTypeEnum);

参数说明

参数	说明
contactId	最近联系人的 ID（好友帐号，群 ID 等）
sessionTypeEnum	会话类型

示例

NIMClient.getService(MsgService.class)
         .deleteRoamingRecentContact(contactId, sessionTypeEnum)
         .setCallback(new RequestCallback<Void>() { ... });

本篇文档内容是否对您有帮助？

有帮助

我要吐槽

您的改进建议

问题类型

内容错误内容没更新描述不清链接有误步骤不完整内容缺失（缺少代码/示例）其他

更多建议

请输入您的建议或问题（至少5个字符，至多500个字符）

联系方式

标记内容

同时提交标记内容

此文档对你是否有帮助

有帮助

我要吐槽

反馈成功

非常感谢您的反馈，我们会继续努力做得更好。

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志

本地最近会话

功能概述

获取最近会话

获取最近会话列表

获取最近会话列表(自定义)

过滤指定消息类型

获取少量会话

获取指定的最近会话

创建最近会话

更新最近会话

更新最近会话

监听最近会话变更

未读数

获取未读数

获取总未读数

获取单个会话未读数

重置未读数

未读数多端同步

删除最近会话

删除最近会话

删除漫游消息

您的改进建议

此文档对你是否有帮助

反馈成功

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志

本地最近会话

功能概述

获取最近会话

获取最近会话列表

获取最近会话列表(自定义)

过滤指定消息类型

获取少量会话

获取指定的最近会话

创建最近会话

更新最近会话

更新最近会话

监听最近会话变更

未读数

获取未读数

获取总未读数

获取单个会话未读数

重置未读数

未读数多端同步

删除最近会话

删除最近会话

删除漫游消息

相关文档

相关产品

您的改进建议

此文档对你是否有帮助

反馈成功