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

### 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) => void</code></td><td>Reject waiting participant</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></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>

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

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