Skip to main content
The Broadcasts module lets you send fire-and-forget custom events to other participants in the room. Use it for emoji reactions, pings, notifications, cursor clicks, or any ephemeral communication. Access it via client.notifications.
Broadcasts are fire-and-forget. They are not persisted and cannot be replayed. If a user is offline when an event is sent, they won’t receive it.

​
Methods

​
Send Event

broadcast(event, data, userIds?) Send a custom event to other users in the room: 
// Send to everyone in the room
client.notifications.broadcast('cursor-click', { x: 100, y: 200 });

// Send to specific users
client.notifications.broadcast('ping', { message: 'hello' }, ['user-002']);
ParameterTypeRequiredDescription
eventstringYesCustom event name. Can be any string.
dataobjectYesPayload to send. Must be JSON-serializable.
userIdsstring[]NoUser IDs to target. If omitted, sent to all other participants.

​
Listen for Events

on(event, callback) Listen for a specific event type: 
client.notifications.on('cursor-click', (data) => {
  console.log('Click at:', data.x, data.y);
});

​
Listen Once

once(event, callback) Listen for an event, but only fire the callback once: 
client.notifications.once('welcome', (data) => {
  showWelcomeMessage(data.message);
});

​
Remove Listener

off(event, callback) Remove a specific listener: 
const handler = (data) => console.log(data);
const offHandler = client.notifications.on('cursor-click', handler);

// Later, remove the listener
client.notifications.off('cursor-click', handler);
// Alternatively
offHandler();

​
Examples

​
Emoji Reactions

// Send a floating emoji
function sendEmoji(emoji: string, x: number, y: number) {
  client.notifications.broadcast('emoji', { emoji, x, y });
}

// Render floating emojis from other users
client.notifications.on('emoji', ({ emoji, x, y }) => {
  const el = document.createElement('span');
  el.textContent = emoji;
  el.className = 'floating-emoji';
  el.style.left = `${x}px`;
  el.style.top = `${y}px`;
  document.body.appendChild(el);
  setTimeout(() => el.remove(), 2000);
});

​
User Notifications

// Notify a specific user
client.notifications.broadcast(
  'mention',
  { from: client.userId, message: 'Check this out!' },
  ['user-002']
);

// Listen for mentions
client.notifications.on('mention', ({ from, message }) => {
  const sender = client.users.all.get(from);
  showNotification(`${sender?.name}: ${message}`);
});