RoomConnectionClient

const roomConnection = client.getRoomConnection()

RoomConnectionClient manages entire room connection. It exposes state subscriptions and provides actions to manage and observe remoteParticipants and in room actions. Room connection s retrieved from the WherebyClient.

Utilities

Method	Returns	Description
getState	RoomConnectionState	Returns the entire room connection state
destroy	void	Destroy the RoomConnectionClient instance.

State Subscriptions

All subscribe methods follow this format:

• Call signature: subscribeX(callback: (payload: T) => void: () => void

• Contract: Invokes a callback on initial subscription and whenever the state changes.

• Returns: an unsubscribe function

Methods

Method	Payload Type	Description
subscribeToChatMessages	ChatMessage[]	Emits chat messages from remote participants
subscribeToCloudRecording	CloudRecordingState | undefined	Emits cloud recording status
subscribeToBreakoutConfig	BreakoutState	Emits breakout config
subscribeToConnectionStatus	ConnectionStatus	Emits the connection status
subscribeToLiveStream	{ status: "streaming" } | undefined	Emits streaming status
subscribeToLiveCaptions	LiveCaptionsState | undefined	Emits live captions status
subscribeToLiveTranscription	LiveTranscriptionState | undefined	Emits live transcription status
subscribeToLocalScreenshare	LocalScreenshareState | undefined	Emits local screenshare status
subscribeToLocalParticipant	LocalParticipantState	Emits local participant state
subscribeToRemoteParticipants	RemoteParticipantState[]	Emits the remote participant state
subscribeToScreenshares	ScreenshareState[]	Emits screenshare state
subscribeToWaitingParticipants	WaitingParticipantState[]	Emits waiting participants
subscribeToSpotlightedParticipants	ClientView[]	Emits spotlighted participants
subscribeToAudioOnlyMode	boolean	Emits true when audio-only mode is enabled and false when it is disabled. Only emits on changes, not on initial subscription. Read the current value from getState().isAudioOnlyModeEnabled

A host's reply to your knock, the message sent with holdWaitingParticipant or rejectWaitingParticipant, is not a separate subscription. Read knockResponse from getState() when subscribeToConnectionStatus reports knock_on_hold or knock_rejected. See KnockResponse.

Actions

Method	Parameters	Returns	Description
joinRoom		Promise<RoomJoinedSuccess>	Join the room specified in WherebyClientOptions
knock		void	Let the room host know that the local participant is waiting and wants to join
cancelKnock		void	Cancel the knock request
setDisplayName	(displayName: string)	void	Change your display name
sendChatMessage	(text: string, parentId?: string)	void	Send a chat message to the room. If parentId is provided and matches the id of a previously received chat message then the chat message will be sent as a reply to the original chat message.
removeChatMessage	(id: string, sig?: string | null)	void	Mark a chat message with removed: true in the rooms state's chatMessages. To remove a chat message, a sig provided in a previously sent ChatMessage must be included. Hosts can remove any chat message without needing to send any sig.
toggleCamera	(enabled?: boolean)	void	Change the state of your camera
toggleMicrophone	(enabled?: boolean)	void	Change the state of your microphone
toggleHdMode	(enabled?: boolean)	void	Enables / disables high-definition (hd) video mode. Default: true
toggleLowDataMode	(enabled?: boolean)	void	Change the state of low data mode
toggleAudioOnlyMode	(enabled?: boolean, options?: ToggleAudioOnlyModeOptions)	void	Enables / disables audio-only mode. While enabled, all incoming video is paused and only audio is received. Omitting enabled toggles the current state. See Audio-only mode
toggleWidescreenMode	(enabled?: boolean)	void	Enables / disables widescreen video mode. Default: true
toggleRaiseHand	(enabled?: boolean)	void	Toggle raising and lowering your hand in the meeting. Any host in the meeting can acknowledge your request with the askToSpeak host action.
startScreenshare		void	Start screen share
stopScreenshare		void	Stop screen share
leaveRoom		void	Leave the room
joinBreakoutGroup	(group: string)	void	Join a breakout group.
joinBreakoutMainRoom		void	Join the main room in a breakout session.
switchCameraEffect	(effectId: string)	void	Enable a camera effect.
clearCameraEffect		void	Disable a camera effect.
enableAudioDenoiser		void	Enable noise suppression on the local microphone stream. Automatically re-applied if the microphone device is later switched. Use isAudioDenoiserSupported() to check browser support first.
disableAudioDenoiser		void	Disable noise suppression on the local microphone stream.
startLiveCaptions		void	Start live captions for local participant only (if enabled for room)
stopLiveCaptions		void	Stop live captions for local participant only (if enabled for room)

Room integrations

startRoomIntegration, stopRoomIntegration and updateRoomIntegrationProps share YouTube videos and Miro boards with the room. See Room Integrations.

Audio-only mode

Audio-only mode pauses all incoming video and keeps audio flowing. It matches the "Disable videos" option in the standard Whereby app. Your own camera stays on unless you pass autoDisableLocalCamera: true, and it is not turned back on when you disable audio-only mode.

import { WherebyClient } from "@whereby.com/core";

const client = new WherebyClient();
const roomConnection = client.getRoomConnection();

// enable audio-only mode (pauses all incoming video) with...
roomConnection.toggleAudioOnlyMode(true);
// or, optionally also turn off the local camera when enabling...
roomConnection.toggleAudioOnlyMode(true, { autoDisableLocalCamera: true });

// later, disable audio-only mode with...
roomConnection.toggleAudioOnlyMode(false);
// or, toggle the current state by omitting the argument...
roomConnection.toggleAudioOnlyMode();

// get notified whenever audio-only mode changes...
roomConnection.subscribeToAudioOnlyMode((isEnabled) => {
    console.log("Audio-only mode enabled:", isEnabled); // true or false
});

Audio-only mode only affects what you receive. Other participants are not told when you turn it on.

Host-only actions

When a participant provides a valid "host" roomKey in the RoomConnectionOptions when the RoomConnectionClient is initialized, they will have access to a number of addition host-only actions in rooms:

Method	Parameters	Returns	Description
lockRoom	(locked: boolean)	void	Lock (true) or unlock (false) the current room
acceptWaitingParticipant	(participantId: string)	void	Accept waiting participant
holdWaitingParticipant	(participantId: string, response?: string)	void	Put a waiting participant on hold, optionally with a message explaining why. They stay in the waiting room and in the waitingParticipants list, so they can be accepted or rejected later. Their connection status becomes knock_on_hold and the message reaches them as knockResponse.
rejectWaitingParticipant	(participantId: string, response?: string)	void	Reject a waiting participant, optionally with a message.
askToSpeak	(participantId: string)	void	Ask the specified remote participant to unmute their microphone and speak in the meeting. This is typically useful in response to a toggleRaiseHand request from a participant in the meeting.
askToTurnOnCamera	(participantId: string)	void	Ask a participant to turn on their camera
askToTurnOnScreenshare	(participantId: string)	void	Ask a participant to start screen sharing
muteParticipants	(participantIds: string[])	void	Mute the specified remote participants
turnOffParticipantCameras	(participantIds: string[])	void	Turn off the camera of the specificed remote participants
stopParticipantScreenshare	(participantId: string)	void	Stop a participants screen share in the meeting
kickParticipant	(participantId: string)	void	Remove the specified remote participant from the meeting
spotlightParticipant	(participantId: string)	void	Put a spotlight on a participant. When used in combination with the video grid, the spotlighted participant will move to the presentation stage, and their video cell will be bigger.
removeSpotlight	(participantId: string)	void	Remove spotlight on a participant.
startCloudRecording		void	Start cloud recording
stopCloudRecording		void	Stop cloud recording
startLiveTranscription		void	Start live transcription (if enabled for room)
stopLiveTranscription		void	Stop live transcription (if enabled for room)
endMeeting	(stayBehind?: boolean)	void	End the meeting for all remote participants. If stayBehind is not provided or is not true, then the local participant will also leave the room

Breakout host actions

These require the host role and a group (SFU) room. Check isAvailable on the BreakoutState before offering breakout controls, and read error if an action was refused.

Method	Parameters	Description
startBreakoutSession	(options: StartBreakoutSessionOptions)	Start a breakout session with the given groups, optional participant assignments and session settings
updateBreakoutSession	(options: UpdateBreakoutSessionOptions)	Update groups, assignments and/or settings, before or during a session. Only the fields you pass are changed
stopBreakoutSession		End the session and return participants to the main room
assignBreakoutParticipants	(assignments: { [clientId: string]: string })	Assign participants to groups, as a map of clientId → groupId. Merged with the current assignments: participants you leave out keep theirs, and an empty groupId unassigns one.
assignAllBreakoutParticipants		Randomly distribute all remote participants evenly across the groups
unassignAllBreakoutParticipants		Clear every group assignment
shuffleBreakoutParticipants		Re-distribute the already-assigned participants randomly. Unassigned participants are left out
extendBreakoutTimer	(seconds?: number)	Add time to the running timer. Defaults to 60 seconds
stopBreakoutTimer		Turn the timer off without ending the session
broadcastToGroups	(participantId: string)	Broadcast a main-room participant into every breakout group, for announcements that should reach all groups at once. This spotlights the participant; participants inside a group see them in broadcastingParticipants.
stopBroadcastToGroups	(participantId: string)	Stop broadcasting the participant into the groups

Events

RoomConnectionClient extends EventEmitter . You can listen to lifecycle and state change events directly:

import { REMOTE_PARTICIPANTS_CHANGED } from "@whereby.com/core";

const roomConnection = client.getRoomConnection();

function logChatMessage(message: ChatMessage) {
    console.log("New chat message received", message);
}

roomConnection.on(REMOTE_PARTICIPANTS_CHANGED, logChatMessage);

RoomConnectionEvents

Event (constant)	Event name (string)	Payload	Emitted when
BREAKOUT_CONFIG_CHANGED	breakout:config-changed	config:BreakoutState	Breakout config changes
CHAT_NEW_MESSAGE	chat:new-message	messages: ChatMessage[]	A new chat message is received
CLOUD_RECORDING_STATUS_CHANGED	cloud-recording:status-changed	{ status: "requested" | "recording" | "error" }, startedAt?: string, error?: string } | undefined	Cloud recording is started or stopped
CONNECTION_STATUS_CHANGED	connection:status-changed	status: ConnectionStatus	There's a change to connection status
LOCAL_PARTICIPANT_CHANGED	local-participant:changed	participant?: LocalParticipantState	There's a change to the local participant state
LOCAL_SCREENSHARE_CHANGED	local-screenshare:state-changed	status: LocalScreenshareState	Local screenshare is started or stopped
LIVE_TRANSCRIPTION_STATUS_CHANGED	live-transcription:status-changed	status: LiveTranscriptionState	Live transcription is started or stopped
LIVE_CAPTIONS_STATUS_CHANGED	live-captions:status-changed	status: LiveCaptionsState	Live captions is started or stopped for local participant
AUDIO_ONLY_MODE_CHANGED	audio-only-mode:changed	isEnabled: boolean	Audio-only mode is enabled or disabled
REMOTE_PARTICIPANTS_CHANGED	remote-participants:changed	participants: RemoteParticipantState[]	There's a change to the remote participant state
SCREENSHARE_STARTED	screenshare:started	screenshares: ScreenshareState[]	Remote screenshare is started or stopped
ROOM_JOINED	room:joined	room: RoomJoinedEvent	A client joins the room
ROOM_JOINED_ERROR	room:joined:error	error: RoomJoinedErrors | string	A client leaves the room
WAITING_PARTICIPANT_JOINED	waiting-participant:joined	participant: WaitingParticipantState	A client joins the waiting room
WAITING_PARTICIPANT_LEFT	waiting-participant:left	participantId: string	A client leaves the waiting room
SPOTLIGHT_PARTICIPANT_ADDED	spotlight:participant-added	particpant: ClientView	A client is spotlighted
SPOTLIGHT_PARTICIPANT_REMOVED	spotlight:participant-removed	participantId: string	A client is removed from the spotlight
STREAMING_STARTED	streaming:started	streaming: LiveStreamState	Streaming is started
STREAMING_STOPPED	streaming:stopped	void	Streaming is stopped