Manage message metadata

Message metadata adds key-value status data to messages. Use it for features like order status tracking, gift claiming, or message reactions.

tip

• Supported in direct, group, and community channels only.
• Max 20 key-value pairs per update, 300 total per message.
• Each update generates an internal notification message.

Listen for metadata changes

Register an NCMessageHandler and implement the optional metadata callbacks:

Swift

swift

import NexconnChatSDK
final class MyMessageHandler: NSObject, MessageHandler {
    func onMessageMetadataUpdated(_ event: MessageMetadataUpdatedEvent) {
        // event.metadata: the updated key-value pairs
        // event.message: the related message object
    }

    func onMessageMetadataDeleted(_ event: MessageMetadataDeletedEvent) {
        // event.keys: the removed keys
        // event.message: the related message object
    }
}

let handler = MyMessageHandler()
NCEngine.addMessageHandler(identifier: "YourKey", handler: handler)

Objective-C

Objective C

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

- (void)onMessageMetadataUpdated:(NCMessageMetadataUpdatedEvent *)event {
    // event.metadata: the updated key-value pairs
    // event.message: the related message object
}

- (void)onMessageMetadataDeleted:(NCMessageMetadataDeletedEvent *)event {
    // event.keys: the removed keys
    // event.message: the related message object
}

Set metadata (at send time)

Pass the initial metadata via NCSendMessageParams.metadata before sending:

Swift

swift

import NexconnChatSDK
let txt = TextMessage(text: "Order #12345")
let params = SendMessageParams(content: txt)
params.metadata = ["orderStatus": "pending"]
guard let channel = DirectChannel(channelId: "targetUserId") else { return }
channel.sendMessage(params: params, attachedHandler: nil, completionHandler: nil)

Objective-C

Objective C

NCTextMessage *txt = [[NCTextMessage alloc] initWithText:@"Order #12345"];
NCSendMessageParams *params = [[NCSendMessageParams alloc] initWithContent:txt];
params.metadata = @{@"orderStatus": @"pending"};

NCDirectChannel *channel = [[NCDirectChannel alloc] initWithChannelId:@"targetUserId"];
[channel sendMessageWithParams:params attachedHandler:nil completionHandler:nil];

Update metadata (after sending)

Call setMetadata:completion: on the sent NCMessage instance:

Swift

swift

import NexconnChatSDK
message.setMetadata(["orderStatus": "confirmed"]) { error in
    if error == nil {
        // Updated — refresh UI
    }
}

Objective-C

Objective C

[message setMetadata:@{@"orderStatus": @"confirmed"}
          completion:^(NCError *error) {
    if (!error) {
        // Updated — refresh UI
    }
}];

Delete metadata

Call deleteMetadataWithKeys:completion: on the message instance to remove specific keys:

Swift

swift

import NexconnChatSDK
message.deleteMetadata(keys: ["orderStatus"]) { error in
    if error == nil {
        // Deleted
    }
}

Objective-C

Objective C

[message deleteMetadataWithKeys:@[@"orderStatus"]
                     completion:^(NCError *error) {
    if (!error) {
        // Deleted
    }
}];