Types
MediaStreamConstraints
MediaStream
MediaDeviceInfo
RoomConnectionOptions: <Object>
displayName?: string
The name to use for the local participant
(you) in the call
localMediaConstraints?: MediaStreamConstraints
Constraints to use for the local participant media (camera and microphone)
localMedia: LocalMedia
Existing local media to use, as provided by the useLocalMedia hook
roomKey?: string
Room key to use if the local participant should assume a non-standard role in the room, such as host or viewer
ChatMessage: <Object>
id
string
Unique identifier for the chat message
senderId
string
Id of the participant who sent the chat message
parentId
string?
If present, indicates that the chat message is a reply to a chat message whose id matches the given parentId value here. If not present, then this chat message is not a reply to any other chat message(s) previously received
sig
string?
If the current participant is the owner of the chat message (i.e. they sent this chat message) then the service will return this property that can be used to e.g. remove this chat message at a later time (see removeChatMessage API)
text
string
Content of the chat message
timestamp
string
Timestamp of when the message was sent (TODO: format)
removed
boolean
If true then this chat message should be considered removed from any ongoing chat display
LiveCaption: <Object>
resultId
string
Unique identifier for the current live caption result
participantId
string
Identifier of the participant
text
string
The text content of the live caption result (can be updated until the live caption is finalized)
timestamp
number
Timestamp of when the live caption was received
CloudRecordingState: <Object>
status
"requested" | "recording" | "error"
Cloud recording status
startedAt
number
If status is "recording" then this field will show when the cloud recording started
error
string
If status is "error" then this field will show the error message received from the service
LiveTranscriptionState: <Object>
status
null | "requested" | "transcribing" | "error"
Live transcription status
startedAt
number
If status is "transcribing" then this field will show when the live transcription started
error
string
If status is "error" then this field will show the error message received from the service
LiveCaptionsState: <Object>
status
null | "requested" | "captioning" | "error"
Live captions status
startedAt
number
If status is "captioning" then this field will show when the live captions started for the local client
error
string
If status is "error" then this field will show the error message received from the service
captionLog
Array<LiveCaption>
Zero or more live captions data objects received from the Whereby Live Captions service. Entries in this array are removed after 5 seconds of inactivity since their last update.
LocalScreenshareState: <Object>
status: "requested" | "screensharing" | "error"
Local screen sharing status
startedAt?: string
If status is "screensharing" then this field will show when the local screen share started. Otherwise this field will be undefined.
error?: string
If status is "error" then this field will provide an error object received from the service. Otherwise this field will be undefined.
LocalParticipant: <Object>
displayName
string
Display name of the local participant (you)
id
string
Local participant id
roleName
string
The role of the local participant. This will be one of the following values:
none, visitor, granted_visitor, viewer, granted_viewer, host, recorder, streamer
isAudioEnabled
boolean
The local participant has their microphone enabled
isVideoEnabled
boolean
The local participant has their camera enabled
isLocalParticipant
true
Always set to true. Can be used to easily identify the local participant if in an array with eg remote participants
breakoutGroup
string | null
Id of the breakout group the local participant is currently in. null or empty when they are in the main room
breakoutGroupAssigned
string
Id of the breakout group the local participant has been assigned to by a host. Empty string when unassigned. Compare with breakoutGroup to tell whether they still need to join
RemoteParticipant: <Object>
displayName
string
Display name of the remote participant
id
string
Id of the remote
participant
roleName
string
The role of the local participant. This will be one of the following values:
none, visitor, granted_visitor, viewer, granted_viewer, host, recorder, streamer
isAudioEnabled
boolean
The remote participant has their camera enabled
isVideoEnabled
boolean
The remote participant has their microphone enabled
breakoutGroup
string | null
Id of the breakout group the participant is currently in. null or empty when they are in the main room
breakoutGroupAssigned
string
Id of the breakout group the participant has been assigned to. Empty string when unassigned, use it to render assignment state in a host's breakout panel
ClientView: <Object>
A client view can be either a participant or a screenshare.
id
string
Internal id
clientId
string
Id of the participant
displayName
string
Display name of the participant or screenshare
isLocalClient
boolean
Is the client view owned by the local participant?
isAudioEnabled
boolean
The client view has their microphone enabled
isVideoEnabled
boolean
The client view has their camera enabled
isPresentation
boolean
The client view is a presentation (screenshare)
Screenshare: <Object>
participantId
string
Id of the participant owning the screenshare
id
string
Id of the screenshare
hasAudioTrack
boolean
isLocal
boolean
Is the screenshare owned by the local participant?
RoomConnectionStatus: <string>
"ready"
Ready to join the room
"connecting"
Currently in the process of doing the initial connection in the room
"connected"
Connected in the room, this is the "stable" state
"room_locked"
Connection failed due to the room being locked, a knock is required to proceed
"knocking"
Waiting for the room host to respond to the knock request
"knock_on_hold"
The host put your knock request on hold. You are still in the waiting room and the host can accept or reject you later, so keep showing a waiting state rather than sending the participant away.
If the host included a message, it is available in knockResponse.
"knock_rejected"
The host rejected your knock request. If the host included a message, it is available in knockResponse.
"kicked"
The current participant was kicked from the room.
This can happen in the following scenarios:
when a meeting host ends the meeting for all participants in the room
when a meeting host kicks the current participant individually from the room
"leaving"
The current participant has invoked the leaveRoom action to exit the room.
"left"
The current participant has now successfully left the room and all other room participants have been notified.
"disconnected"
The current participant has been disconnected from the room due to an unplanned loss of network connection.
This can happen during temporary network outage (e.g. loss of network or switching networks). If/when the network connection returns the SDK will change the room connection status to reconnectingautomatically.
"reconnecting"
A lost internet connection has been re-established.
The SDK will now automatically re-connect the current participant to the previous room and the room connection state will change to either: a.) knocking if the room is locked, or; b.) connected if the room is unlocked.
LiveStreamState: <Object>
status
"streaming"
Live streaming is in progress
startedAt
number
When the live stream started
WaitingParticipant: <Object>
id
string
Id of the participant waiting to be let in
displayName
string
WaitingParticipant on hold
A participant that a host has put on hold stays in the waitingParticipants list, they are still in the waiting room, just told to wait. The list entry itself is unchanged; the on-hold state lives on the waiting participant's own client, as the knock_on_hold connection status. Track locally which participants you put on hold if you want to reflect that in the host UI.
KnockResponse: <Object>
The host's response to your knock, delivered when they put you on hold or reject you. Available as state.knockResponse. It is null until a response arrives, and a host who responds without writing anything produces a response with no message so always guard on knockResponse?.message rather than on knockResponse alone.
message
string?
The message the host wrote when calling holdWaitingParticipant or rejectWaitingParticipant. Absent when the host responded without a message
sender
KnockResponseSender?
Who the message came from. Populated with the host's display name for on-hold responses; rejections are delivered without sender details
KnockResponseSender: <Object>
displayName
string | null?
Display name of the host who responded
avatarUrl
string | null?
Avatar of the host who responded, when available
Breakout: <Object>
The full breakout state of the room, as state.breakout. Timestamp fields are epoch milliseconds unless noted, so they can be compared directly against Date.now() to drive countdowns.
isAvailable
boolean
Breakout groups require a group (SFU) room. false in peer-to-peer rooms, where breakout actions are refused
error
string | null
Set when a breakout action was refused, for example starting a session in a peer-to-peer room
isActive
boolean
The state of the breakout session. If it's true, a breakout session is currently ongoing in the room
currentGroup
{ id: string, name: string } | null
The breakout group that the local participant is currently in. null if they are not in a group
groups
{ [groupId: string]: string } | null
The configured groups, as a map of group id to group name
enforceAssignment
boolean
When true, participants are meant to stay in the group they are assigned to. The SDK surfaces the flag but does not block joinBreakoutGroup, honour it in your UI, for example by only offering the assigned group
autoMoveToGroup
boolean
When true, assigned participants are moved into their group automatically when the session starts
moveToGroupGracePeriod
number | null
Seconds between the session starting and the automatic move into the group. Gives you a window to show a countdown and a "join now" button. Defaults to 10 when autoMoveToGroup is enabled
autoMoveToMain
boolean
When true, participants are moved back to the main room automatically when the session ends
moveToMainGracePeriod
number | null
Seconds between the session ending and the automatic move back to the main room. Defaults to 30 when autoMoveToMain is enabled
breakoutTimerSetting
boolean
Whether the session runs on a timer
breakoutTimerDuration
number
Length of the timer in seconds. Defaults to 1800 (30 minutes) when the timer is enabled without a duration
startedAt
Date | null
When the breakout session was started
endTime
number | null
When the timer runs out, as a timestamp. Use it to render the remaining time
moveToGroupAt
number | null
Timestamp of the upcoming automatic move into the group, or null when autoMoveToGroup is off
moveToMainAt
number | null
Timestamp of the upcoming automatic move back to the main room, or null when autoMoveToMain is off
groupedParticipants
{ clients: ClientView[], group: { id: string, name: string } | null }[]
List of the groups in the current breakout session, including the participants in each group
participantsInCurrentGroup
ClientView[]
Participants in the local participant's current group. Empty list when they are not in a group
broadcastingParticipants
ClientView[]
Main-room participants currently being broadcast into every group. Only populated for participants who are inside a group
BreakoutSessionSettings: <Object>
The settings shared by startBreakoutSession and updateBreakoutSession. All fields are optional, anything you leave out keeps its current value.
enforceAssignment
boolean?
Signal that participants should stay in their assigned group instead of picking one. Surfaced as state.breakout.enforceAssignment for your UI to honour
autoMoveToGroup
boolean?
Move assigned participants into their group automatically when the session starts
moveToGroupGracePeriod
number | null?
Seconds to wait before that automatic move. Defaults to 10 if you enable autoMoveToGroup without setting it
autoMoveToMain
boolean?
Move participants back to the main room automatically when the session ends
moveToMainGracePeriod
number | null?
Seconds to wait before that automatic move. Defaults to 30 if you enable autoMoveToMain without setting it
breakoutTimerSetting
boolean?
Run the session on a timer
breakoutTimerDuration
number?
Timer length in seconds. Defaults to 1800 (30 minutes) if you enable the timer without setting it
StartBreakoutSessionOptions: <Object>
BreakoutSessionSettings, plus:
groups
{ [groupId: string]: string }
Required. The groups to create, as a map of group id to group name
assignments
{ [clientId: string]: string }?
Which participants go where, as a map of clientId → groupId
BreakoutGroupAssignedEvent: <Object>
group
string
Id of the group the local participant was assigned to
groupName
string
Name of that group
BreakoutTimerEvent: <Object>
Carries no props. The message on the NotificationEvent describes what happened, and the current timer state is available in state.breakout.
ToggleAudioOnlyModeOptions: <Object>
autoDisableLocalCamera?: boolean
Also turn off the local camera when enabling audio-only mode. The camera is not turned back on when audio-only mode is disabled
Room integrations
Types for room integrations. All of them are exported from @whereby.com/browser-sdk/react. RoomIntegrations is the React name for core's RoomIntegrationsState.
RoomIntegrations: <Object>
state.roomIntegrations on useRoomConnection.
hasFetched
boolean
true once the room's list of integrations has loaded
isFetching
boolean
true while the list is loading
RoomIntegration: <Object>
An integration the room offers, such as YouTube.
roomIntegrationId
string
Id to pass to startRoomIntegration
name
string
Machine name, for example "youtube" or "miro"
title
string
Display name, for example "YouTube"
description
string
Short description, for menus
type
string
The integration's category, for example "video"
icons
{ small: string; large: string }
Icon URLs
link
{ href: string; text: string }
The provider's website
contentTagName
string
Custom element name of the content, for example "youtube-integration-contentframe"
entrypoint
string
URL of the integration's script. Used by the Whereby app, not by the SDK
webview
string
URL of the page that shows running content. The picker is bootstrap.html next to it
matcher
RegExp
Matches links this integration can show
isEmbeddable
boolean
true if the integration can run in an SDK app
RoomIntegrationSession: <Object>
A running integration as the server describes it.
roomIntegrationSessionId
string
Id of the running session. Pass it to stopRoomIntegration
roomIntegrationId
string
The integration that's running
breakoutGroupId
string
The breakout group it runs in. "" in the main room
tagName
string
Custom element name of the content
shareUrl
string
The https URL of the shared content
clientId
string
Id of the participant who started it
roomIntegrationSessionStartedAt
number | null
When it started, in epoch milliseconds
RoomIntegrationSessionView: <Object>
The entries in state.roomIntegrations.running. A RoomIntegrationSession, plus:
isPresenter
boolean
true if you started it
presenterDisplayName
string | null
Display name of the participant who started it. null if that's you, or if they've left
canStop
boolean
true if you can stop it: you started it, or you're a host
RoomIntegrationProps: <Object>
A flat object of primitive values. Each integration defines its own keys. YouTube uses keys such as videoref, seek, paused and aspectratio.
RoomIntegrationErrorDetail: <Object>
message
string
A description for developers
RoomIntegrationError: <string>
"unknown_integration", "integration_not_enabled", "invalid_content", "not_allowed_to_stop", "not_in_a_room", "forbidden", "missing_parameters", "invalid_parameters", "internal_server_error" or "unknown". See Errors for what each one means.
RoomIntegrationContent: <Object>
What startRoomIntegration needs besides the integration id. Returned by roomIntegrationContent.youtube() and .miro().
tagName
string
Custom element name of the content
shareUrl
string
The https URL of the content
RoomIntegrationPickerResult, the value onPicked receives, has the same shape.
RoomIntegrationPickerOutcome: <Object>
What subscribeToRoomIntegrationPicker passes to onOutcome.
RoomIntegrationIframeProps: <Object>
Returned as iframeProps by useRoomIntegrationPicker and useRoomIntegrationView. Spread all of it onto your <iframe>.
ref
React.RefObject<HTMLIFrameElement | null>
Lets the hook check that messages come from this frame. Required
src
string
The page to load
title
string
Accessible name of the frame
allow
string
Permissions policy for the frame
CellView: <Object>
A cell in the grid layout, as returned by useGrid. Integration cells are only returned when useGrid is called with includeIntegrations: true. Either a VideoCellView or an IntegrationCellView, told apart by type.
type
"video" | "integration"
What the cell shows
cellId
string
Stable id. The participant's id for video cells, "room-integration:<roomIntegrationSessionId>" for integration cells. Use it as the React key
clientId
string
Same as cellId for integration cells
aspectRatio
number?
Width divided by height
isDraggable
boolean?
Whether the cell can be dragged. false for integration cells
isSubgrid
boolean?
true for cells in the subgrid
Video cells can also carry avatarSize, cellPaddings and isPlaceholder, used by the default layout.
Events
NotificationEvent
All events are of type NotificationEvent, with
Event Props
StickyReactionEvent
stickyReaction
{ reaction: string, timestamp: string } | null
RequestAudioEvent
enable
boolean
RequestScreenshareEvent
enable
boolean
SignalStatusEvent
ChatMessageEvent
Last updated
Was this helpful?