Message metadata

Attach key-value metadata to messages. Use message metadata to add structured information, such as reactions, translations, or custom fields, after a message has been sent.

How it works

• Each message supports up to 20 key-value pairs.
• Keys and values are both strings.
• Metadata updates are synced to all participants in real time.
• Use message.setMetadata() and message.deleteMetadata() on the message instance.

Set message metadata

First retrieve a Message object (from a sent message or from history), then call setMetadata:

TypeScript

import { DirectChannel, BaseChannel, Message, SendTextMessageParams } from '@nexconn/chat';

const channel = new DirectChannel('<target-user-id>');

// Option 1: Use the message object returned from sendMessage
const { code, data: sentMessage } = await channel.sendMessage(
  new SendTextMessageParams({ text: 'Hello!' }),
);

if (code === 0 && sentMessage) {
  const { code: metaCode } = await sentMessage.setMetadata({
    reaction_like: 'user1,user2',
    translated: 'true',
  });
  if (metaCode === 0) {
    console.log('Metadata updated');
  }
}

// Option 2: Retrieve a message from history
const query = BaseChannel.createMessagesQuery({
  channelIdentifier: channel.identifier,
  startTime: Date.now(),
  pageSize: 1,
  isAscending: false,
});
const { code: histCode, data: page } = await query.loadNextPage();
if (histCode === 0 && page.data.length > 0) {
  await page.data[0].setMetadata({ reaction_like: 'user1' });
}

Delete message metadata keys

Remove specific keys from the metadata:

TypeScript

import { Message } from '@nexconn/chat';

// sentMessage is a Message<T> returned from sendMessage or fetched from history
const { code } = await sentMessage.deleteMetadata(['reaction_like']);
if (code === 0) {
  console.log('Metadata key removed');
}

Listen for metadata changes

Register a MessageHandler to receive metadata update and delete events:

TypeScript

import { NCEngine, MessageHandler, MessageMetadataUpdatedEvent, MessageMetadataDeletedEvent } from '@nexconn/chat';

NCEngine.addMessageHandler('meta-handler', new MessageHandler({
  onMessageMetadataUpdated(event: MessageMetadataUpdatedEvent): void {
    console.log('Metadata updated:', event.metadata);
  },
  onMessageMetadataDeleted(event: MessageMetadataDeletedEvent): void {
    console.log('Metadata keys deleted:', event.keys);
  },
}));

// Remove the handler when no longer needed
NCEngine.removeMessageHandler('meta-handler');

tip

Common use cases for message metadata include:

• Reactions: Store emoji reactions as key-value pairs
• Translations: Attach translated text to a message
• Custom status: Mark messages as "important", "reviewed", etc.