RelayrtcDocs
Get started
Documentation
React SDK

useStreamGuests and useGuestSession

Authorized host controls and consent-first guest stage state.

Both hooks accept the stable StreamGuestOptions callbacks described by StreamGuestClient. Memoize callbacks when they depend on a selected stream/run, and supply a caller-owned guest-status endpoint to useGuestSession. An operator's paginated roster is not a substitute for that caller snapshot.

useStreamGuests returns roster, pending, error, client, refresh and command for host invitations, requests and moderation. useGuestSession adds joinStage and leaveStage and the room/activeGuestId snapshot. Effects connect polling and disconnect/leave RTC on unmount. Backend identity/role checks still apply when a button is hidden.

React
import { useGuestSession } from '@relayrtc/react'
 
export function GuestStage({ options }: { options: Parameters<typeof useGuestSession>[0] }) {
  const guest = useGuestSession(options)
  const own = guest.roster?.data.find(row => row.state === 'approved' || row.state === 'accepted')
  return <section>
    {own && !guest.room && <button disabled={!!guest.pending}
      onClick={() => { void guest.joinStage(own.id) }}>Join stage with devices off</button>}
    {guest.room && <button
      onClick={() => { void guest.room?.microphone.enable().catch(console.error) }}>Enable microphone</button>}
    {guest.room && <button onClick={() => { void guest.leaveStage() }}>Leave stage</button>}
    {guest.error && <p role="alert">{guest.error.message}</p>}
  </section>
}

Use the returned guest Room for device controls and media snapshots. The guest client owns an independent room; ordinary provider hooks do not automatically observe it. Subscribe to that Room or its capture controls when building a preview. Invitation acceptance, RTC join and device enablement are separate choices. Show camera-denial errors while allowing a permitted microphone; moderator mute is a server permission fence, separate from local mute or device disable. Unmount delayed HLS/DVR players during stage participation and restore authorized viewer playback after leave/removal. See live guests.