Skip to Content
Mux Docs: Home

Sending custom events

Send and receive arbitrary data by using 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

For more details, refer to the SDK API documentation.

import com.mux.sdk.webrtc.spaces.Space;
import com.mux.sdk.webrtc.spaces.SpaceConfiguration;
import com.mux.sdk.webrtc.spaces.Spaces;

...

final String JWT = <YOUR_JWT>;

SpaceConfiguration spaceConfiguration = null;

try {
    spaceConfiguration = SpaceConfiguration.newBuilder()
            .setJWT(JWT)
            .build();
} catch (Exception e) {
    e.printStackTrace();
    return;
}

Spaces spaces = Spaces.getInstance(this);
Space space = spaces.getSpace(spaceConfiguration);

space.join(new Space.Listener() {
    @Override
    public void onJoined(Space space, LocalParticipant localParticipant) {
        localParticipant.publishCustomEvent("I'm the custom event payload");
    }
});

...

Listen for custom events

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

import com.mux.sdk.webrtc.spaces.Participant;
import com.mux.sdk.webrtc.spaces.Space;
import com.mux.sdk.webrtc.spaces.SpaceConfiguration;
import com.mux.sdk.webrtc.spaces.Spaces;

...

final String JWT = <YOUR_JWT>;

SpaceConfiguration spaceConfiguration = null;

try {
    spaceConfiguration = SpaceConfiguration.newBuilder()
            .setJWT(JWT)
            .build();
} catch (Exception e) {
    e.printStackTrace();
    return;
}

Spaces spaces = Spaces.getInstance(this);
Space space = spaces.getSpace(spaceConfiguration);

space.join(new Space.Listener() {
    @Override
    public void onParticipantCustomEvent(Space space, Participant participant, String payload) {
        // The participant is the sender, and the payload is their event payload
    }
});

...

Was this page helpful?