> For the complete documentation index, see [llms.txt](https://docs.whereby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whereby.com/reference/react-hooks-reference/useroomconnection.md).

# 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`

<table><thead><tr><th width="234">Parameter</th><th width="103">Required</th><th width="275">Type</th><th>Description</th></tr></thead><tbody><tr><td>roomUrl</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><code>string</code></td><td>The URL of the Whereby room. Refer to our <a href="https://docs.whereby.com/whereby-rest-api-reference#meetings">REST api reference</a> to learn how to create these.</td></tr><tr><td>roomConnectionOptions</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><a href="/pages/kgsXFNq2EVMPcwOAa0N3#roomconnectionoptions"><code>RoomConnectionOptions</code></a></td><td>Additional options for the room connection</td></tr></tbody></table>

## Return type

The hook returns a `RoomConnectionReference` object with the following properties.

<table><thead><tr><th>Property</th><th width="279.3333333333333">Type</th><th>Description</th></tr></thead><tbody><tr><td>state</td><td><a href="#state"><code>RoomConnectionState</code></a></td><td>Object representing the state of the room</td></tr><tr><td>actions</td><td><a href="#actions"><code>RoomConnectionActions</code></a></td><td>Object representing the available actions in the room</td></tr><tr><td>events</td><td><a href="#events">RoomConnectionEvents</a></td><td>Event emitter that emits in-room events as they are happening</td></tr></tbody></table>

### state

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

| Property                | Type                                                                                                                               | Description                                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| chatMessages            | [`ChatMessage[]`](/reference/react-hooks-reference/types.md#chatmessage)                                                           | The chat messages which have been sent in the room since connecting                                                                                                      |
| cloudRecording          | [`CloudRecordingState`](/reference/react-hooks-reference/types.md#cloudrecordingstate)`?`                                          | Indicates whether cloud recording is active in the room                                                                                                                  |
| connectionStatus        | [`RoomConnectionStatus`](/reference/react-hooks-reference/types.md#roomconnectionstatus)                                           | Overall status of the room connection                                                                                                                                    |
| localScreenshareStatus  | [<mark style="color:blue;">`LocalScreenshareStatus`</mark>](/reference/react-hooks-reference/types.md#localscreensharestatus-1)`?` | Status of your local screen share                                                                                                                                        |
| localParticipant        | [`LocalParticipant`](/reference/react-hooks-reference/types.md#localparticipant)`?`                                                | A representation of the local participant in the call (you)                                                                                                              |
| liveTranscription       | [`LiveTranscriptionState`](/reference/react-hooks-reference/types.md#localscreensharestatus)`?`                                    | Indicates whether live transcription is active in the room                                                                                                               |
| liveCaptions            | [`LiveCaptionsState`](/reference/react-hooks-reference/types.md#localscreensharestatus-1)`?`                                       | Indicates whether live captions is active in the room and provides access to ongoing live caption data                                                                   |
| remoteParticipants      | [`RemoteParticipant`](/reference/react-hooks-reference/types.md#remoteparticipant)`[]`                                             | A list of the remote participants in the room                                                                                                                            |
| screenshares            | [`Screenshare`](/reference/react-hooks-reference/types.md#screenshare)`[]`                                                         | List of active screenshares in the room                                                                                                                                  |
| liveStream              | [<mark style="color:blue;">`LiveStreamState`</mark>](/reference/react-hooks-reference/types.md#livestreamstate)`?`                 | Set if live stream is enabled for the room                                                                                                                               |
| waitingParticipants     | [`WaitingParticipant`](/reference/react-hooks-reference/types.md#waitingparticipant)`[]`                                           | A list of participants waiting to enter a locked room                                                                                                                    |
| spotlightedParticipants | [ClientView](/reference/react-hooks-reference/types.md#clientview)\[]                                                              | A list of spotlighted participants                                                                                                                                       |
| breakout                | [Breakout](/reference/react-hooks-reference/types.md#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.

<table><thead><tr><th width="205.90755208333331">Property</th><th width="324.72265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>joinRoom</td><td><code>() => Promise&#x3C;</code><a href="/pages/h4IBf7O7kxaodS3RsTRe#roomjoinedsuccess-less-than-object-greater-than"><code>RoomJoinedSuccess</code></a><code>></code></td><td>Join the room configured in the <a href="/pages/lFZVOkmKDjatvjJ73nZp"><code>useRoomConnection</code></a> config.</td></tr><tr><td><a data-footnote-ref href="#user-content-fn-1">knock</a></td><td><code>() => void</code></td><td>Let the room host know that the local participant is waiting and wants to join</td></tr><tr><td>setDisplayName</td><td><code>(displayName: string) => void</code></td><td>Change your display name</td></tr><tr><td>sendChatMessage</td><td><code>(text: string, parentId?: string) => void</code></td><td><p>Send a chat message to the room.</p><p></p><p>If <code>parentId</code> is provided and matches the <code>id</code> of a previously received chat message then the chat message will be sent as a <em>reply</em> to the original chat message.</p></td></tr><tr><td>removeChatMessage</td><td><code>(id: string, sig?: string | null)</code></td><td><p>Mark a chat message with <code>removed: true</code> in the rooms state's <code>chatMessages</code>. </p><p></p><p>To remove a chat message, a <code>sig</code> provided in a previously sent ChatMessage must be included.</p><p></p><p>Hosts can remove any chat message without needing to send any <code>sig.</code></p></td></tr><tr><td>toggleCamera</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of your camera</td></tr><tr><td>toggleMicrophone</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of your microphone</td></tr><tr><td>toggleHdMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of video quality between high-definition and standard-definition. Default <code>true</code></td></tr><tr><td>toggleLowDataMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of low data mode</td></tr><tr><td>toggleWidescreenMode</td><td><code>(enabled?: boolean) => void</code></td><td>Change the state of video width/height between 16:9 (widescreen) and 4:3 (standard). Default <code>true</code></td></tr><tr><td>toggleRaiseHand</td><td><code>(enabled?: boolean) => void</code></td><td>Toggle raising and lowering your hand in the meeting. Any host in the meeting can acknowledge your request with the <code>askToSpeak</code> host action.</td></tr><tr><td>acceptWaitingParticipant</td><td><code>(participantId: string) => void</code></td><td>Accept waiting participant</td></tr><tr><td>rejectWaitingParticipant</td><td><code>(participantId: string, response?: string) => void</code></td><td>Reject waiting participant, optionally with a message.</td></tr><tr><td>startScreenshare</td><td><code>() => void</code></td><td>Start screen share</td></tr><tr><td>stopScreenshare</td><td><code>() => void</code></td><td>Stop screen share</td></tr><tr><td>leaveRoom</td><td><code>() => void</code></td><td>Leave the room</td></tr><tr><td>joinBreakoutGroup</td><td><code>(group: string) ⇒ void</code></td><td>Join a breakout group.</td></tr><tr><td>joinBreakoutMainRoom</td><td><code>() ⇒ void</code></td><td>Join the main room in a breakout session.</td></tr><tr><td>switchCameraEffect</td><td><code>(effectId: string) => void</code></td><td>Enable a camera effect. Use <code>getUsableCameraEffectPresets()</code> to get a valid <code>effectId</code>.</td></tr><tr><td>switchCameraEffectCustom</td><td><code>(imageUrl: string) => Promise&#x3C;void></code></td><td>Enable a camera effect that uses a custom image (from the given URL) as the background.</td></tr><tr><td>clearCameraEffect</td><td><code>() ⇒ void</code></td><td>Disable a camera effect.</td></tr><tr><td>enableAudioDenoiser</td><td><code>() ⇒ void</code></td><td>Enable noise suppression on the local microphone stream. Automatically re-applied if the microphone device is later switched. Use <code>isAudioDenoiserSupported()</code> to check browser support first.</td></tr><tr><td>disableAudioDenoiser</td><td><code>() ⇒ void</code></td><td>Disable noise suppression on the local microphone stream.</td></tr><tr><td>startLiveCaptions</td><td><code>() ⇒ void</code></td><td>Start live captions for local participant only (if configured)</td></tr><tr><td>stopLiveCaptions</td><td><code>() ⇒ void</code></td><td>Stop live captions for local participant only (if configured)</td></tr><tr><td>cancelKnock</td><td><code>() => void</code></td><td>Withdraw a pending knock and leave the waiting room</td></tr><tr><td>holdWaitingParticipant</td><td><code>(participantId: string, response?: string) => void</code></td><td>Put a waiting participant on hold, optionally with a message explaining why (for example "We're running 5 minutes late").<br><br>The participant stays in the waiting room and in your <code>waitingParticipants</code> list, so you can still accept or reject them later. Their connection status changes to <code>knock_on_hold</code> and the message is delivered in <code>knockResponse</code>. See <a href="https://docs.whereby.com/whereby-for-web-browser/react-based-browser-sdk/waiting-room-messages">Waiting room messages</a>.</td></tr></tbody></table>

#### Host-only actions

When a participant provides a valid "host" `roomKey` in the [`RoomConnectionOptions`](/reference/react-hooks-reference/types.md#roomconnectionoptions) when the [useRoomConnection](/reference/react-hooks-reference/useroomconnection.md) hook was created, they will have access to a number of addition host-only actions in rooms:

<table><thead><tr><th width="239.33333333333331">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>lockRoom</td><td><code>(locked: boolean) => void</code></td><td><strong>[Host only]</strong> Lock (<code>true</code>) or unlock (<code>false</code>) the current room</td></tr><tr><td>muteParticipants</td><td><code>(participantIds: string[]) => void</code></td><td><strong>[Host only]</strong> Mute the specified remote participants</td></tr><tr><td>askToSpeak</td><td><code>(participantId: string) => void</code></td><td><p><strong>[Host only]</strong> Ask the specified remote participant to unmute their microphone and speak in the meeting.</p><p>This is typically useful in response to a <code>toggleRaiseHand</code> request from a participant in the meeting.</p></td></tr><tr><td>kickParticipant</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Remove the specified remote participant from the meeting</td></tr><tr><td>endMeeting</td><td><code>(stayBehind?: boolean) => void</code></td><td><p><strong>[Host only]</strong> End the meeting for <em>all</em> remote participants.</p><p>If <code>stayBehind</code> is not provided or is not <code>true</code>, then the local participant will also leave the room</p></td></tr><tr><td>spotlightParticipant</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Put a spotlight on a participant.<br><br>When used in combination with the video grid, the spotlighted participant will move to the presentation stage, and their video cell will be bigger.</td></tr><tr><td>removeSpotlight</td><td><code>(participantId: string) => void</code></td><td><strong>[Host only]</strong> Remove spotlight on a participant.</td></tr><tr><td>startCloudRecording</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Start cloud recording (if configured)</td></tr><tr><td>stopCloudRecording</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Stop cloud recording (if configured)</td></tr><tr><td>startLiveTranscription</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Start live transcription (if configured)</td></tr><tr><td>stopLiveTranscription</td><td><code>() ⇒ void</code></td><td><strong>[Host only]</strong> Stop live transcription (if configured)</td></tr></tbody></table>

#### **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` | <p><strong>\[Host only]</strong> Assign participants to groups, as a map of <code>clientId → groupId</code>.<br><br>Merged with the current assignments: participants you leave out keep theirs, and an empty <code>groupId</code> unassigns a participant.</p>                                                |
| 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`                       | <p><strong>\[Host only]</strong> Broadcast a main-room participant into every breakout group, so they can make an announcement without visiting each group.<br><br>This spotlights the participant, and participants inside a group will see them in <code>state.breakout.broadcastingParticipants</code>.</p> |
| 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](/reference/react-hooks-reference/types.md#notificationevent)                                                                                   | Listen for all events                                                                                                                                                                                                                                        |
| requestAudioEnable  | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestAudioEvent](/reference/react-hooks-reference/types.md#requestaudioevent)> | <p>A host is asking for the local participant to speak in the meeting.</p><p>The local participant should be notified when this event is received and prompted to trigger <code>actions.toggleMicrophone(true)</code> if or when they are ready to speak</p> |
| requestAudioDisable | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[RequestAudioEvent](/reference/react-hooks-reference/types.md#requestaudioevent)> | A host has forcibly muted your microphone                                                                                                                                                                                                                    |
| signalTrouble       | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[SignalStatusEvent](/reference/react-hooks-reference/types.md#signalstatusevent)> | There is a problem with the internet connection and a connection to our signal server can not be established                                                                                                                                                 |
| signalOk            | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[SignalStatusEvent](/reference/react-hooks-reference/types.md#signalstatusevent)> | Internet connectivity is present or it has been restored after `signalTrouble`                                                                                                                                                                               |
| chatMessageReceived | [NotificationEvent](/reference/react-hooks-reference/types.md#notificationevent)<[ChatMessageEvent](/reference/react-hooks-reference/types.md#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 *un*assigned 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`](/reference/react-hooks-reference/types.md#roomconnectionoptions) when the [useRoomConnection](/reference/react-hooks-reference/useroomconnection.md) hook was created, they will have access to a number of addition host-only events in rooms:

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

## Usage

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

[^1]: Only needed when the roomConnectionStatus is `room_locked`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.whereby.com/reference/react-hooks-reference/useroomconnection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.