Manage sessions

A session refers to the logical relation that the ZIM SDK automatically generates when a user sends one-to-one or group messages.

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of session management, allowing you to get the session list, create, update, and delete sessions, and more. With the session management feature, you can obtain and display the one-on-one or group chat list in a chat app, game community, online consulting scenario, and more.

Prerequisites

• Create a project in ZEGOCLOUD Console. Then, contact Technical Support to activate the In-app Chat service, and get the AppID and ServerSecret for SDK integration. The ZIM service permission is not enabled by default. Before using it, please activate the ZIM service by yourself in ZEGOCLOUD Console (for details, please refer to Project Management - In-app Chat), if you cannot activate the ZIM service, please contact ZEGOCLOUD technical support to activate it.
• Get the Token that SDK required for login authentication. For details, see Authentication.
• Integrate the ZIM SDK. For details, see the Integrate the SDK chapter of Send and receive messages.

Get the session list

To know what session you have been joined after login, call the queryConversationListWithConfig method to query the session data list.

To avoid the problem that too many sessions are pulled at a time, which takes a long time and causes slow loading of the session interface, you can customize the number of sessions by setting the ZIMConversationQueryConfig object for paging query when pulling sessions.

Sample method call

- (void)queryConversationListWithConfig:(ZIMConversationQueryConfig *)config callback:(ZIMConversationListQueriedCallback)callback;

Parameter description

Sample code

ZIMConversationQueryConfig *config = [[ZIMConversationQueryConfig alloc] init];
// Session anchor point. Empty indicates that the query starts from the latest.
config.nextConversation = nil;
// The number of queries per page.
config.count = 20;

// Get the session list.
[self.zim queryConversationListWithConfig:config callback:^(NSArray<ZIMConversation *> * _Nonnull conversationList, ZIMError * _Nonnull errorInfo) {
    // Get the results of query the session list.
    if(errorInfo.code == ZIMErrorCodeSuccess) {
      // You will need to save and maintain the session objects in the array.
    } else {
      // ......
    }
}];

The ZIMConversation property

You can customize the UI display of the session list after pulling the session information. The obtained session list information ZIMConversation contains the following properties:

Update session list

After setting up the setEventHandler method and listening for the callback conversationChanged after login, you will receive notifications when:

• A new session is added.
• The last message of a session is updated.
• The total number of unread messages is changed.

At this time, you will need to update the session list by calling the queryConversationListWithConfig method based on your actual needs.

Sample method call

- (void)zim:(ZIM *)zim conversationChanged:(NSArray<ZIMConversationChangeInfo *> *)conversationChangeInfoList;

Parameter description

Sample code

// Set up the event handler and listen for related event callbacks. 
[self.zim setEventHandler:self];

...

- (void)zim:(ZIM *)zim conversationChanged:(NSArray<ZIMConversationChangeInfo *> *)conversationChangeInfoList {
    // Get the session change list.
    for (ZIMConversationChangeInfo *info in conversationChangeInfoList) {
        if (info.event == ZIMConversationEventAdded) {
            // Add to your self-maintained list and set up a UI fresh here.
        } else if (info.event == ZIMConversationEventUpdated) {
           // UI Edit the session properties, and set up a UI fresh here.
        }
    }
}

Clear the number of unread session messages

To clear the number of unread session messages after getting the session list, call the clearConversationUnreadMessageCount method.

You need to call this method when your app user interacts with some pages. The following are some common scenarios to call this method:

• Call this method when you click a session to enter the specific chat interface.
• You keep staying in the same session, and you need to call this method every time you receive new messages.
• Call this method when you want to mark a specified message as read in the session list interface.

Sample method call

- (void)clearConversationUnreadMessageCount:(NSString *)conversationID type:(ZIMConversationType)type callback:(ZIMConversationUnreadMessageCountClearedCallback)callback;

Parameter description

Sample code

// To clear the number of unread messages of specifed session.
[self.zim clearConversationUnreadMessageCount:@"CONV_ID" conversationType: ZIMConversationTypePeer callback:^(ZIMError * _Nonnull errorInfo) {
    // Returned results of the clear operation.
    if(errorInfo.code == ZIMErrorCodeSuccess) {
      // ......
    } else {
      // ......
    }
}];

Get the number of unread messages

To know how many unread messages you currently have after login, listen for the callback conversationTotalUnreadMessageCountUpdated of the setEventHandler method.

After a successful login, the client user is notified of the update of the total number of unread messages through the callback in any of the following situations:

• The user receives a new message and the message notification is enabled for the current session.
• The user proactively clears the number of unread session messages. For details, see the chapter above Clear the number of unread session messages.

With this callback, you can adjust your app's UI display to remind the client user how many messages are currently unread.

Sample method call

- (void)zim:(ZIM *)zim conversationTotalUnreadMessageCountUpdated:(unsigned int)totalUnreadMessageCount;

Parameter description

Sample code

// Set up the event handler and listen for related callbacks.
[self.zim setEventHandler:self];

...

// Callback for getting the total number of unread messages.
- (void)zim:(ZIM *)zim conversationTotalUnreadMessageCountUpdated:(unsigned int)totalUnreadMessageCount {
    // Get the number of unread messages for UI dispaly.
    // ......
}

Mute notifications

Mute notifications: when the ZIM SDK receives a message for the current session, it does not send a push notification, and the total number of unread messages does not increase.

To mute notifications for specified session, call the setConversationNotificationStatus method with the conversationID parameter.

Sample method call

- (void)setConversationNotificationStatus:(ZIMConversationNotificationStatus)status conversationID:(NSString *)conversationID conversationType:(ZIMConversationType)conversationType callback:(ZIMConversationNotificationStatusSetCallback)callback;

Parameter description

Sample code

// Mute notifications for specified sessions.
[self.zim setConversationNotificationStatus:ZIMConversationNotificationStatusDoNotDisturb conversationID:@"CONV_ID" conversationType:ZIMConversationTypePeer callback:^(ZIMError * _Nonnull errorInfo) {
    // Set the callback for the results of mute notifications.
    if(errorInfo.code == ZIMErrorCodeSuccess) {
      // ......
    } else {
      // ......
    }
}];

Delete sessions

To delete the specified session after login, call the deleteConversation with the conversationID parameter.

Sample method call

- (void)deleteConversation:(NSString *)conversationID conversationType:(ZIMConversationType)type config:(ZIMConversationDeleteConfig *)config callback:(ZIMConversationDeletedCallback)callback;

Parameter description

Sample code

// Delete a specified session.
ZIMConversationDeleteConfig *config = [[ZIMConversationDeleteConfig alloc] init];
config.isAlsoDeleteServerConversation = YES;
[self.zim deleteConversation:@"CONV_ID" conversationType: ZIMConversationTypePeer config:config callback:^(ZIMError * _Nonnull errorInfo) {
    // The results of delete a specified result. 
    if(errorInfo.code == ZIMErrorCodeSuccess) {
      // ......
    } else {
      // ......
    }
}];