Manage open channel metadata

Open channel metadata lets you store and synchronize custom state within an open channel. Use it for features such as polls, live scores, room settings, or any other shared state that participants need to access.

How it works

• Metadata is a collection of key-value pairs associated with an open channel.
• All participants receive real-time notifications when metadata changes.
• Metadata is deleted when the open channel is destroyed.

Set key-value pairs

TypeScript

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

const channel = new OpenChannel('<open-channel-id>');
const { code } = await channel.setMetadata({
  metadata: {
    room_status: 'live',
    host: 'user123',
  },
  deleteWhenLeft: false, // Whether to delete these keys when the user leaves
  overwrite: true,       // Whether to overwrite keys set by other users
});
if (code === 0) {
  console.log('Metadata set successfully');
}

SetMetadataParams

Parameter	Type	Required	Description
metadata	Record<string, string>	Yes	Key-value pairs to set
deleteWhenLeft	boolean	No	Whether to delete these keys when the user who set them leaves. Default: false.
overwrite	boolean	No	Whether to overwrite keys set by other users. Default: false.

Get key-value pairs

Retrieve a specific key, or all keys if no key is provided:

TypeScript

// Get a specific key
const { code, data } = await channel.getMetadata('room_status');
if (code === 0) {
  console.log('Value:', data);
}

// Get all keys
const { code: allCode, data: allData } = await channel.getMetadata();
if (allCode === 0) {
  console.log('All metadata pairs:', allData);
}

Delete key-value pairs

TypeScript

const { code } = await channel.deleteMetadata({
  keys: ['room_status'],
});
if (code === 0) {
  console.log('Metadata key removed');
}

Listen for metadata changes

Register an OpenChannelHandler to receive metadata change events:

TypeScript

import { NCEngine, OpenChannelHandler } from '@nexconn/chat';

NCEngine.addOpenChannelHandler('kv-handler', new OpenChannelHandler({
  onMetadataChanged({ changeInfo }) {
    console.log('Open channel metadata changed:', changeInfo);
  },
  onMetadataSynced({ channelId }) {
    console.log('Metadata sync completed for channel:', channelId);
  },
}));

Remove the handler when it is no longer needed:

TypeScript

NCEngine.removeOpenChannelHandler('kv-handler');

info

• Each open channel supports up to 100 key-value pairs.
• By default, only the user who set a key-value pair can modify or delete it. Set overwrite: true to allow overwriting keys from other users.