> 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/core-sdk-reference/api-reference/roomconnectionclient.md).

# 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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#breakout"><code>BreakoutState</code></a></td><td>Emits breakout config</td></tr><tr><td><code>subscribeToConnectionStatus</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#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>subscribeToLiveCaptions</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#screenshare-2"><code>LiveCaptionsState</code></a> <code>| undefined</code></td><td>Emits live captions status</td></tr><tr><td><code>subscribeToLiveTranscription</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#screenshare-1"><code>LiveTranscriptionState</code></a> <code>| undefined</code></td><td>Emits live transcription status</td></tr><tr><td><code>subscribeToLocalScreenshare</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#clientview"><code>LocalScreenshareState</code></a> <code>| undefined</code></td><td>Emits local screenshare status</td></tr><tr><td><code>subscribeToLocalParticipant</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#screenshare-2"><code>ScreenshareState</code></a><code>[]</code></td><td>Emits screenshare state</td></tr><tr><td><code>subscribeToWaitingParticipants</code></td><td><a href="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#clientview"><code>ClientView</code></a><code>[]</code></td><td>Emits spotlighted participants</td></tr><tr><td><code>subscribeToAudioOnlyMode</code></td><td><code>boolean</code></td><td>Emits <code>true</code> when audio-only mode is enabled and <code>false</code> when it is disabled. Only emits on changes, not on initial subscription. Read the current value from <code>getState().isAudioOnlyModeEnabled</code></td></tr></tbody></table>

{% hint style="info" %}
A host's reply to your knock, the message sent with `holdWaitingParticipant` or `rejectWaitingParticipant`, is not a separate subscription. Read `knockResponse` from `getState()` when `subscribeToConnectionStatus` reports `knock_on_hold` or `knock_rejected`. See `KnockResponse`.
{% endhint %}

## Actions

<table><thead><tr><th width="198.86848958333331">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="/reference/core-sdk-reference/types/roomconnection-types.md#roomjoinedsuccess-less-than-object-greater-than"><code>RoomJoinedSuccess</code></a><code>></code></td><td>Join the room specified in WherebyClientOptions</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, parentId?: string)</code></td><td><code>void</code></td><td><p>Send a chat message to the room.</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><code>removeChatMessage</code></td><td><code>(id: string, sig?: string | null)</code></td><td><code>void</code></td><td><p>Mark a chat message with <code>removed: true</code> in the rooms state's <code>chatMessages</code>.</p><p>To remove a chat message, a <code>sig</code> provided in a previously sent ChatMessage must be included.</p><p>Hosts can remove any chat message without needing to send any <code>sig.</code></p></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>toggleHdMode</code></td><td><code>(enabled?: boolean)</code></td><td><code>void</code></td><td>Enables / disables high-definition (hd) video mode. Default: <code>true</code></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>toggleAudioOnlyMode</code></td><td><code>(enabled?: boolean, options?:</code> <a href="/reference/core-sdk-reference/types/roomconnection-types.md#toggleaudioonlymodeoptions"><code>ToggleAudioOnlyModeOptions</code></a><code>)</code></td><td><code>void</code></td><td>Enables / disables audio-only mode. While enabled, all incoming video is paused and only audio is received. Omitting <code>enabled</code> toggles the current state. See <a href="#audio-only-mode">Audio-only mode</a></td></tr><tr><td><code>toggleWidescreenMode</code></td><td><code>(enabled?: boolean)</code></td><td><code>void</code></td><td>Enables / disables widescreen video mode. Default: <code>true</code></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.</td></tr><tr><td><code>clearCameraEffect</code></td><td></td><td><code>void</code></td><td>Disable a camera effect.</td></tr><tr><td><code>enableAudioDenoiser</code></td><td></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><code>disableAudioDenoiser</code></td><td></td><td><code>void</code></td><td>Disable noise suppression on the local microphone stream.</td></tr><tr><td><code>startLiveCaptions</code></td><td></td><td><code>void</code></td><td>Start live captions for local participant only (if enabled for room)</td></tr><tr><td><code>stopLiveCaptions</code></td><td></td><td><code>void</code></td><td>Stop live captions for local participant only (if enabled for room)</td></tr></tbody></table>

### Room integrations

`startRoomIntegration`, `stopRoomIntegration` and `updateRoomIntegrationProps` share YouTube videos and Miro boards with the room. See [Room Integrations](/reference/core-sdk-reference/api-reference/roomconnectionclient/room-integrations.md).

### Audio-only mode

Audio-only mode pauses all incoming video and keeps audio flowing. It matches the "Disable videos" option in the standard Whereby app. Your own camera stays on unless you pass `autoDisableLocalCamera: true`, and it is not turned back on when you disable audio-only mode.

```javascript
import { WherebyClient } from "@whereby.com/core";

const client = new WherebyClient();
const roomConnection = client.getRoomConnection();

// enable audio-only mode (pauses all incoming video) with...
roomConnection.toggleAudioOnlyMode(true);
// or, optionally also turn off the local camera when enabling...
roomConnection.toggleAudioOnlyMode(true, { autoDisableLocalCamera: true });

// later, disable audio-only mode with...
roomConnection.toggleAudioOnlyMode(false);
// or, toggle the current state by omitting the argument...
roomConnection.toggleAudioOnlyMode();

// get notified whenever audio-only mode changes...
roomConnection.subscribeToAudioOnlyMode((isEnabled) => {
    console.log("Audio-only mode enabled:", isEnabled); // true or false
});
```

{% hint style="info" %}
Audio-only mode only affects what you receive. Other participants are not told when you turn it on.
{% endhint %}

## 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`  | Accept waiting participant                                                                                                                                                                                                                                                                                                                     |
| `holdWaitingParticipant`     | `(participantId: string, response?: string)` | `void`  | <p>Put a waiting participant on hold, optionally with a message explaining why.<br><br>They stay in the waiting room and in the <code>waitingParticipants</code> list, so they can be accepted or rejected later. Their connection status becomes <code>knock\_on\_hold</code> and the message reaches them as <code>knockResponse</code>.</p> |
| `rejectWaitingParticipant`   | `(participantId: string, response?: string)` | `void`  | Reject a waiting participant, optionally with a message.                                                                                                                                                                                                                                                                                       |
| `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                                                                                                                                                                                                                                                                                                      |
| `askToTurnOnScreenshare`     | `(participantId: string)`                    | `void`  | Ask a participant to start screen sharing                                                                                                                                                                                                                                                                                                      |
| `muteParticipants`           | `(participantIds: string[])`                 | `void`  | Mute the specified remote participants                                                                                                                                                                                                                                                                                                         |
| `turnOffParticipantCameras`  | `(participantIds: string[])`                 | `void`  | Turn off the camera of the specificed remote participants                                                                                                                                                                                                                                                                                      |
| `stopParticipantScreenshare` | `(participantId: string)`                    | `void`  | Stop a participants screen share in the meeting                                                                                                                                                                                                                                                                                                |
| `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 (if enabled for room)                                                                                                                                                                                                                                                                                                 |
| `stopLiveTranscription`      |                                              | `void`  | Stop live transcription (if enabled for room)                                                                                                                                                                                                                                                                                                  |
| `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>                                                                                                                                                 |

### Breakout host actions

These require the host role *and* a group (SFU) room. Check `isAvailable` on the `BreakoutState` before offering breakout controls, and read `error` if an action was refused.

| Method                            | Parameters                                      | Description                                                                                                                                                                                                                                        |
| --------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startBreakoutSession`            | `(options: StartBreakoutSessionOptions)`        | Start a breakout session with the given groups, optional participant assignments and session settings                                                                                                                                              |
| `updateBreakoutSession`           | `(options: UpdateBreakoutSessionOptions)`       | Update groups, assignments and/or settings, before or during a session. Only the fields you pass are changed                                                                                                                                       |
| `stopBreakoutSession`             |                                                 | End the session and return participants to the main room                                                                                                                                                                                           |
| `assignBreakoutParticipants`      | `(assignments: { [clientId: string]: string })` | <p>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 one.</p>                            |
| `assignAllBreakoutParticipants`   |                                                 | Randomly distribute all remote participants evenly across the groups                                                                                                                                                                               |
| `unassignAllBreakoutParticipants` |                                                 | Clear every group assignment                                                                                                                                                                                                                       |
| `shuffleBreakoutParticipants`     |                                                 | Re-distribute the already-assigned participants randomly. Unassigned participants are left out                                                                                                                                                     |
| `extendBreakoutTimer`             | `(seconds?: number)`                            | Add time to the running timer. Defaults to 60 seconds                                                                                                                                                                                              |
| `stopBreakoutTimer`               |                                                 | Turn the timer off without ending the session                                                                                                                                                                                                      |
| `broadcastToGroups`               | `(participantId: string)`                       | <p>Broadcast a main-room participant into every breakout group, for announcements that should reach all groups at once.<br><br>This spotlights the participant; participants inside a group see them in <code>broadcastingParticipants</code>.</p> |
| `stopBroadcastToGroups`           | `(participantId: string)`                       | Stop broadcasting the participant into the groups                                                                                                                                                                                                  |

## Events

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

```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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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_CHANGED</code></td><td><code>local-screenshare:state-changed</code></td><td><code>status:</code> <a href="/reference/core-sdk-reference/types/roomconnection-types.md#clientview"><code>LocalScreenshareState</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:</code> <a href="/reference/core-sdk-reference/types/roomconnection-types.md#screenshare-1"><code>LiveTranscriptionState</code></a></td><td>Live transcription is started or stopped</td></tr><tr><td><code>LIVE_CAPTIONS_STATUS_CHANGED</code></td><td><code>live-captions:status-changed</code></td><td><code>status:</code> <a href="/reference/core-sdk-reference/types/roomconnection-types.md#screenshare-2"><code>LiveCaptionsState</code></a></td><td>Live captions is started or stopped for local participant</td></tr><tr><td><code>AUDIO_ONLY_MODE_CHANGED</code></td><td><code>audio-only-mode:changed</code></td><td><code>isEnabled: boolean</code></td><td>Audio-only mode is enabled or disabled</td></tr><tr><td><code>REMOTE_PARTICIPANTS_CHANGED</code></td><td><code>remote-participants:changed</code></td><td><code>participants:</code> <a href="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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="/reference/core-sdk-reference/types/roomconnection-types.md#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`