Receive messages

Set up message handlers to intercept and process incoming messages.

Register a message handler

The Chat SDK uses a handler-based model. Register a message handler with a unique identifier after SDK initialization, ideally before connecting:

tip

• Register before calling connect to ensure offline messages are received immediately.
• Use a persistent object (for example, a view controller or a singleton service) as the handler to avoid premature deallocation.
• Registering with the same identifier twice overwrites the previous handler.

Swift

swift

import NexconnChatSDK

NCEngine.addMessageHandler(identifier: "YourUniqueKey", handler: self)

Objective-C

Objective C

[NCEngine addMessageHandlerWithIdentifier:@"YourUniqueKey" handler:self];

Implement the MessageHandler protocol

Your handler class must conform to MessageHandler. All callback methods are optional:

Swift

swift

import NexconnChatSDK

final class YourClass: NSObject, MessageHandler {
    func onMessageReceived(_ event: MessageReceivedEvent) {
        guard let message = event.message else { return }

        print("Received message: \(message.messageId)")
        print("Remaining in batch: \(event.left), offline: \(event.offline), hasPackage: \(event.hasPackage)")
    }

    func onOfflineMessageSyncCompleted(_ event: OfflineMessageSyncCompletedEvent) {
        print("Offline message sync completed.")
    }

    func onMessageDeleted(_ event: MessageDeletedEvent) {
        print("Deleted messages: \(event.messages?.count ?? 0)")
    }

    func onMessagesModified(_ event: MessagesModifiedEvent) {
        print("Modified messages: \(event.messages.count)")
    }
}

Objective-C

Objective C

@interface YourClass () <NCMessageHandler>
@end

@implementation YourClass

- (void)onMessageReceived:(NCMessageReceivedEvent *)event {
    // event.left: remaining messages not yet delivered in this batch
    // event.offline: whether this is an offline (missed) message
    // event.hasPackage: whether the server still has unpulled message batches
    if (event.left == 0) {
        // All pending messages delivered — safe to refresh UI
    }
}

- (void)onOfflineMessageSyncCompleted:(NCOfflineMessageSyncCompletedEvent *)event {
    // All offline messages have been synced
}

- (void)onMessageDeleted:(NCMessageDeletedEvent *)event {
    // event.messages: the deleted messages
}

- (void)onMessagesModified:(NCMessagesModifiedEvent *)event {
    // event.messages: the modified messages
}

@end

Remove a message handler

Remove the handler when it is no longer needed (for example, in dealloc or viewDidDisappear:):

Swift

swift

import NexconnChatSDK

NCEngine.removeMessageHandler(forIdentifier: "YourUniqueKey")

Objective-C

Objective C

[NCEngine removeMessageHandlerForIdentifier:@"YourUniqueKey"];

Message received status

The receivedStatusInfo property on NCMessage tracks the receiving state (read, listened, downloaded, and retrieved):

Swift

swift

import NexconnChatSDK

let message = /* message object from callback */
let statusInfo = message.receivedStatusInfo
let isRead = statusInfo.isRead
let isListened = statusInfo.isListened
let isDownloaded = statusInfo.isDownloaded
let isRetrieved = statusInfo.isRetrieved

Objective-C

Objective C

NCMessage *message = /* message object from callback */;
NCMessageReceivedStatusInfo *statusInfo = message.receivedStatusInfo;
BOOL isRead = statusInfo.isRead;
BOOL isListened = statusInfo.isListened;
BOOL isDownloaded = statusInfo.isDownloaded;
BOOL isRetrieved = statusInfo.isRetrieved;

Update received status

Call setReceivedStatusInfo(_:completion:) on the message instance to persist the updated state:

Swift

swift

import NexconnChatSDK

let statusInfo = MessageReceivedStatusInfo()
statusInfo.isRead = true

message.setReceivedStatusInfo(statusInfo) { isUpdated, error in
    if isUpdated {
        print("Received status updated.")
    } else {
        print("Failed to update received status: \(error?.localizedDescription ?? "unknown error")")
    }
}

Objective-C

Objective C

NCMessageReceivedStatusInfo *statusInfo = [[NCMessageReceivedStatusInfo alloc] init];
statusInfo.isRead = YES;

[message setReceivedStatusInfo:statusInfo completion:^(BOOL isUpdated, NCError * _Nullable error) {
    // isUpdated == YES on success
}];