useRoomConnection

The useRoomConnection hook provides the ability to connect participants in a given room, subscribe to state updates, and perform actions on the connection like toggling the camera or microphone.

useRoomConnection(roomUrl: string, roomConnectionOptions: RoomConnectionOptions): Object | null

Parameter	Required	Type	Description
roomUrl	✅	string	The URL of the Whereby room. Refer to our REST api reference to learn how to create these.
roomConnectionOptions	✅	RoomConnectionOptions	Additional options for the room connection

Return type

The hook returns a RoomConnectionReference object with the following properties.

Property	Type	Description
state	RoomConnectionState	Object representing the state of the room
actions	RoomConnectionActions	Object representing the available actions in the room
events	RoomConnectionEvents	Event emitter that emits in-room events as they are happening

state

The current state of the room. Use this state to render your custom video experience.

Property	Type	Description
chatMessages	ChatMessage[]	The chat messages which have been sent in the room since connecting
cloudRecording	CloudRecordingState?	Indicates whether cloud recording is active in the room
connectionStatus	RoomConnectionStatus	Overall status of the room connection
localScreenshareStatus	LocalScreenshareStatus?	Status of your local screen share
localParticipant	LocalParticipant?	A representation of the local participant in the call (you)
liveTranscription	LiveTranscriptionState?	Indicates whether live transcription is active in the room
liveCaptions	LiveCaptionsState?	Indicates whether live captions is active in the room and provides access to ongoing live caption data
remoteParticipants	RemoteParticipant[]	A list of the remote participants in the room
screenshares	Screenshare[]	List of active screenshares in the room
liveStream	LiveStreamState?	Set if live stream is enabled for the room
waitingParticipants	WaitingParticipant[]	A list of participants waiting to enter a locked room
spotlightedParticipants	ClientView[]	A list of spotlighted participants
breakout	Breakout	The breakout group state of the room
knockResponse	KnockResponse | null	The host's response to your knock when you were put on hold or rejected. null until a response arrives, and it may carry no message, guard on knockResponse?.message

actions

The actions property contains a map of functions which can be invoked to perform an action in the room. All these functions are sync and return void, and you should rely on the state to render the effect of their invocation.

Property	Type	Description
joinRoom	() => Promise<RoomJoinedSuccess>	Join the room configured in the useRoomConnection config.
knock	() => void	Let the room host know that the local participant is waiting and wants to join
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)	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	Change the state of video quality between high-definition and standard-definition. Default true
toggleLowDataMode	(enabled?: boolean) => void	Change the state of low data mode
toggleWidescreenMode	(enabled?: boolean) => void	Change the state of video width/height between 16:9 (widescreen) and 4:3 (standard). 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.
acceptWaitingParticipant	(participantId: string) => void	Accept waiting participant
rejectWaitingParticipant	(participantId: string, response?: string) => void	Reject waiting participant, optionally with a message.
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. Use getUsableCameraEffectPresets() to get a valid effectId.
switchCameraEffectCustom	(imageUrl: string) => Promise<void>	Enable a camera effect that uses a custom image (from the given URL) as the background.
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 configured)
stopLiveCaptions	() ⇒ void	Stop live captions for local participant only (if configured)
cancelKnock	() => void	Withdraw a pending knock and leave the waiting room
holdWaitingParticipant	(participantId: string, response?: string) => void	Put a waiting participant on hold, optionally with a message explaining why (for example "We're running 5 minutes late"). The participant stays in the waiting room and in your waitingParticipants list, so you can still accept or reject them later. Their connection status changes to knock_on_hold and the message is delivered in knockResponse. See Waiting room messages.

Host-only actions

When a participant provides a valid "host" roomKey in the RoomConnectionOptions when the useRoomConnection hook was created, they will have access to a number of addition host-only actions in rooms:

Property	Type	Description
lockRoom	(locked: boolean) => void	[Host only] Lock (true) or unlock (false) the current room
muteParticipants	(participantIds: string[]) => void	[Host only] Mute the specified remote participants
askToSpeak	(participantId: string) => void	[Host only] 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.
kickParticipant	(participantId: string) => void	[Host only] Remove the specified remote participant from the meeting
endMeeting	(stayBehind?: boolean) => void	[Host only] 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
spotlightParticipant	(participantId: string) => void	[Host only] 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	[Host only] Remove spotlight on a participant.
startCloudRecording	() ⇒ void	[Host only] Start cloud recording (if configured)
stopCloudRecording	() ⇒ void	[Host only] Stop cloud recording (if configured)
startLiveTranscription	() ⇒ void	[Host only] Start live transcription (if configured)
stopLiveTranscription	() ⇒ void	[Host only] Stop live transcription (if configured)

Breakout host actions

Hosts can start, configure and steer a breakout session with the actions below. They all require the host role and a group (SFU) room, check state.breakout.isAvailable before showing breakout controls in your UI, and read state.breakout.error if an action is refused. See Breakout sessions for the full flow.

Property	Type	Description
startBreakoutSession	(options: StartBreakoutSessionOptions) => void	[Host only] Start a breakout session with the given groups, optional participant assignments and session settings
updateBreakoutSession	(options: UpdateBreakoutSessionOptions) => void	[Host only] Update the groups, assignments and/or settings. Can be called both before and during a session, only the fields you pass are changed
stopBreakoutSession	() => void	[Host only] End the breakout session and return participants to the main room
assignBreakoutParticipants	(assignments: { [clientId: string]: string }) => void	[Host only] 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 a participant.
assignAllBreakoutParticipants	() => void	[Host only] Randomly distribute all remote participants evenly across the groups
unassignAllBreakoutParticipants	() => void	[Host only] Clear every group assignment
shuffleBreakoutParticipants	() => void	[Host only] Re-distribute the already-assigned participants randomly across the groups. Participants without an assignment are left out
extendBreakoutTimer	(seconds?: number) => void	[Host only] Give the groups more time by adding to the timer duration. Defaults to 60 seconds
stopBreakoutTimer	() => void	[Host only] Turn the timer off without ending the session — the groups keep running until you call stopBreakoutSession
broadcastToGroups	(participantId: string) => void	[Host only] Broadcast a main-room participant into every breakout group, so they can make an announcement without visiting each group. This spotlights the participant, and participants inside a group will see them in state.breakout.broadcastingParticipants.
stopBroadcastToGroups	(participantId: string) => void	[Host only] Stop broadcasting the participant into the groups (removes their spotlight)

events

Event emitter which emits notification events as they are happening inside of the room.

It's possible to subscribe and unsubscribe to events using the events.on and events.off methods.

Event	Payload	Description
*	NotificationEvent	Listen for all events
requestAudioEnable	NotificationEvent<RequestAudioEvent>	A host is asking for the local participant to speak in the meeting. The local participant should be notified when this event is received and prompted to trigger actions.toggleMicrophone(true) if or when they are ready to speak
requestAudioDisable	NotificationEvent<RequestAudioEvent>	A host has forcibly muted your microphone
signalTrouble	NotificationEvent<SignalStatusEvent>	There is a problem with the internet connection and a connection to our signal server can not be established
signalOk	NotificationEvent<SignalStatusEvent>	Internet connectivity is present or it has been restored after signalTrouble
chatMessageReceived	NotificationEvent<ChatMessageEvent>	A chat message was sent by a remote participant

Breakout events

Emitted to every participant in a room with an active breakout session.

Event	Payload	Description
breakoutGroupAssigned	NotificationEvent<BreakoutGroupAssignedEvent>	The local participant was assigned to a breakout group. Use this to prompt them to join, or to explain an imminent automatic move. Being unassigned does not emit an event.
breakoutTimerEnding	NotificationEvent<BreakoutTimerEvent>	The breakout timer is about to run out. A good moment to warn the groups that they'll be sent back to the main room shortly
breakoutTimerEnded	NotificationEvent<BreakoutTimerEvent>	The breakout timer ran out
breakoutTimerExtended	NotificationEvent<BreakoutTimerEvent>	A host added time to the running breakout timer

Host-only events

When a participant provides a valid "host" roomKey in the RoomConnectionOptions when the useRoomConnection hook was created, they will have access to a number of addition host-only events in rooms:

Event	Payload	Description
remoteHandRaised	NotificationEvent<StickyReactionEvent>	A remote participant has raised their hand to request to speak in the meeting. The local host participant should be notified when this event is received and prompted to trigger actions.askToSpeak(participantId) if or when they want to invite the remote participant to speak in the meeting.
remoteHandLowered	NotificationEvent<StickyReactionEvent>	A remote participant who previously had their hand raised has now lowered their hand. Any previous raised hand notifications shown for this remote participant should be cancelled and no further action is needed from the local host participant.

Usage

import * as React from "react";
import { useRoomConnection, VideoView } from "@whereby.com/browser-sdk/react";

function MyCallUX( { roomUrl, localStream }) {
    const { state, actions, events } = useRoomConnection(
        "<room_url>"
        {
            localMediaOptions: {
                audio: true,
                video: true,
            }
        }
    );

    const { connectionState, remoteParticipants } = state;
    const { joinRoom, leaveRoom, toggleCamera, toggleMicrophone } = actions;
    
    React.useEffect(() => {
        joinRoom().catch(error => console.error("Could not join room", error));
        return () => leaveRoom();
    }, []);

    // listen to all notification events on mount and unlisten on unmount
    React.useEffect(() => {
        if(!events) return;
        const handleEvents = (e) => console.log(e);
        events.on("*", handleEvents);
        return () => events && events.off("*", handleEvents);
    }, []);

    return <div className="videoGrid">
        { /* Render any UI, making use of state */ }
        { remoteParticipants.map((p) => (
            <VideoView key={p.id} stream={p.stream} />
        )) }
    </div>;
}