Message metadata

Use cases

Use metadata to add status indicators to existing messages:

• Message reactions: Add reaction information to the original message through metadata.
• Gift claiming / order status: Change the message display state. For example, send a gift message with an "unclaimed" state, then update the metadata to "claimed" when the user taps it.
• Only supported in direct channels and group channels. Not supported in open channels.
• Each metadata update generates a built-in notification message. Frequent updates can produce a high volume of messages.

Update metadata

Call message.setMetadata() on the message instance after it has been sent.

Method

Dart

Future<int> setMetadata(Map expansion, ErrorHandler handler)

Parameters

Parameter	Type	Description
expansion	Map<String, String>	Key-value pairs to update. Keys support uppercase/lowercase letters, numbers, and + = - _. Values can include spaces.
handler	ErrorHandler	Event callback.

Code example

Dart

await message.setMetadata(
  {'reaction_like': 'user1,user2', 'status': 'claimed'},
  (error) {
    if (error == null) {
      print('Metadata updated');
    }
  },
);

Remove metadata keys

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

Method

Dart

Future<int> deleteMetadata(List<String> keys, ErrorHandler handler)

Code example

Dart

await message.deleteMetadata(
  ['reaction_like'],
  (error) {
    if (error == null) {
      print('Metadata keys removed');
    }
  },
);

Listen for metadata updates

Register a MessageHandler to receive metadata update and removal events:

MessageMetadataUpdatedEvent

Property	Type	Description
metadata	Map?	Updated metadata entries.
message	Message?	Target message.

MessageMetadataDeletedEvent

Property	Type	Description
message	Message?	Target message.
keys	List<String>?	Removed metadata keys.

Dart

NCEngine.addMessageHandler('expansion-handler', MessageHandler(
  onMessageMetadataUpdated: (event) {
    print('Metadata updated on message: ${event.message?.messageId}');
  },
  onMessageMetadataDeleted: (event) {
    print(
      'Metadata keys removed from message: ${event.message?.messageId}, keys: ${event.keys}',
    );
  },
));