# RoomConnectionClient

```jsx
const roomConnection = client.getRoomConnection()
```

RoomConnectionClient manages entire room connection.  It exposes state subscriptions and provides actions to manage and observe remoteParticipants and in room actions. Room connection s retrieved from the WherebyClient.

## Utilities

| Method     | Returns               | Description                                |
| ---------- | --------------------- | ------------------------------------------ |
| `getState` | `RoomConnectionState` | Returns the entire room connection state   |
| `destroy`  | `void`                | Destroy the RoomConnectionClient instance. |

## State Subscriptions

All subscribe methods follow this format:

* Call signature: `subscribeX(callback: (payload: T) => void: () => void`
* Contract: Invokes a callback on initial subscription and whenever the state changes.
* Returns: an unsubscribe function

### Methods

<table><thead><tr><th width="266.87677001953125">Method</th><th width="423.48443603515625">Payload Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscribeToChatMessages</code></td><td> <a href="../../types/roomconnection-types#chatmessage"><code>ChatMessage</code></a><code>[]</code> </td><td>Emits chat messages from remote participants</td></tr><tr><td><code>subscribeToCloudRecording</code></td><td><a href="../../types/roomconnection-types#screenshare"><code>CloudRecordingState</code></a> <code>| undefined</code></td><td>Emits cloud recording status</td></tr><tr><td><code>subscribeToBreakoutConfig</code></td><td><a href="../../types/roomconnection-types#breakout"><code>BreakoutState</code></a> </td><td>Emits breakout config </td></tr><tr><td><code>subscribeToConnectionStatus</code></td><td><a href="../../types/roomconnection-types#connectionstatus-less-than-string-greater-than"><code>ConnectionStatus</code></a></td><td>Emits the connection status</td></tr><tr><td><code>subscribeToLiveStream</code></td><td><code>{ status: "streaming" } | undefined</code></td><td>Emits streaming status</td></tr><tr><td><code>subscribeToLiveTranscription</code></td><td><a href="../../types/roomconnection-types#screenshare-1"><code>LiveTranscriptionState</code></a> <code>| undefined</code></td><td>Emits live transcription status</td></tr><tr><td><code>subscribeToLocalScreenshareStatus</code></td><td><p></p><p> <a href="../../types/roomconnection-types#localscreensharestatus-less-than-string-greater-than"><code>LocalScreenshareStatus</code></a> <code>| undefined</code></p></td><td>Emits local screenshare status</td></tr><tr><td><code>subscribeToLocalParticipant</code></td><td><a href="../../types/roomconnection-types#localparticipantstate-less-than-object-greater-than"><code>LocalParticipantState</code></a></td><td>Emits local participant state</td></tr><tr><td><code>subscribeToRemoteParticipants</code></td><td><a href="../../types/roomconnection-types#remoteparticipantstate-less-than-object-greater-than"><code>RemoteParticipantState</code></a><code>[]</code> </td><td>Emits the remote participant state</td></tr><tr><td><code>subscribeToScreenshares</code></td><td><a href="../../types/roomconnection-types#screenshare-2"><code>ScreenshareState</code></a><code>[]</code> </td><td>Emits screenshare state</td></tr><tr><td><code>subscribeToWaitingParticipants</code></td><td><a href="../../types/roomconnection-types#waitingparticipantstate-less-than-object-greater-than"><code>WaitingParticipantState</code></a><code>[]</code></td><td>Emits waiting participants</td></tr><tr><td><code>subscribeToSpotlightedParticipants</code></td><td><a href="../../types/roomconnection-types#clientview"><code>ClientView</code></a><code>[]</code></td><td>Emits spotlighted participants</td></tr></tbody></table>

## Actions

<table><thead><tr><th width="186.70442708333331">Method</th><th width="146.5767822265625">Parameters</th><th>Returns</th><th>Description</th></tr></thead><tbody><tr><td><code>joinRoom</code></td><td></td><td> <code>Promise&#x3C;</code><a href="../../types/roomconnection-types#roomjoinedsuccess-less-than-object-greater-than"><code>RoomJoinedSuccess</code></a><code>></code></td><td><p>Join the room specified in WherebyClientOptions</p><p></p></td></tr><tr><td><a data-footnote-ref href="#user-content-fn-1"><code>knock</code></a></td><td></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><code>cancelKnock</code></td><td></td><td><code>void</code></td><td>Cancel the knock request</td></tr><tr><td><code>setDisplayName</code></td><td><code>(displayName: string)</code></td><td><code>void</code></td><td>Change your display name</td></tr><tr><td><code>sendChatMessage</code></td><td><code>(text: string)</code></td><td> <code>void</code></td><td>Send a chat message to the room</td></tr><tr><td><code>toggleCamera</code></td><td><code>(enabled?: boolean)</code></td><td><code>void</code></td><td>Change the state of your camera</td></tr><tr><td><code>toggleMicrophone</code></td><td><code>(enabled?: boolean)</code></td><td> <code>void</code></td><td>Change the state of your microphone</td></tr><tr><td><code>toggleLowDataMode</code></td><td><code>(enabled?: boolean)</code></td><td>  <code>void</code></td><td>Change the state of low data mode</td></tr><tr><td><code>toggleRaiseHand</code></td><td><code>(enabled?: boolean)</code></td><td>  <code>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><code>startScreenshare</code></td><td></td><td>  <code>void</code></td><td>Start screen share</td></tr><tr><td><code>stopScreenshare</code></td><td></td><td>  <code>void</code></td><td>Stop screen share</td></tr><tr><td><code>leaveRoom</code></td><td></td><td>  <code>void</code></td><td>Leave the room</td></tr><tr><td><code>joinBreakoutGroup</code></td><td><code>(group: string)</code></td><td> <code>void</code></td><td>Join a breakout group. </td></tr><tr><td><code>joinBreakoutMainRoom</code></td><td></td><td><code>void</code></td><td>Join the main room in a breakout session.</td></tr><tr><td><code>switchCameraEffect</code></td><td><code>(effectId: string)</code></td><td><code>void</code></td><td>Enable a camera effect. <code>@whereby.com/camera-effects</code> needs to be installed for this to work</td></tr><tr><td><code>clearCameraEffect</code></td><td></td><td><code>void</code></td><td>Disable a camera effect.<code>@whereby.com/camera-effects</code> needs to be installed for this to work</td></tr></tbody></table>

## Host-only actions

When a participant provides a valid "host" `roomKey` in the [`RoomConnectionOptions`](https://docs.whereby.com/reference/react-hooks-reference/types#roomconnectionoptions-less-than-object-greater-than) when the RoomConnectionClient is initialized, they will have access to a number of addition host-only actions in rooms:

| Method                      | Parameters                        | Returns | Description                                                                                                                                                                                                              |
| --------------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lockRoom`                  | `(locked: boolean)`               | `void`  | Lock (`true`) or unlock (`false`) the current room                                                                                                                                                                       |
| `acceptWaitingParticipant`  | `(participantId: string) => void` | `void`  | Accept waiting participant                                                                                                                                                                                               |
| `rejectWaitingParticipant`  | `(participantId: string) => void` | `void`  | Reject waiting participant                                                                                                                                                                                               |
| `askToSpeak`                | `(participantId: string)`         | `void`  | <p>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> |
| `askToTurnOnCamera`         | `(participantId: string)`         | `void`  | Ask a participant to turn on their camera                                                                                                                                                                                |
| `muteParticipants`          | `(participantIds: string[])`      | `void`  | Mute the specified remote participants                                                                                                                                                                                   |
| `turnOffParticipantCameras` | `(participantIds: string[])`      | `void`  | Turn off the camera of the specificed remote participants                                                                                                                                                                |
| `kickParticipant`           | `(participantId: string)`         | `void`  | Remove the specified remote participant from the meeting                                                                                                                                                                 |
| `spotlightParticipant`      | `(participantId: string)`         | `void`  | <p>Put a spotlight on a participant.</p><p>When used in combination with the video grid, the spotlighted participant will move to the presentation stage, and their video cell will be bigger.</p>                       |
| `removeSpotlight`           | `(participantId: string)`         | `void`  | Remove spotlight on a participant.                                                                                                                                                                                       |
| `startCloudRecording`       |                                   | `void`  | Start cloud recording                                                                                                                                                                                                    |
| `stopCloudRecording`        |                                   | `void`  | Stop cloud recording                                                                                                                                                                                                     |
| `startLiveTranscription`    |                                   | `void`  | Start live transcription                                                                                                                                                                                                 |
| `stopLiveTranscription`     |                                   | `void`  | Stop live transcription                                                                                                                                                                                                  |
| `endMeeting`                | `(stayBehind?: boolean)`          | `void`  | <p>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>                           |

## Events

`RoomConnectionClient` extends `EventEmitter` . You can listen to lifecycle and state change events directly:&#x20;

```jsx
import { REMOTE_PARTICIPANTS_CHANGED } from "@whereby.com/core";

const roomConnection = client.getRoomConnection();

function logChatMessage(message: ChatMessage) {
    console.log("New chat message received", message);
}

roomConnection.on(REMOTE_PARTICIPANTS_CHANGED, logChatMessage);
```

#### RoomConnectionEvents

<table><thead><tr><th width="260.01739501953125">Event (constant)</th><th width="188.490478515625">Event name (string)</th><th width="398.95318603515625">Payload</th><th>Emitted when</th></tr></thead><tbody><tr><td><code>BREAKOUT_CONFIG_CHANGED</code></td><td><code>breakout:config-changed</code></td><td><code>config:</code><a href="../../types/roomconnection-types#breakout"><code>BreakoutState</code></a> </td><td>Breakout config changes</td></tr><tr><td><code>CHAT_NEW_MESSAGE</code></td><td><code>chat:new-message</code></td><td><code>messages:</code> <a href="../../types/roomconnection-types#chatmessage"><code>ChatMessage</code></a><code>[]</code> </td><td>A new chat message is received</td></tr><tr><td><code>CLOUD_RECORDING_STATUS_CHANGED</code></td><td><code>cloud-recording:status-changed</code></td><td><code>{ status: "requested" | "recording" | "error" }, startedAt?: string, error?: string } | undefined</code></td><td>Cloud recording is started or stopped</td></tr><tr><td><code>CONNECTION_STATUS_CHANGED</code></td><td><code>connection:status-changed</code></td><td><code>status:</code> <a href="../../types/roomconnection-types#connectionstatus-less-than-string-greater-than"><code>ConnectionStatus</code></a>      </td><td>There's a change to connection status</td></tr><tr><td><code>LOCAL_PARTICIPANT_CHANGED</code></td><td><code>local-participant:changed</code></td><td><code>participant?:</code> <a href="../../types/roomconnection-types#localparticipantstate-less-than-object-greater-than"><code>LocalParticipantState</code></a>  </td><td>There's a change to the local participant state</td></tr><tr><td><code>LOCAL_SCREENSHARE_STATUS_CHANGED</code></td><td><code>local-screenshare:status-changed</code></td><td><code>status?:</code> <a href="../../types/roomconnection-types#localscreensharestatus-less-than-string-greater-than"><code>LocalScreenshareStatus</code></a> </td><td>Local screenshare is started or stopped</td></tr><tr><td><code>LIVE_TRANSCRIPTION_STATUS_CHANGED</code></td><td><code>live-transcription:status-changed</code></td><td><code>{ status: "requested" | "transcribing" | "error" }, startedAt?: string, error?: string } | undefined</code></td><td>Live transcription is started or stopped</td></tr><tr><td><code>REMOTE_PARTICIPANTS_CHANGED</code></td><td><code>remote-participants:changed</code></td><td><code>participants:</code> <a href="../../types/roomconnection-types#remoteparticipantstate-less-than-object-greater-than"><code>RemoteParticipantState</code></a><code>[]</code> </td><td>There's a change to the remote participant state</td></tr><tr><td><code>SCREENSHARE_STARTED</code></td><td><code>screenshare:started</code></td><td><code>screenshares:</code> <a href="../../types/roomconnection-types#screenshare-2"><code>ScreenshareState</code></a><code>[]</code> </td><td>Remote screenshare is started or stopped</td></tr><tr><td><code>ROOM_JOINED</code></td><td><code>room:joined</code></td><td><code>room:</code> <a href="../../types/roomconnection-types#roomjoinedevent-less-than-object-greater-than"><code>RoomJoinedEvent</code></a> </td><td>A client joins the room</td></tr><tr><td><code>ROOM_JOINED_ERROR</code></td><td><code>room:joined:error</code></td><td><code>error: RoomJoinedErrors | string</code>     </td><td>A client leaves the room</td></tr><tr><td><code>WAITING_PARTICIPANT_JOINED</code></td><td><code>waiting-participant:joined</code></td><td><code>participant:</code> <a href="../../types/roomconnection-types#waitingparticipantstate-less-than-object-greater-than"><code>WaitingParticipantState</code></a>  </td><td>A client joins the waiting room</td></tr><tr><td><code>WAITING_PARTICIPANT_LEFT</code></td><td><code>waiting-participant:left</code></td><td><code>participantId: string</code>   </td><td>A client leaves the waiting room</td></tr><tr><td><code>SPOTLIGHT_PARTICIPANT_ADDED</code></td><td><code>spotlight:participant-added</code></td><td><code>particpant:</code> <a href="../../types/roomconnection-types#clientview"><code>ClientView</code></a></td><td>A client is spotlighted</td></tr><tr><td><code>SPOTLIGHT_PARTICIPANT_REMOVED</code></td><td><code>spotlight:participant-removed</code></td><td><code>participantId: string</code></td><td>A client is removed from the spotlight</td></tr><tr><td><code>STREAMING_STARTED</code></td><td><code>streaming:started</code></td><td><code>streaming:</code> <a href="../../types/roomconnection-types#livestreamstate"><code>LiveStreamState</code></a></td><td>Streaming is started</td></tr><tr><td><code>STREAMING_STOPPED</code></td><td><code>streaming:stopped</code></td><td><code>void</code></td><td>Streaming is stopped</td></tr></tbody></table>

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


---

# Agent Instructions: 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:

```
GET https://docs.whereby.com/reference/core-sdk-reference/api-reference/roomconnectionclient.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.