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)
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

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	() => void	Join the room configured in the useRoomConnection config.
	() => 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) => void	Send a chat message to the room
toggleCamera	(enabled?: boolean) => void	Change the state of your camera
toggleMicrophone	(enabled?: boolean) => void	Change the state of your microphone
toggleLowDataMode	(enabled?: boolean) => void	Change the state of low data mode
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) => void	Reject waiting participant
startScreenshare	() => void	Start screen share
stopScreenshare	() => void	Stop screen share
leaveRoom	() => void	Leave the room

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.

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

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();
        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>;
}