LogoLogo
WherebyStatusCommunity
  • 📹Whereby 101
    • Create Your Video Experience
      • Get started in 3 steps
      • Embedding Whereby in a web app
        • Using Whereby's Web Component & Pre-built UI
          • Script Tags
          • With Low Code
            • Embedding in Squarespace or Wordpress
            • No code video conferencing in Bubble
        • Using Whereby's Browser SDK with React Hooks for a fully custom UI
      • Embedding Whereby in a mobile app
        • Embedding Whereby in iOS
          • Using Whereby's Native iOS SDK
        • Embedding Whereby in Android
          • Using Whereby's Native SDK
        • Using Flutter
        • Using React Native
      • Github SDK Examples
      • Meeting scheduling with Cronofy
    • Generating Room URLs
      • Name prefixes
      • Using “Create a room”
      • Using Postman
    • Customize Your Video Experience
      • During room creation
      • Using Attributes/URL Params
      • Global preferences
      • Branding elements
      • Dial-In
      • File sharing
      • Breakout Groups with Embedded
      • Waiting Rooms
    • User roles & Meeting Permissions
    • FAQ
      • Accessibility
      • Whereby Words
      • Firewall & Security
      • HIPAA compliant setup
      • Allowed Domains & Localhost
      • Whereby Embedded Feature Comparison
  • 🔍Meeting Content & Quality
    • Recording
      • Cloud Recording
      • Local Recording
    • Transcribing
      • Session Transcription
      • Recording Transcription
    • Live Captions
    • Session summaries
    • Live streaming RTMP
    • Quality Insights
      • Real-time troubleshooting
      • Using the Insights dashboard
      • Improving call quality
      • Tracking room events with Webhooks
  • 🤷End User
    • End User Support Guides
      • Supported Browsers & Devices
      • Screen Sharing Setup & Usage
      • Using Breakout Groups
      • Troubleshooting & Basics
  • 🚚Developer Guides
    • Quickly deploy Whereby to your domain
    • Tracking Customer Usage
    • Migrating from Twilio
      • Twilio JS SDK Quick Migration
      • Twilio JS SDK Direct Migration
  • 🖥️Reference
    • REST API Reference
      • /meetings
      • /insights
      • /recordings
      • /transcriptions
      • /summaries
      • /rooms
    • Web Component Reference
    • React Hooks Reference
      • Quick Start
        • Getting started with the Browser SDK
      • Guides & Tutorials
        • Migrate from version 2.x to 3
        • Grid logic
        • Custom Video Tiles with React
        • Usage with Next.js
        • How to customize the toolbar
      • API Reference
        • WherebyProvider
        • VideoView
        • VideoGrid
        • useLocalMedia
        • useRoomConnection
      • Types
    • React Native Reference
      • Quick Start
      • WherebyEmbed
    • Webhooks Reference
Powered by GitBook
On this page
  • Return type
  • state
  • actions
  • events
  • Usage

Was this helpful?

Edit on GitHub
  1. Reference
  2. React Hooks Reference
  3. API Reference

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

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

breakout

The breakout group state of the room

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

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

joinBreakoutGroup

(group: string) ⇒ void

Join a breakout group.

joinBreakoutMainRoom

() ⇒ void

Join the main room in a breakout session.

Host-only actions

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

*

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 actions.toggleMicrophone(true) if or when they are ready to speak

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 signalTrouble

chatMessageReceived

A chat message was sent by a remote participant

Host-only events

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 actions.askToSpeak(participantId) if or when they want to invite the remote participant to speak in the meeting.

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

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

Last updated 4 months ago

Was this helpful?

The URL of the Whereby room. Refer to our to learn how to create these.

?

?

[]

[]

?

[]

[]

Join the room configured in the config.

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

<>

<>

<>

<>

<>

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

<>

<>

🖥️
✅
✅
REST api reference
useRoomConnection
RoomConnectionState
RoomConnectionActions
RoomConnectionEvents
useRoomConnection
useRoomConnection
RoomConnectionOptions
RoomConnectionOptions
RoomConnectionOptions
ChatMessage[]
CloudRecordingState
RoomConnectionStatus
LocalScreenshareStatus
LocalParticipant
RemoteParticipant
Screenshare
LiveStreamState
WaitingParticipant
ClientView
Breakout
NotificationEvent
NotificationEvent
RequestAudioEvent
NotificationEvent
RequestAudioEvent
NotificationEvent
SignalStatusEvent
NotificationEvent
SignalStatusEvent
NotificationEvent
ChatMessageEvent
NotificationEvent
StickyReactionEvent
NotificationEvent
StickyReactionEvent