Sending custom events

Understand custom events

Custom events allow a way for developers to send a payload with arbitrary data to all other participants in the Space. A participant can publish a custom event and expect other participants in the Space to receive a custom event with the same payload. There is no stateful information in the custom event as only participants connected to the active session can send and receive events.

To publish a custom event, the payload must be a string and must not be greater than 4MB in size. The sender must also have a publisher role in their JWT (the JWTs assume this role by default). Custom events are rate limited at 1 request per second for each sender.

Although custom events require a string payload, developers may convert their data into a string on the sender side and convert the string back to its original form on the receiver side. This makes custom events suitable for many different use cases with structured data, such as gestures, notifications, or chat messages.

Publish custom events

Refer to the web SDK documentation to learn more about the API.

copy
import { Space } from "@mux/spaces-web";

const space = new Space(JWT);

// Join the Space and get the LocalParticipant
const localParticipant = await space.join();

// Form a string payload
const payload = JSON.stringify({
  message: "🚀",
});

// Publish the CustomEvent as the LocalParticipant
// If successful, a SpaceEvent.ParticipantCustomEventPublished event is emitted to the Space
// and a ParticipantEvent.CustomEventPublished event is emitted to the LocalParticipant
try {
  await localParticipant.publishCustomEvent(payload);
} catch (error) {
  // Handle errors
} 

Listen for custom events

Developers can listen to the Space or the sender to know when a custom event has been published.

copy
import { Space, SpaceEvent, ParticipantEvent } from "@mux/spaces-web";

const space = new Space(JWT);

// Join the space
const localParticipant = await space.join();

// Listen to the Space for a SpaceEvent.ParticipantCustomEventPublished event
// The first argument in the event handler is the sender, and the second argument is the CustomEvent
space.on(SpaceEvent.ParticipantCustomEventPublished, (participant, event) => {
  // Handle event
  const payload = event.payload;
});

// Listen to the sender for a ParticipantEvent.CustomEventPublished event
// The argument in the event handler is the CustomEvent
space.on(SpaceEvent.ParticipantJoined, (participant) => {
  participant.on(ParticipantEvent.CustomEventPublished, (event) => {
    // Handle event
    const payload = event.payload;
  });
});

localParticipant.on(ParticipantEvent.CustomEventPublished, (event) => {
  // Handle event
  const payload = event.payload;
});