Overview

Recent session list is the list of recent contacts. When a message is received from a new contact, the SDK will automatically generate a local recent session. It records account and type of contact, time of recent message, status, content, and unread count.

Prototype RecentContact. interface:

Return	RecentContact interface	Description
MsgAttachment	getAttachment()	Get attachment of the recent message.
String	getContactId()	Get recent contact ID (friend's account, team ID.).
String	getContent()	Get brief content of the recent message.
Map	getExtension()	Get the extension field of the recent session object.
String	getFromAccount()	Get sender account of the recent message.
String	getFromNick()	Get sender display name of the recent message with the contact.
MsgStatusEnum	getMsgStatus()	Get state of the recent message.
MsgTypeEnum	getMsgType()	Get type of the recent message.
String	getRecentMessageId()	Get client ID of the recent message, i.e. IMMessage#getUuid().
SessionTypeEnum	getSessionType()	Get session type (one-to-one chat or team chat).
long	getTag()	Get tag attribute.
long	getTime()	Get time of the recent message, unit: ms.
int	getUnreadCount()	Get unread count.
void	setExtension(Map extension)	Set extension field of the recent session object.
void	setMsgStatus(MsgStatusEnum msgStatus)	Set the recent message status.
void	setTag(long tag)	Sticky tag for extension purposes, for example, setting contacts to top, ranking recent session list.

Getting the most recent session

Get the recent session list for display session list on home page.

Getting the most recent sessions

• Asynchronous interface:

java/**
 * Query the list of recent contacts.
 *
 * @return InvocationFuture.
 */
public InvocationFuture<List<RecentContact>> queryRecentContacts();

• Synchronous interface:

java/**
 * Query the list of recent contacts (synchronous interface).
 *
 * @return InvocationFuture.
 */
public List<RecentContact> queryRecentContactsBlock();

• Example

javaNIMClient.getService(MsgService.class).queryRecentContacts()
	.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
	   @Override
       public void onResult(int code, List<RecentContact> recents, Throwable e) {
            The parameter "// recents" is the list of recent contacts (list of recent sessions)
       }
    });

Geting recent session list (custom)

Filtering messages of specified type

If the recent message of returned session is not a certain type of message, the following filtering interface can be used.

If the recent message is not text message, then returned session from the interface is used and the recent non-text message is taken as the recent message.

• Asynchronous interface:

java/**
 * Query the list of recent contacts.
 *
 * @return InvocationFuture.
 */
public InvocationFuture<List<RecentContact>> queryRecentContacts(MsgTypeEnum filterMsgType);

• Synchronous interface:

java/**
 * Query the list of recent contacts, and filter specified message type (synchronous interface).
 *
 * @return InvocationFuture
 */
public List<RecentContact> queryRecentContactsBlock(MsgTypeEnum filterMsgType);

• Example

java NIMClient.getService(MsgService.class).queryRecentContacts(MsgTypeEnum.text)
	.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
	   @Override
       public void onResult(int code, List<RecentContact> recents, Throwable e) {
            The parameter "// recents" is the list of recent contacts (list of recent sessions)
       }
    });

Getting a few sessions

Get specified number of recent sessions:

• Asynchronous interface

java/**
 * Query the list of sessions with recent contacts. It can be set with limit to avoid slow loading for the first time due to more local sessions.
 *
 * "@param limit" is to get count of local sessions, with max. count 100. Otherwise, it will be modified to 100.
 * @return InvocationFuture
 */
InvocationFuture<List<RecentContact>> queryRecentContacts(int limit);

• Synchronous interface

java/**
 * Query the list of sessions with recent contacts (synchronous interface). It can be set with limit to avoid slow loading for the first time due to more local sessions.
 *
 * "@param limit" is to get count of local sessions, with max. count 100. Otherwise, it will be modified to 100.
 */
List<RecentContact> queryRecentContactsBlock(int limit);

• Example

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

Get the specified recent session

Starting with v5.9.0, you can get the corresponding sessions by session ID.

java/**
 * Query the list of sessions with recent contacts (synchronous interface). It can be set with limit to avoid slow loading for the first time due to more local sessions.
 * @param contactId - Session id, account of the other party or team ID.
 * @param sessionType - Session type.
 */
RecentContact queryRecentContact(java.lang.String contactId, SessionTypeEnum sessionType);

Creating a recent session

• Create an empty recent session:

java/**
 * Create an empty contact session
 *
 * @param contactId - Session id, account of the other party or team id.
 * @param sessionType session type
 * @param tag     Session tag, eg: sticky tag (implementation in UIKit: RECENT_TAG_STICKY). Users can implement as per their own tag. Otherwise, 0 must be input. <br/>
 * @param time    Session time, unit: ms.
 * @param saveToDB - It determines to store the session in DB. Notes: <br/>
 * 1. If there is the same session (with same contactId and sessionType), it will not be stored in db; <br/>
 * 2. If there is not the same session and needSaveToDB is true, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
 *          <b/>
 * @return InvocationFuture<RecentContact>
 */
RecentContact createEmptyRecentContact(String contactId, SessionTypeEnum sessionType, long tag, long time,
                                       boolean saveToDB);

• Configure the interface from which the final message searched from the local database is input.

java/**
 * Create an empty contact session
 *
 * @param contactId - Session id, account of the other party or team id.
 * @param sessionType session type.
 * @param tag     Session tag, eg: sticky tag (implementation in UIKit: RECENT_TAG_STICKY). Users can implement as per their own tag. Otherwise, 0 must be input. <br/>
 * @param time    Session time, unit: ms.
 * @param saveToDB - It determines to store the session in DB. Notes: <br/>
 * 1. If there is the same session (with same contactId and sessionType), it will not be stored in db; <br/>
 * 2. If there is not the same session and needSaveToDB is true, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
 *          <b/>
 * @param withLastMsg - It determines to input related information about the final message.
 * @return InvocationFuture<RecentContact>
 */
RecentContact createEmptyRecentContact(String contactId, SessionTypeEnum sessionType, long tag, long time,
                                       boolean saveToDB, boolean withLastMsg);

If a message has no corresponding recent local session, the recent local session can be created upon message using the following interface.

java/**
 * @param message - Message.
 * @param needNotify - It determines to trigger notification of MsgServiceObserve.observeRecentContact(Observer, boolean).
 */
void updateRecentByMessage(IMMessage message, boolean needNotify);

Updating recent sessions

Updating recent sessions

java/**
 * Update attributes of a session with recent contact Now,
 * @param recent - Data of session with recent contact to be updated.
 */
void updateRecent(RecentContact recent);

If you want to receive the notification of MsgServiceObserve.observeRecentContact(Observer, boolean), update can be made using the following interface:

java/**
 * Update attributes of a session with recent contact Now
 * @param recent - Data of session with recent contact to be updated.
 */
void updateRecentAndNotify(RecentContact recent);

Listening for changes of recent sessions

If the recent session object and its attributes have any change, SDK will update information about recent contact of corresponding chat object and send update notification of recent contact.

• API prototype

java/**
 * Register or cancel observer for change in the list of recent contacts
 * @param observer - Observer. The parameter is the list of changed recent contacts.
 * @param register true indicates registered, and true indicates unregistered.
 */
public void observeRecentContact(Observer<List<RecentContact>> observer, boolean register);

• Example

java// Create observer object
Observer<List<RecentContact>> messageObserver = new Observer<List<RecentContact>>() {
	    @Override
	    public void onEvent(List<RecentContact> messages) {

	    }
    }
// Register or cancel observer
NIMClient.getService(MsgServiceObserve.class).observeRecentContact(messageObserver, register);

Unread count

Get the unread count

Get the total unread count

java/**
 * Get total unread count.
 */
public int getTotalUnreadCount();

Example

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

Getting the number of unread count in a session

by RecentContact - getUnreadCount() method.

Resetting the unread count

When you call the following interface to reset current session, SDK will manage the unread count automatically. The interface will call clearUnreadCount(String, SessionTypeEnum) automatically to clear the unread count for the object who is chatting. If there is new message from the object who is chatting, the unread count will not increase.

java/**
 * Set current session.
 * @param account, - Account of chat object, or the following two values: MSG_CHATTING_ACCOUNT_ALL and MSG_CHATTING_ACCOUNT_NONE.

 * @param sessionType Session type. If account is not the detailed object, the parameter will be ignored.
 */
void setChattingAccount(java.lang.String account, SessionTypeEnum sessionType);

Generally, the unread count must be recovered when leaving the chat interface:

java// Recover to update unread count.
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);

If the unread count is cleared without joining chat window, the following interface can be called to implement:

java/**
 * Clear unread count of specified recent contact (marked as "read"). <br>
 * If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
 *
 * @param account - Account of chat room object
 * @param sessionType session type
 * @return - Send ack result
 */
InvocationFuture<Void> clearUnreadCount(String account, SessionTypeEnum sessionType);

/**
 * Clear unread count of specified recent contact (marked as "read"). <br>
 * If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
 *
 * @param sessionKeyList - List of accounts of chat object. For {@link Pair}, the first option is session ID and the second option is session type.
 * The session type supports to input {@link SessionTypeEnum#peer-to-peer} and {@link SessionTypeEnum#Team}.
 * @return - Send ack result. Elements in the list are failed parts.
 */
InvocationFuture<List<SessionAckInfo>> clearUnreadCount(List<Pair<String, SessionTypeEnum>> sessionKeyList);

/**
 * Clear unread count of all contact (marked as "read")
 * If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
 */
void clearAllUnreadCount();

Syncing the unread count on multiple devices

When the multi-client synchronization for number of unread session is enabled, the session read from one client will also be marked as "Read" in other clients.

Enable method: Setting SDKOptions - sessionReadAck attribute to true.

Deleting recent sessions

Deleting a recent session

The SDK allows you to delete specified recent local and cloud session. However, messages in the session will be retained. When it is called, the total unread count will subtract the number of current unread session.

MsgService provides three methods: The distinction between deleteRecentContact(RecentContact) and deleteRecentContact2(String, SessionTypeEnum) is that the latter can trigger notification "MsgServiceObserve#observeRecentContactDeleted". The other interface cannot trigger "MsgServiceObserve#observeRecentContactDeleted", but support to set whether to delete roaming message simultaneously.

• API prototype

Version without triggering observer notification:

java/**
 * Delete one option in the list of recent contacts.
 * Invoke the interface to delete data will not generate observer notification.
 *
 * @param recent - Option of recent contact to be deleted.
 */
public void deleteRecentContact(RecentContact recent);

Version triggering observer notification:

java/**
 * Delete history of recent contact.
 * If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContactDeleted(Observer, boolean)} will be triggered.
 *
 * @param account
 * @param sessionType
 */
public void deleteRecentContact2(String account, SessionTypeEnum sessionType);

Configurable version:

java/**
 * Delete history of recent contact.<br>
 *
 * @param account - Session ID.
 * @param sessionType - Session type. Only {@link SessionTypeEnum#peer-to-peer} and {@link SessionTypeEnum#Team} can be selected, and roaming message will be deleted.
 * @param deleteType - Deletion type. It determines to delete local history and roaming history.
 * If the value is null, it is considered as {@link DeleteTypeEnum#REMAIN}.
 * @param sendAck - It determines to mark the session as "read" at other clients if the parameter is legal.
 */
InvocationFuture<Void> deleteRecentContact(String account, SessionTypeEnum sessionType, DeleteTypeEnum deleteType, boolean sendAck);

• Example

java// Not trigger the observer notification version.
NIMClient.getService(MsgService.class).deleteRecentContact(recent);
// Trigger the observer notification version.
NIMClient.getService(MsgService.class).deleteRecentContact2(account, SessionTypeEnum.peer-to-peer);
// Configurable version. It is configured to delete local session and roaming message. Besides, ACK must be sent.
NIMClient.getService(MsgService.class).deleteRecentContact(sessionId, sessionType, DeleteTypeEnum.LOCAL_AND_REMOTE, true)
                   .setCallback(deleteRecentCallback);

Delete roaming messages

The SDK allows you to delete roaming message of specified contact by the following method:

• API prototype

java/**
 * Delete roaming messages that belong to specified recent contact.
 * Not delete local message. If login occurs at other clients, messages generated in the session at current time point will not be roamed.
 *
 * @return InvocationFuture - Configurable callback feature. It can monitor the deletion result.
 */
public InvocationFuture<Void> deleteRoamingRecentContact(String contactId, SessionTypeEnum sessionTypeEnum);

• Parameters

Parameter	Description
contactId	ID of recent contact (friend ID, team ID.)
sessionTypeEnum	Session type

• Example

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