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 | ✅ |
| The URL of the Whereby room. Refer to our REST api reference to learn how to create these. |
roomConnectionOptions | ✅ | Additional options for the room connection |
Return type
The hook returns a RoomConnectionReference
object with the following properties.
Property | Type | Description |
---|---|---|
state | Object representing the state of the room | |
actions | Object representing the available actions in the room | |
events | 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 | The chat messages which have been sent in the room since connecting. | |
cloudRecording | Indicates whether cloud recording is active in the room. | |
connectionStatus | Overall status of the room connection | |
localScreenshareStatus | Status of your local screen share | |
localParticipant | A representation of the local participant in the call (you) | |
remoteParticipants | A list of the remote participants in the room | |
screenshares | List of active screenshares in the room | |
liveStream | Set if live stream is enabled for the room | |
waitingParticipants | A list of participants waiting to enter a locked room. | |
spotlightedParticipants | 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 |
| Join the room configured in the |
| Let the room host know that the local participant is waiting and wants to join | |
setDisplayName |
| Change your display name |
sendChatMessage |
| Send a chat message to the room |
toggleCamera |
| Change the state of your camera |
toggleMicrophone |
| Change the state of your microphone |
toggleLowDataMode |
| Change the state of low data mode |
toggleRaiseHand |
| Toggle raising and lowering your hand in the meeting. Any host in the meeting can acknowledge your request with the |
acceptWaitingParticipant |
| Accept waiting participant |
rejectWaitingParticipant |
| Reject waiting participant |
startScreenshare |
| Start screen share |
stopScreenshare |
| Stop screen share |
leaveRoom |
| 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 |
| [Host only] Lock ( |
muteParticipants |
| [Host only] Mute the specified remote participants |
askToSpeak |
| [Host only] Ask the specified remote participant to unmute their microphone and speak in the meeting. This is typically useful in response to a |
kickParticipant |
| [Host only] Remove the specified remote participant from the meeting |
endMeeting |
| [Host only] End the meeting for all remote participants. If |
spotlightParticipant |
| [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 |
| [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 |
---|---|---|
* | Listen for all events | |
requestAudioEnable | 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 | |
requestAudioDisable | A host has forcibly muted your microphone | |
signalTrouble | There is a problem with the internet connection and a connection to our signal server can not be established | |
signalOk | Internet connectivity is present or it has been restored after | |
chatMessageReceived | 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 | 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 | |
remoteHandLowered | 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
Last updated