100ms Logo



Search docs

Session Metadata

Session metadata is a shared state that is accessible by everyone in the room. Think of it as a additional top-level data associated with a session. Session metadata can be used to achieve features like pinned text, spotlight (bringing a particular peer into a center stage for everyone in the room), etc.

Session metadata is persisted throughout a session and is cleared once the last peer leaves the room.

💡 Session Metadata vs Peer Metadata

While peer metadata is associated with individual peers and each peer can have their own metadata, session metadata remains the same for every peer in the room.


Setting session metadata

import { hmsActions } from './hms'; const setSessionMetadata = async (data) => { await hmsActions.setSessionMetadata(data); await hmsActions.sendBroadcastMessage('refresh', 'metadata'); }; // usage setSessionMetadata('any-data');

Refreshing session metadata

import { hmsStore, hmsActions, hmsNotifications } from './hms'; hmsStore.subscribe((isConnected) => { if (isConnected) hmsActions.populateSessionMetadata(); }, selectIsConnectedToRoom); hmsNotifications.onNotification((notification) => { const msg = notification.data; if (msg && msg.type === 'metadata' && msg.message === 'refresh') { hmsActions.populateSessionMetadata(); } }, HMSNotificationTypes.NEW_MESSAGE);

SDK Actions


  • Use setSessionMetadata to update the value of the session metadata.
  • Objects could be set as session metadata but the object should be JSON serializable.
  • Note: whatever is passed to setSessionMetadata is set as session metadata as is. When using objects, if you want to update a particular key, you should update it before calling setSessionMetadata.
// interface setSessionMetadata(metadata: any): Promise<void> // usage await hmsActions.setSessionMetadata('any-string-here'); await hmsActions.setSessionMetadata({ hello: 'world' });


  • Use populateSessionMetadata to fetch the metadata from the server and update it in HMSStore.
  • In the alpha release, session metadata needs to be repopulated on the app side upon join and on receiving refresh message as demonstrated earlier in the uasge section.
// interface populateSessionMetadata(): Promise<void>; // usage await hmsActions.populateSessionMetadata();

Accessing session metadata

The current session metadata can be accessed from HMSStore using the selectSessionMetadata selector.

const sessionMetadata = hmsStore.getState(selectSessionMetadata);

Limitations and workarounds in Alpha release

  • Changing the value of session metadata using setSessionMetadata doesn’t update the metadata of remote peers.
  • To notify remote peers of the change in metadata, broadcast API needs to be used.
  • After updating metadata, a broadcast message with text refresh of type metadata is sent to all the remote peers.
  • On receiving a message of this type and text, session metadata needs to be refreshed and populateSessionMetadata action.
  • Also after joining, session metadata is not available and needs to be fetched explicitly by the app using populateSessionMetadata action.
  • No permission support - anyone can read/write session metadata. If you want to restrict access to session metadata, you have to do it on your app level logic.
  • Locks to ensure consistency of the data. If two peers update it at the same time, it will be a race condition for which one succeeds last, overwriting whatever was before.

Example - Pin Message

You can use session metadata to pin information so that it's available for everyone in the room - even for newly joined peers. In this example we'll pin a chat message that's important in React.


Hook to set pinned message - useSetPinnedMessage

import { useCallback } from 'react'; import { selectPeerNameByID, selectSessionMetadata, useHMSActions, useHMSStore, useHMSVanillaStore } from '@100mslive/react-sdk'; // from refreshing session metadata section import { METADATA_MESSAGE_TYPE, REFRESH_MESSAGE } from './useRefreshSessionMetadata'; /** * set pinned chat message by updating the session metadata * and broadcasting metadata refresh message to other peers */ export const useSetPinnedMessage = () => { const hmsActions = useHMSActions(); const vanillaStore = useHMSVanillaStore(); const pinnedMessage = useHMSStore(selectSessionMetadata); const setPinnedMessage = useCallback( /** * @param {import("@100mslive/react-sdk").HMSMessage | undefined} message */ async (message) => { const peerName = vanillaStore.getState(selectPeerNameByID(message?.sender)) || message?.senderName; const newPinnedMessage = message ? peerName ? `${peerName}: ${message.message}` : message.message : null; if (newPinnedMessage !== pinnedMessage) { await hmsActions.setSessionMetadata(newPinnedMessage); await hmsActions.sendBroadcastMessage(REFRESH_MESSAGE, METADATA_MESSAGE_TYPE); } }, [hmsActions, vanillaStore, pinnedMessage] ); return { setPinnedMessage }; };

Display the pinned message

We'll also use the same function returned from the hook to clear the pinned chat by passing in no arguments

const PinnedMessage = () => { const pinnedMessage = useHMSStore(selectSessionMetadata); const { setPinnedMessage } = useSetPinnedMessage(); return pinnedMessage ? ( <Flex> <Box> <PinIcon /> </Box> <Text variant="sm">{pinnedMessage}</Text> <IconButton onClick={() => setPinnedMessage()}> <CrossIcon /> </IconButton> </Flex> ) : null; };

Have a suggestion? Recommend changes ->

Was this helpful?