Message metadata

Message metadata lets you attach key-value status data to messages. Common use cases include message reactions, gift redemption status, and order state changes.

tip

• Metadata is supported only in direct, group, and community channels.
• Each update can set up to 20 key-value pairs, with a maximum of 300 total per message.

Listen for metadata changes

Use MessageHandler to listen for metadata updates and removals.

Kotlin

kotlin

NCEngine.addMessageHandler("myHandler", object : MessageHandler {
    override fun onMessageMetadataUpdated(event: MessageMetadataUpdatedEvent) {
        Log.d("MetaData", "Message ${event.message.messageId} metadata updated")
        event.metadata.forEach { (key, value) ->
            Log.d("MetaData", "$key = $value")
        }
    }
    
    override fun onMessageMetadataDeleted(event: MessageMetadataDeletedEvent) {
        Log.d("MetaData", "Keys removed from message ${event.message.messageId}: ${event.keys}")
    }
})

Java

Java

NCEngine.addMessageHandler("myHandler", new MessageHandler() {
    @Override
    public void onMessageMetadataUpdated(MessageMetadataUpdatedEvent event) {
        Log.d("MetaData", "Message " + event.getMessage().getMessageId() + " metadata updated");
    }
    
    @Override
    public void onMessageMetadataDeleted(MessageMetadataDeletedEvent event) {
        Log.d("MetaData", "Keys removed: " + event.getKeys());
    }
});

Update metadata

Use message.setMetadata() to update key-value pairs on a message.

Kotlin

kotlin

val expansion = mapOf(
    "status" to "confirmed",
    "confirmTime" to System.currentTimeMillis().toString()
)

message.setMetadata(expansion) { error ->
    if (error == null) {
        println("Metadata updated")
    } else {
        println("Update failed: ${error.code}")
    }
}

Java

Java

Map<String, String> expansion = new HashMap<>();
expansion.put("status", "confirmed");
expansion.put("confirmTime", String.valueOf(System.currentTimeMillis()));

message.setMetadata(expansion, error -> {
    if (error == null) {
        Log.d("MetaData", "Metadata updated");
    } else {
        Log.e("MetaData", "Update failed: " + error.getCode());
    }
});

Remove metadata

Use message.deleteMetadata() to remove specific keys from a message's metadata.

Kotlin

kotlin

val keysToRemove = listOf("status", "confirmTime")

message.deleteMetadata(keysToRemove) { error ->
    if (error == null) {
        println("Keys removed")
    } else {
        println("Remove failed: ${error.code}")
    }
}

Java

Java

List<String> keysToRemove = Arrays.asList("status", "confirmTime");

message.deleteMetadata(keysToRemove, error -> {
    if (error == null) {
        Log.d("MetaData", "Keys removed");
    } else {
        Log.e("MetaData", "Remove failed: " + error.getCode());
    }
});

Important notes

• Each metadata update generates an internal notification message.
• Frequent updates generate many messages. Limit how often you update metadata.