SignalWire Browser SDK

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Reference for the SignalWire Browser SDK, every class, error, function, interface, and type the SDK exports. If you’re new to the SDK, start with the Overview or jump straight to SignalWire, the top-level client that owns the WebSocket session and produces every other entity in the SDK.

The reference is organized by surface area. Classes are the things you interact with, the client, an active call, a participant, the directory. Functions are top-level helpers for logging, embeddable integrations, and type narrowing. Errors are the typed exceptions the SDK throws so you can branch on them with instanceof. Most stateful values are exposed in two complementary forms, a snapshot getter (audioMuted) and an observable suffixed with $ (audioMuted$) for reactive UI binding.

Install

npm\ \ @signalwire/js GitHub\ \ signalwire-js

npm install @signalwire/js@latest rxjs

RxJS is a peer dependency, the SDK uses observables for all reactive state. See the RxJS Primer.

Classes

SignalWire\ \ Main entry point for the SignalWire Browser SDK. Address\ \ Represents a contact or room in the directory. Participant\ \ Represents a participant in a call. SelfParticipant\ \ The local participant in a call, with additional device and media control. SelfCapabilities\ \ Manages the capability state for the self participant. User\ \ Authenticated user profile. ClientPreferences\ \ Public preferences API for configuring SDK behavior. WebRTCCall\ \ Concrete WebRTC call implementation.

Credential Providers

EmbedTokenCredentialProvider\ \ Exchanges an embed token for a SAT via the host’s token endpoint. StaticCredentialProvider\ \ Returns a fixed set of credentials.

Errors

CallCreateError\ \ Thrown when a call cannot be created. CollectionFetchError\ \ Thrown when fetching a collection page fails. DeviceTokenError\ \ Thrown when device token issuance or validation fails. DPoPInitError\ \ Thrown when DPoP key initialization fails. InvalidCredentialsError\ \ Thrown when the SDK is rejected by the auth backend. MediaTrackError\ \ Thrown when a media track operation fails. MessageParseError\ \ Thrown when an incoming message cannot be parsed. OverconstrainedFallbackError\ \ Thrown when getUserMedia fails with OverconstrainedError and all fallback levels are exhausted. PreflightError\ \ Thrown when the preflight connectivity test fails. RecoveryError\ \ Thrown when a recovery attempt fails. TokenRefreshError\ \ Thrown when an access-token refresh fails. UnexpectedError\ \ Catch-all for unexpected SDK errors. VertoPongError\ \ Thrown when a Verto ping/pong heartbeat fails.

Functions

embeddableCall\ \ Creates a call using an embed token for simple, embeddable integrations. isSelfParticipant\ \ Type guard that checks if a participant is the local SelfParticipant. getLogger\ \ Retrieve the current SDK logger instance. setLogger\ \ Replace the built-in logger with a custom implementation. Pass null to restore defaults. setLogLevel\ \ Set the log level for the built-in logger. No effect when a custom logger is set via setLogger(). setDebugOptions\ \ Configure debug options (e.g., { logWsTraffic: true }).

Variables

ready

const ready: boolean = true

Flag indicating the library has been loaded and is ready to use. For UMD builds: window.SignalWire.ready. For ES modules: import { ready } from '@signalwire/js'.

version

const version: string = __VERSION__

Library version from package.json, injected at build time.

Address

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

An Address represents a single directory entry, a contact, room, or any other dialable endpoint exposed by the user’s fabric. Address instances are produced by the Directory returned from SignalWire.directory$; applications do not construct them directly.

Beyond identity metadata (display name, type, cover/preview URLs), Address exposes lazy observables for the entry’s interaction history ( history$) and text messages ( textMessages$). Subscribing to either kicks off the underlying REST fetch and pages additional results in on demand. Use textMessage to send a new message to the address.

The reactive accessors (displayName$, type$, locked$, etc.) emit when the server pushes an update for this address; their snapshot counterparts (displayName, type, locked) return the most recent cached value. The instance is destroyed when the parent directory page is released.

Extends

Destroyable

Constructors

Constructor

new Address(addressId, conversationManager, addressProvider): Address

Parameters

addressId

stringRequired

Server-assigned ID of the address.

conversationManager

ConversationsProviderRequired

Provider used to load and manage conversations for this address.

addressProvider

AddressProvider<Address>Required

Provider used to load directory entries for this address.

Properties

history$

Observable<EntityCollectionTransformed<GetConversationMessageResponse, AddressHistory<Address>> | undefined>

Observable of call history for this address. Lazily loads conversation data. See AddressHistory.

textMessages$

Observable<EntityCollectionTransformed<GetConversationMessageResponse, TextMessage<Address>> | undefined>

Observable of text messages for this address. Lazily loads conversation data. See TextMessage.

Accessors

activity$\ \ Observable of active call states for this address. channels$\ \ Observable of available communication channels (audio, video, messaging). coverUrl$\ \ Observable of the cover image URL. createdAt\ \ ISO timestamp of when the address was created. defaultChannel\ \ Default communication channel URI (video for rooms, audio otherwise). destroyed$\ \ Observable that emits when the instance is destroyed displayName$\ \ Observable of the human-readable display name. history\ \ Collection of call history entries for this address, with pagination support. id\ \ Unique address identifier. locked$\ \ Observable indicating whether the address (room) is locked. name\ \ Address name (resource identifier). previewUrl$\ \ Observable of the preview image URL. resourceId$\ \ Observable of the underlying resource ID. textMessage\ \ Collection of text messages for this address, with pagination support. type$\ \ Observable of the resource type (e.g. 'room', 'subscriber').

Methods

destroy\ \ Cleans up subscriptions and subjects owned by this instance. sendText\ \ Sends a text message to this address.

activity$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get activity$(): Observable<CallState[]>

Observable of active call states for this address.

Not yet implemented in v4.activity$ and activity require presence support and throw when accessed.

Throws

Requires presence support.

activity

get activity(): CallState[]

Active call states for this address.

Throws

Requires presence support.

Examples

address.activity$.subscribe((activity) => {
  console.log('activity:', activity);
});

channels$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get channels$(): Observable<{ audio?: string; messaging?: string; video?: string; }>

Observable of available communication channels (audio, video, messaging).

channels

get channels(): object

Available communication channels.

audio?

optional audio?: string

messaging?

optional messaging?: string

video?

optional video?: string

Examples

address.channels$.subscribe((channels) => {
  console.log('channels:', channels);
});

coverUrl$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get coverUrl$(): Observable<string | undefined>

Observable of the cover image URL.

coverUrl

get coverUrl(): string | undefined

Cover image URL.

Examples

address.coverUrl$.subscribe((coverUrl) => {
  console.log('coverUrl:', coverUrl);
});

createdAt

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get createdAt(): string

ISO timestamp of when the address was created.

Examples

console.log(address.createdAt);

defaultChannel

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get defaultChannel(): string | undefined

Default communication channel URI (video for rooms, audio otherwise).

Examples

console.log(address.defaultChannel);

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Returns

void

Inherited from

Destroyable.destroy

Examples

address.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Destroyable.destroyed$

Examples

address.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

displayName$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get displayName$(): Observable<string>

Observable of the human-readable display name.

displayName

get displayName(): string

Human-readable display name.

Examples

address.displayName$.subscribe((displayName) => {
  console.log('displayName:', displayName);
});

history

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get history(): EntityCollectionTransformed<GetConversationMessageResponse, AddressHistory<Address>> | undefined

Collection of call history entries for this address, with pagination support.

Returns undefined until history$ has been subscribed to (lazy-loaded). Filters to 'log' subtype messages including kind, status, start/end times.

See

history$ to trigger lazy loading.

Examples

console.log(address.history);

id

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get id(): string

Unique address identifier.

Examples

console.log(address.id);

locked$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get locked$(): Observable<boolean>

Observable indicating whether the address (room) is locked.

locked

get locked(): boolean

Whether the address (room) is locked.

Examples

address.locked$.subscribe((locked) => {
  console.log('locked:', locked);
});

name

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get name(): string

Address name (resource identifier).

Examples

console.log(address.name);

previewUrl$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get previewUrl$(): Observable<string | undefined>

Observable of the preview image URL.

previewUrl

get previewUrl(): string | undefined

Preview image URL.

Examples

address.previewUrl$.subscribe((previewUrl) => {
  console.log('previewUrl:', previewUrl);
});

resourceId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get resourceId$(): Observable<string>

Observable of the underlying resource ID.

resourceId

get resourceId(): string

Underlying resource ID.

Examples

address.resourceId$.subscribe((resourceId) => {
  console.log('resourceId:', resourceId);
});

sendText

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

sendText(text): Promise<void>

Sends a text message to this address.

Parameters

text

stringRequired

The message text to send.

Returns

Promise<void>

Examples

await address.sendText('Hello!');

See

textMessage / textMessages$, read the conversation thread.
history, call log for the same conversation.

textMessage

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get textMessage(): EntityCollectionTransformed<GetConversationMessageResponse, TextMessage<Address>> | undefined

Collection of text messages for this address, with pagination support.

Returns undefined until textMessages$ has been subscribed to (lazy-loaded). Filters to 'chat' subtype messages from the conversation.

See

textMessages$ to trigger lazy loading.
sendText to send a new message.

Examples

console.log(address.textMessage);

type$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get type$(): Observable<ResourceType>

Observable of the resource type (e.g. 'room', 'subscriber').

type

get type(): ResourceType

Resource type (e.g. 'room', 'subscriber').

Examples

address.type$.subscribe((type) => {
  console.log('type:', type);
});

ClientPreferences

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

ClientPreferences is the central knob panel for every tunable runtime default in the SDK, connection timeouts, ICE behavior, default media constraints, codec preferences, recovery thresholds, persisted device selections, and UX defaults like auto-mute-on-hidden. The single instance is owned by SignalWire and reached as client.preferences; applications never construct it directly.

Each preference is exposed as a paired getter/setter accessor, setting it applies immediately and affects subsequent operations (e.g. setting reconnectDelayMax changes the next reconnect attempt’s back-off). All time-based preferences take seconds, not milliseconds.

By default, preferences live only in memory for the current session. Calling enableSavePreferences with a Storage loads any persisted values on startup and writes back to storage on every subsequent change, survive page reload and tab restore without re-configuring on each session.

Constructors

Constructor

new ClientPreferences(): ClientPreferences

Accessors

autoMuteVideoOnHidden\ \ Whether to auto-mute video when the tab becomes hidden. checkConnectionOnVisible\ \ Whether to check peer connection health when the page becomes visible. connectionTimeout\ \ WebSocket connection timeout in seconds. defaultAudioConstraints\ \ Default audio track constraints applied when no explicit constraints are provided. defaultVideoConstraints\ \ Default video track constraints applied when video is enabled without explicit constraints. degradationBitrateThreshold\ \ Bitrate in kbps below which video is automatically disabled. degradationRecoveryThreshold\ \ Bitrate in kbps above which video is automatically re-enabled. deviceDebounceTime\ \ Debounce time for device change events, in seconds. devicePollingInterval\ \ Polling interval for device enumeration, in seconds. disableUdpIceServers\ \ Whether to filter out UDP-based ICE servers. enableAutoDegradation\ \ Whether automatic video degradation on low bandwidth is enabled. enableNetworkChangeDetection\ \ Whether browser network change detection (online/offline) is enabled. enableRelayFallback\ \ Whether relay-only escalation is enabled as a last-resort recovery tier. enableServerHangupInterception\ \ Whether server-sent media-timeout hangups are intercepted for recovery. iceCandidateTimeout\ \ Timeout for individual ICE candidate gathering, in seconds. iceDisconnectedGracePeriod\ \ Grace period before treating ICE ‘disconnected’ as failure, in seconds. iceGatheringTimeout\ \ Timeout for the entire ICE gathering phase, in seconds. iceRestartTimeout\ \ Timeout for a single ICE restart attempt in seconds. iceServers\ \ Custom ICE servers for TURN/STUN configuration. inputAudioConstraints\ \ Default audio input track constraints. inputVideoConstraints\ \ Default video input track constraints. keyframeBurstWindow\ \ Keyframe burst window duration in milliseconds. keyframeCooldown\ \ Cooldown period in ms after keyframe burst limit is reached. keyframeMaxBurst\ \ Maximum keyframe requests in a burst window. maxRecoveryAttempts\ \ Maximum recovery attempts before giving up. persistDeviceSelection\ \ Whether device selections are persisted to storage. preferredAudioCodecs\ \ Preferred audio codecs in priority order. preferredAudioInput\ \ Preferred audio input device for new calls. preferredAudioOutput\ \ Preferred audio output device for new calls. preferredVideoCodecs\ \ Preferred video codecs in priority order. preferredVideoInput\ \ Preferred video input device for new calls. receiveAudio\ \ Whether to receive remote audio by default. receiveVideo\ \ Whether to receive remote video by default. reconnectCallsTimeout\ \ Timeout for reconnecting to previously attached calls, in seconds. reconnectDelayMax\ \ Maximum reconnection backoff delay in seconds. reconnectDelayMin\ \ Minimum reconnection backoff delay in seconds. recoveryCooldown\ \ Cooldown period between recovery attempts in seconds. recoveryDebounceTime\ \ Recovery signal debounce window in seconds. refreshDevicesOnVisible\ \ Whether to re-enumerate devices when the page becomes visible. reinviteDebounceTime\ \ Minimum time in ms between re-INVITE attempts. reinviteMaxAttempts\ \ Maximum re-INVITE attempts per call. reinviteTimeout\ \ Timeout in ms for a single re-INVITE attempt. relayHost\ \ Custom relay host URL. Empty string uses the default. relayOnly\ \ Whether to force TURN relay-only ICE candidates. statsBaselineSamples\ \ Number of baseline samples for stats monitoring. statsHistorySize\ \ Number of seconds of metrics history to retain. statsJitterSpikeMultiplier\ \ Multiplier for jitter spike detection relative to baseline. statsNoPacketThreshold\ \ Duration in ms with no inbound packets before a critical issue is emitted. statsPacketLossThreshold\ \ Packet loss fraction threshold (0-1) for issue detection. statsPollingInterval\ \ Stats polling interval in milliseconds. statsRttSpikeMultiplier\ \ Multiplier for RTT spike detection relative to baseline. stereoAudio\ \ Whether stereo Opus is enabled globally. syncDevicesToActiveCalls\ \ Whether device changes are auto-applied to active calls. userVariables\ \ Custom user variables attached to calls.

Methods

enableSavePreferences\ \ Enables persistence of preferences to storage. Loads any previously saved preferences and syncs future changes.

checkConnectionOnVisible

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get checkConnectionOnVisible(): boolean
set checkConnectionOnVisible(value: boolean)

Whether to check peer connection health when the page becomes visible.

Parameters

value

booleanRequired

If true, checks connectivity when the tab or window becomes visible again.

Examples

// Read
console.log(client.preferences.checkConnectionOnVisible);

// Write
client.preferences.checkConnectionOnVisible = true;

connectionTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get connectionTimeout(): number
set connectionTimeout(seconds: number)

WebSocket connection timeout in seconds.

Parameters

seconds

numberRequired

Connection attempt timeout, in seconds.

Examples

// Read
console.log(client.preferences.connectionTimeout);

// Write
client.preferences.connectionTimeout = 10;

defaultAudioConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get defaultAudioConstraints(): MediaTrackConstraints | undefined
set defaultAudioConstraints(value: MediaTrackConstraints | undefined)

Default audio track constraints applied when no explicit constraints are provided.

Parameters

value

MediaTrackConstraints | undefined

Default constraints applied when capturing audio input. Pass undefined to clear. See MediaTrackConstraints.

Examples

// Read
console.log(client.preferences.defaultAudioConstraints);

// Write
client.preferences.defaultAudioConstraints = { echoCancellation: true };

degradationBitrateThreshold

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get degradationBitrateThreshold(): number
set degradationBitrateThreshold(value: number)

Bitrate in kbps below which video is automatically disabled.

Parameters

value

numberRequired

Outgoing bitrate (kbps) below which video is automatically disabled.

Examples

// Read
console.log(client.preferences.degradationBitrateThreshold);

// Write
client.preferences.degradationBitrateThreshold = 150;

degradationRecoveryThreshold

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get degradationRecoveryThreshold(): number
set degradationRecoveryThreshold(value: number)

Bitrate in kbps above which video is automatically re-enabled.

Parameters

value

numberRequired

Outgoing bitrate (kbps) above which video is automatically re-enabled.

Examples

// Read
console.log(client.preferences.degradationRecoveryThreshold);

// Write
client.preferences.degradationRecoveryThreshold = 300;

deviceDebounceTime

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get deviceDebounceTime(): number
set deviceDebounceTime(seconds): void

Debounce time for device change events, in seconds.

Parameters

seconds

number

Debounce window (in seconds) for media-device change events.

Examples

console.log(client.preferences.deviceDebounceTime);

devicePollingInterval

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get devicePollingInterval(): number
set devicePollingInterval(seconds): void

Polling interval for device enumeration, in seconds.

Parameters

seconds

number

Polling interval (in seconds) when device-change events are unavailable.

Examples

console.log(client.preferences.devicePollingInterval);

disableUdpIceServers

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get disableUdpIceServers(): boolean
set disableUdpIceServers(value): void

Whether to filter out UDP-based ICE servers.

Parameters

value

boolean

If true, ICE servers using UDP transport are excluded.

Examples

console.log(client.preferences.disableUdpIceServers);

enableAutoDegradation

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get enableAutoDegradation(): boolean
set enableAutoDegradation(value): void

Whether automatic video degradation on low bandwidth is enabled.

Parameters

value

boolean

If true, the SDK automatically degrades quality under poor network conditions.

Examples

console.log(client.preferences.enableAutoDegradation);

enableNetworkChangeDetection

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get enableNetworkChangeDetection(): boolean
set enableNetworkChangeDetection(value): void

Whether browser network change detection (online/offline) is enabled.

Parameters

value

boolean

If true, the SDK reacts to network-change events (e.g. Wi-Fi/cellular switch).

Examples

console.log(client.preferences.enableNetworkChangeDetection);

enableRelayFallback

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get enableRelayFallback(): boolean
set enableRelayFallback(value): void

Whether relay-only escalation is enabled as a last-resort recovery tier.

Parameters

value

boolean

If true, falls back to relay (TURN) when direct connections fail.

Examples

console.log(client.preferences.enableRelayFallback);

enableSavePreferences

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enableSavePreferences(storage): void

Enables persistence of preferences to storage. Loads any previously saved preferences and syncs future changes.

Parameters

storage

StorageManagerRequired

Storage manager used to persist user preferences across sessions.

Examples

client.preferences.enableSavePreferences(storage);

enableServerHangupInterception

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get enableServerHangupInterception(): boolean
set enableServerHangupInterception(value): void

Whether server-sent media-timeout hangups are intercepted for recovery.

Parameters

value

boolean

If true, server-initiated hangups are intercepted for recovery.

Examples

console.log(client.preferences.enableServerHangupInterception);

iceCandidateTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get iceCandidateTimeout(): number
set iceCandidateTimeout(seconds): void

Timeout for individual ICE candidate gathering, in seconds.

Parameters

seconds

number

Time (in seconds) to wait for new ICE candidates.

Examples

console.log(client.preferences.iceCandidateTimeout);

iceDisconnectedGracePeriod

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get iceDisconnectedGracePeriod(): number
set iceDisconnectedGracePeriod(seconds): void

Grace period before treating ICE ‘disconnected’ as failure, in seconds.

Parameters

seconds

number

Grace period (in seconds) before treating an ICE disconnect as fatal.

Examples

console.log(client.preferences.iceDisconnectedGracePeriod);

iceGatheringTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get iceGatheringTimeout(): number
set iceGatheringTimeout(seconds): void

Timeout for the entire ICE gathering phase, in seconds.

Parameters

seconds

number

Maximum time (in seconds) to gather ICE candidates.

Examples

console.log(client.preferences.iceGatheringTimeout);

iceRestartTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get iceRestartTimeout(): number
set iceRestartTimeout(seconds): void

Timeout for a single ICE restart attempt in seconds.

Parameters

seconds

number

Timeout (in seconds) for an ICE restart attempt.

Examples

console.log(client.preferences.iceRestartTimeout);

iceServers

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get iceServers(): RTCIceServer[] | undefined
set iceServers(value): void

Custom ICE servers for TURN/STUN configuration.

Parameters

value

RTCIceServer[] | undefined

Custom ICE server list. Pass undefined to use the SDK defaults. See RTCIceServer.

Examples

console.log(client.preferences.iceServers);

inputAudioConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputAudioConstraints(): MediaTrackConstraints | undefined
set inputAudioConstraints(value): void

Default audio input track constraints.

Parameters

value

MediaTrackConstraints | undefined

Constraints applied when acquiring audio input. Pass undefined to clear. See MediaTrackConstraints.

Examples

console.log(client.preferences.inputAudioConstraints);

keyframeBurstWindow

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get keyframeBurstWindow(): number
set keyframeBurstWindow(value): void

Keyframe burst window duration in milliseconds, the window over which video keyframe requests are counted before a keyframeCooldown applies. See Keyframe recovery for the full burst-with-cooldown mechanism. Default: 3000 (3 seconds).

Parameters

value

number

Keyframe burst window duration (ms).

Examples

console.log(client.preferences.keyframeBurstWindow);

keyframeCooldown

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get keyframeCooldown(): number
set keyframeCooldown(value): void

Cooldown period in milliseconds after the keyframe burst limit is reached, how long the SDK stops sending video keyframe requests once keyframeMaxBurst is hit within a keyframeBurstWindow. See Keyframe recovery for the full mechanism. Default: 10000 (10 seconds).

Parameters

value

number

Cooldown period (ms) after the keyframe burst limit is reached.

Examples

console.log(client.preferences.keyframeCooldown);

keyframeMaxBurst

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get keyframeMaxBurst(): number
set keyframeMaxBurst(value): void

Maximum video keyframe requests allowed within a single keyframeBurstWindow before a keyframeCooldown applies. See Keyframe recovery for the full burst-with-cooldown mechanism. Default: 3.

Parameters

value

number

Maximum number of keyframe requests allowed in one burst window.

Examples

console.log(client.preferences.keyframeMaxBurst);

maxRecoveryAttempts

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get maxRecoveryAttempts(): number
set maxRecoveryAttempts(value): void

Maximum recovery attempts before giving up.

Parameters

value

number

Maximum number of automatic recovery attempts before giving up.

Examples

console.log(client.preferences.maxRecoveryAttempts);

persistDeviceSelection

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get persistDeviceSelection(): boolean
set persistDeviceSelection(value): void

Whether device selections are persisted to storage.

Parameters

value

boolean

If true, persists the user’s device selection across sessions.

Examples

console.log(client.preferences.persistDeviceSelection);

preferredAudioCodecs

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get preferredAudioCodecs(): string[]
set preferredAudioCodecs(value): void

Preferred audio codecs in priority order.

Parameters

value

string[]

Ordered list of preferred audio codec names, e.g. ["opus", "PCMU"].

Examples

console.log(client.preferences.preferredAudioCodecs);

preferredAudioInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get preferredAudioInput(): MediaDeviceInfo | null
set preferredAudioInput(value): void

Preferred audio input device for new calls.

Parameters

value

MediaDeviceInfo | null

Preferred audio input device, or null to clear. See MediaDeviceInfo.

Examples

console.log(client.preferences.preferredAudioInput);

preferredAudioOutput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get preferredAudioOutput(): MediaDeviceInfo | null
set preferredAudioOutput(value): void

Preferred audio output device for new calls.

Parameters

value

MediaDeviceInfo | null

Preferred audio output device, or null to clear. See MediaDeviceInfo.

Examples

console.log(client.preferences.preferredAudioOutput);

receiveAudio

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get receiveAudio(): boolean
set receiveAudio(value): void

Whether to receive remote audio by default.

Parameters

value

boolean

If true, the local peer accepts incoming audio.

Examples

console.log(client.preferences.receiveAudio);

reconnectCallsTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reconnectCallsTimeout(): number
set reconnectCallsTimeout(seconds): void

Timeout for reconnecting to previously attached calls, in seconds.

Parameters

seconds

number

Maximum time (in seconds) to attempt call reconnection before failing.

Examples

console.log(client.preferences.reconnectCallsTimeout);

reconnectDelayMax

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reconnectDelayMax(): number
set reconnectDelayMax(seconds): void

Maximum reconnection backoff delay in seconds.

Parameters

seconds

number

Maximum delay (in seconds) between reconnection attempts.

Examples

console.log(client.preferences.reconnectDelayMax);

reconnectDelayMin

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reconnectDelayMin(): number
set reconnectDelayMin(seconds): void

Minimum reconnection backoff delay in seconds.

Parameters

seconds

number

Initial delay (in seconds) before the first reconnection attempt.

Examples

console.log(client.preferences.reconnectDelayMin);

recoveryCooldown

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get recoveryCooldown(): number
set recoveryCooldown(seconds): void

Cooldown period between recovery attempts in seconds.

Parameters

seconds

number

Cooldown (in seconds) between consecutive recovery attempts.

Examples

console.log(client.preferences.recoveryCooldown);

recoveryDebounceTime

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get recoveryDebounceTime(): number
set recoveryDebounceTime(seconds): void

Recovery signal debounce window in seconds.

Examples

console.log(client.preferences.recoveryDebounceTime);

refreshDevicesOnVisible

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get refreshDevicesOnVisible(): boolean
set refreshDevicesOnVisible(value): void

Whether to re-enumerate devices when the page becomes visible.

Examples

console.log(client.preferences.refreshDevicesOnVisible);

reinviteDebounceTime

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reinviteDebounceTime(): number
set reinviteDebounceTime(value): void

Minimum time in ms between re-INVITE attempts.

Examples

console.log(client.preferences.reinviteDebounceTime);

reinviteMaxAttempts

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reinviteMaxAttempts(): number
set reinviteMaxAttempts(value): void

Maximum re-INVITE attempts per call.

Examples

console.log(client.preferences.reinviteMaxAttempts);

reinviteTimeout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get reinviteTimeout(): number
set reinviteTimeout(value): void

Timeout in ms for a single re-INVITE attempt.

Examples

console.log(client.preferences.reinviteTimeout);

relayHost

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get relayHost(): string
set relayHost(value): void

Custom relay host URL. Empty string uses the default.

Examples

console.log(client.preferences.relayHost);

relayOnly

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get relayOnly(): boolean
set relayOnly(value): void

Whether to force TURN relay-only ICE candidates.

Examples

console.log(client.preferences.relayOnly);

statsBaselineSamples

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsBaselineSamples(): number
set statsBaselineSamples(value): void

Number of baseline samples for stats monitoring.

Examples

console.log(client.preferences.statsBaselineSamples);

statsHistorySize

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsHistorySize(): number
set statsHistorySize(value): void

Number of seconds of metrics history to retain.

Examples

console.log(client.preferences.statsHistorySize);

statsJitterSpikeMultiplier

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsJitterSpikeMultiplier(): number
set statsJitterSpikeMultiplier(value): void

Multiplier for jitter spike detection relative to baseline.

Examples

console.log(client.preferences.statsJitterSpikeMultiplier);

statsNoPacketThreshold

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsNoPacketThreshold(): number
set statsNoPacketThreshold(value): void

Duration in ms with no inbound packets before a critical issue is emitted.

Examples

console.log(client.preferences.statsNoPacketThreshold);

statsPacketLossThreshold

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsPacketLossThreshold(): number
set statsPacketLossThreshold(value): void

Packet loss fraction threshold (0-1) for issue detection.

Examples

console.log(client.preferences.statsPacketLossThreshold);

statsPollingInterval

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsPollingInterval(): number
set statsPollingInterval(value): void

Stats polling interval in milliseconds.

Examples

console.log(client.preferences.statsPollingInterval);

statsRttSpikeMultiplier

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get statsRttSpikeMultiplier(): number
set statsRttSpikeMultiplier(value): void

Multiplier for RTT spike detection relative to baseline.

Examples

console.log(client.preferences.statsRttSpikeMultiplier);

stereoAudio

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get stereoAudio(): boolean
set stereoAudio(value): void

Whether stereo Opus is enabled globally.

Examples

console.log(client.preferences.stereoAudio);

syncDevicesToActiveCalls

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get syncDevicesToActiveCalls(): boolean
set syncDevicesToActiveCalls(value): void

Whether device changes are auto-applied to active calls.

Examples

console.log(client.preferences.syncDevicesToActiveCalls);

userVariables

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get userVariables(): Record<string, unknown>
set userVariables(value): void

Custom user variables attached to calls.

Examples

console.log(client.preferences.userVariables);

EmbedTokenCredentialProvider

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Credential provider that exchanges an embed token for a SAT via the host’s token endpoint.

Implements

CredentialProvider

Constructors

Constructor

new EmbedTokenCredentialProvider(host, embedToken): EmbedTokenCredentialProvider

Parameters

host

stringRequired

Hostname or origin used for transport and REST calls.

embedToken

stringRequired

Embed token issued by the host application’s token endpoint.

Methods

authenticate\ \ Obtains the initial credentials. Called once during client initialization. refresh\ \ Obtains fresh credentials before the current ones expire. Optional.

authenticate

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

authenticate(): Promise<{ expiry_at: number; token: string; }>

Obtains the initial credentials. Called once during client initialization.

Implementor responsibilities:

Resolve with a valid SDKCredential on success.
Reject (throw) on failure, this will cause client initialization to fail.
When context.fingerprint is provided, forward it to the server-side token endpoint with scope: "sat:refresh" to enable automatic token refresh.

SDK behavior:

Awaits this method before establishing the WebSocket connection.
On rejection, propagates the error to the caller of SignalWire().

Returns

Promise<{ expiry_at: number; token: string; }>

Examples

import { EmbedTokenCredentialProvider } from '@signalwire/js';

const provider = new EmbedTokenCredentialProvider({
  token: 'YOUR_EMBED_TOKEN',
  host: 'your-space.signalwire.com',
});

// Called by the SDK during `new SignalWire(provider)`, typically not
// invoked directly by application code.
const credential = await provider.authenticate({ /* AuthenticateContext */ });

refresh

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

refresh(): Promise<{ expiry_at: number; token: string; }>

Obtains fresh credentials before the current ones expire. Optional.

Implementor responsibilities:

Resolve with a new SDKCredential containing an updated token (or authorizationState) and expiry_at.
Reject (throw) if refresh is not possible, the SDK will stop the refresh schedule.

SDK behavior:

Only called when expiry_at was set on the previous credential.
Scheduled automatically before expiry; implementors do not need to manage timing.
On rejection, the refresh schedule stops and the session continues with the current credentials until they expire.
When not provided and the SAT includes a sat:refresh scope, the SDK automatically refreshes via Client Bound SAT (DPoP) without developer intervention.
When not provided and no refresh scope is present, the SDK uses the initial credentials for the entire session lifetime.

Returns

Promise<{ expiry_at: number; token: string; }>

Examples

// Scheduled automatically by the SDK before `expiry_at`. To trigger manually
// in tests:
const fresh = await provider.refresh();
console.log('new token expiry:', fresh.expiry_at);

StaticCredentialProvider

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Credential provider that returns a fixed set of credentials.

Use when the token is already available (e.g. from a backend endpoint).

Examples

const provider = new StaticCredentialProvider({ token: 'my-sat-token' });
const client = new SignalWire(provider);

Implements

CredentialProvider

Constructors

Constructor

new StaticCredentialProvider(credentials): StaticCredentialProvider

Parameters

credentials

SDKCredentialRequired

Credentials used to authenticate the SDK session. See SDKCredential.

Methods

authenticate\ \ Returns the static credentials.

authenticate

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

authenticate(): Promise<SDKCredential>

Returns the static credentials.

Returns

Promise<SDKCredential>

Examples

import { StaticCredentialProvider } from '@signalwire/js';

const provider = new StaticCredentialProvider({ token: 'YOUR_SAT', expiry_at: 0 });
const credential = await provider.authenticate(); // returns the same static credential

CallCreateError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised by SignalWire.dial and the inbound-call flow when a call cannot be brought to the connecting state, typical causes are signaling-layer failure, authentication rejection, or the server refusing the call invite. The direction property distinguishes whether the failure occurred while placing an outbound call or accepting an inbound one.

Extends

Error

Constructors

Constructor

new CallCreateError(message, error?, direction?, options?): CallCreateError

Parameters

message

stringRequired

Human-readable error message.

error

unknown

Underlying error that caused the call creation to fail, if any.

direction

'inbound' | 'outbound'

Direction of the call that failed to create.

options

ErrorOptions

Standard ErrorOptions (e.g. cause).

Properties

direction

'inbound' | 'outbound'Required

Direction of the call that failed to create.

error

unknownRequired

Underlying error that caused the call creation to fail, if any.

message

stringRequired

Human-readable error message.

Examples

import { CallCreateError } from '@signalwire/js';

try {
  const call = await client.dial('/public/my-room', { audio: true, video: true });
} catch (err) {
  if (err instanceof CallCreateError) {
    console.error(`Failed to create ${err.direction} call:`, err.message, err.error);
  }
}

CollectionFetchError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when an underlying REST fetch backing a paginated collection, for example Address.history or Address.textMessage, fails. The error carries the operation name and the underlying network/HTTP error so callers can decide whether to retry, surface a UI message, or fall back to a cached view.

Extends

Error

Constructors

Constructor

new CollectionFetchError(operation, originalError): CollectionFetchError

Parameters

operation

stringRequired

Name of the collection-fetch operation that failed.

originalError

unknownRequired

Underlying error returned by the fetch.

Properties

operation

stringRequired

Name of the collection-fetch operation that failed.

originalError

unknownRequired

Underlying error returned by the fetch.

Examples

import { CollectionFetchError } from '@signalwire/js';

address.history$.subscribe({
  next: (collection) => render(collection),
  error: (err) => {
    if (err instanceof CollectionFetchError) {
      console.error(`history fetch (${err.operation}) failed:`, err.originalError);
    }
  },
});

DeviceTokenError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when the SDK cannot obtain or validate a device token from the auth backend. Surfaces both during the initial token exchange and on subsequent re-issue attempts. When this fires the session is not authenticated; check the underlying error for HTTP-status detail and decide whether to prompt the user to re-authenticate or retry.

Extends

Error

Constructors

Constructor

new DeviceTokenError(message, originalError?): DeviceTokenError

Parameters

message

stringRequired

Human-readable error message.

originalError

unknown

Underlying error raised during device-token issuance or validation.

Properties

originalError

unknown

Underlying error raised during device-token issuance or validation.

Examples

import { DeviceTokenError } from '@signalwire/js';

client.errors$.subscribe((err) => {
  if (err instanceof DeviceTokenError) {
    console.error('device token failure:', err.message, err.originalError);
    redirectToLogin();
  }
});

DPoPInitError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised during client construction when DPoP (Demonstrating Proof-of-Possession) key initialization fails, typically because the browser does not expose a usable SubtleCrypto (insecure origin, very old browser) or persistent storage is unavailable for the key material. The error is fatal: a SignalWire instance that cannot initialize DPoP cannot authenticate.

Extends

Error

Constructors

Constructor

new DPoPInitError(originalError, message?): DPoPInitError

Parameters

originalError

unknownRequired

Underlying error raised during DPoP key initialization.

message

string

Human-readable error message.

Properties

originalError

unknownRequired

Underlying error raised during DPoP key initialization.

Examples

import { DPoPInitError } from '@signalwire/js';

try {
  const client = new SignalWire(credentialProvider);
  await client.connect();
} catch (err) {
  if (err instanceof DPoPInitError) {
    // Likely cause: insecure origin or unsupported browser.
    showFallbackUI('Your browser does not support secure authentication.');
  }
}

InvalidCredentialsError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when the auth backend rejects the credentials returned by the configured CredentialProvider, for example, an expired SAT, a revoked embed token, or a payload that fails schema validation. The reason property carries the server-reported cause when available.

Extends

Error

Constructors

Constructor

new InvalidCredentialsError(reason?, options?): InvalidCredentialsError

Parameters

reason

string

Reason the auth backend rejected the credentials.

options

ErrorOptions

Standard ErrorOptions (e.g. cause).

Properties

reason

stringRequired

Reason the auth backend rejected the credentials.

Examples

import { InvalidCredentialsError } from '@signalwire/js';

try {
  await client.connect();
} catch (err) {
  if (err instanceof InvalidCredentialsError) {
    console.error('auth rejected:', err.reason);
    await refreshCredentialProvider();
  }
}

MediaTrackError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when a peer-connection track operation fails, most commonly when the SDK tries to addTrack, replaceTrack, or remove a track during device switching, muting, or screen-share handoff. The operation and kind properties locate the failure; originalError carries the underlying DOMException from the WebRTC stack.

Extends

Error

Constructors

Constructor

new MediaTrackError(operation, kind, originalError): MediaTrackError

Parameters

operation

stringRequired

Track operation that failed (e.g. addTrack, replaceTrack).

kind

stringRequired

Kind of media track involved (audio or video).

originalError

unknownRequired

Underlying error raised by the WebRTC stack.

Properties

kind

stringRequired

Kind of media track involved (audio or video).

operation

stringRequired

Track operation that failed (e.g. addTrack, replaceTrack).

originalError

unknownRequired

Underlying error raised by the WebRTC stack.

Examples

import { MediaTrackError } from '@signalwire/js';

call.errors$.subscribe((err) => {
  if (err instanceof MediaTrackError) {
    console.error(`media track ${err.kind} ${err.operation} failed:`, err.originalError);
  }
});

MessageParseError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when an inbound signaling message cannot be decoded, typically a malformed JSON payload or one that fails schema validation. The SDK skips the offending message and continues; persistent occurrences usually indicate a server/client version skew.

Extends

Error

Constructors

Constructor

new MessageParseError(originalError): MessageParseError

Parameters

originalError

unknownRequired

Underlying parse error (typically a JSON or schema error).

Properties

originalError

unknownRequired

Underlying parse error (typically a JSON or schema error).

Examples

import { MessageParseError } from '@signalwire/js';

client.errors$.subscribe((err) => {
  if (err instanceof MessageParseError) {
    console.warn('skipped unparsable message:', err.originalError);
  }
});

OverconstrainedFallbackError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised by the device controller when getUserMedia rejects with OverconstrainedError and the SDK’s built-in fallback ladder, progressively relaxing the requested constraints, has been exhausted without finding a working set. The deviceKind property indicates whether the failure was on audio or video capture.

Extends

Error

Constructors

Constructor

new OverconstrainedFallbackError(deviceKind, originalError?): OverconstrainedFallbackError

Parameters

deviceKind

stringRequired

Device kind whose constraints could not be satisfied (audio or video).

originalError

unknown

Final OverconstrainedError returned after all fallback levels were exhausted.

Properties

deviceKind

stringRequired

Device kind whose constraints could not be satisfied (audio or video).

originalError

unknown

Final OverconstrainedError returned after all fallback levels were exhausted.

Examples

import { OverconstrainedFallbackError } from '@signalwire/js';

try {
  await client.enableVideoInput();
} catch (err) {
  if (err instanceof OverconstrainedFallbackError) {
    console.error(`no working ${err.deviceKind} device available:`, err.originalError);
    showPickerWithoutConstraints();
  }
}

PreflightError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised by SignalWire.preflight when the connectivity test fails at one of its phases. Inspect phase to discriminate (signaling, media, connectivity), failure at the signaling phase usually means the user’s network blocks the transport; failure at the media phase usually means device-permission or codec issues.

Extends

Error

Constructors

Constructor

new PreflightError(phase, originalError?): PreflightError

Parameters

phase

stringRequired

Preflight phase where the failure occurred (e.g. signaling, media, connectivity).

originalError

unknown

Underlying error raised during preflight.

Properties

originalError

unknown

Underlying error raised during preflight.

phase

stringRequired

Preflight phase where the failure occurred (e.g. signaling, media, connectivity).

Examples

import { PreflightError } from '@signalwire/js';

try {
  const result = await client.preflight('/preflight-endpoint');
} catch (err) {
  if (err instanceof PreflightError) {
    console.error(`preflight failed at ${err.phase}:`, err.originalError);
  }
}

RecoveryError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when the SDK’s automatic call-recovery flow fails, for example, after a transient signaling disconnect that exceeds maxRecoveryAttempts. The action and attempt properties identify which recovery step gave up. When this fires the call has transitioned to failed; clean up UI and notify the user.

Extends

Error

Constructors

Constructor

new RecoveryError(action, attempt, originalError?): RecoveryError

Parameters

action

stringRequired

Recovery action being attempted when the error was raised.

attempt

numberRequired

Recovery attempt number (1-based) at the time of failure.

originalError

unknown

Underlying error that caused the recovery attempt to fail.

Properties

action

stringRequired

Recovery action being attempted when the error was raised.

attempt

numberRequired

Recovery attempt number (1-based) at the time of failure.

originalError

unknown

Underlying error that caused the recovery attempt to fail.

Examples

import { RecoveryError } from '@signalwire/js';

call.errors$.subscribe((err) => {
  if (err instanceof RecoveryError) {
    console.error(`recovery action ${err.action} failed on attempt ${err.attempt}`);
    teardownCallUI();
  }
});

TokenRefreshError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when the SDK attempts to refresh an expiring access token (SAT) and the refresh endpoint returns an error or unparsable response. After this fires, the session continues using the current token until expiry; once that lapses the connection will be torn down. Catching this is your cue to obtain a fresh token out-of-band.

Extends

Error

Constructors

Constructor

new TokenRefreshError(message, originalError?): TokenRefreshError

Parameters

message

stringRequired

Human-readable error message.

originalError

unknown

Underlying error returned by the token-refresh endpoint.

Returns

TokenRefreshError

Properties

originalError

unknown

Underlying error returned by the token-refresh endpoint.

Examples

import { TokenRefreshError } from '@signalwire/js';

client.errors$.subscribe((err) => {
  if (err instanceof TokenRefreshError) {
    console.warn('token refresh failed:', err.message, err.originalError);
    void rotateCredentialProvider();
  }
});

UnexpectedError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Catch-all wrapper used when the SDK encounters a condition that doesn’t map to one of the typed error classes. The at property records where the wrap occurred and options.cause (standard ErrorOptions) carries the original throwable. Treat this as a bug signal, any occurrence merits filing an issue with the at value and the underlying cause attached.

Extends

Error

Constructors

Constructor

new UnexpectedError(at?, options?): UnexpectedError

Parameters

at

string

Location where the error was raised, for diagnostics.

options

ErrorOptions

Standard ErrorOptions (e.g. cause).

Returns

UnexpectedError

Properties

at

string

Location where the error was raised, for diagnostics.

Examples

import { UnexpectedError } from '@signalwire/js';

client.errors$.subscribe((err) => {
  if (err instanceof UnexpectedError) {
    console.error(`unexpected error at ${err.at}:`, err.cause);
    reportToTelemetry(err);
  }
});

VertoPongError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Raised when the Verto ping/pong heartbeat misses a response window, typically a symptom of a stalled WebSocket or a network change that hasn’t yet been detected. The SDK reacts by disconnecting and starting the reconnection/recovery flow; this error is informational and does not by itself terminate any call.

Extends

Error

Constructors

Constructor

new VertoPongError(originalError): VertoPongError

Parameters

originalError

unknownRequired

Underlying error raised by the Verto ping/pong handler.

Returns

VertoPongError

Properties

originalError

unknownRequired

Underlying error raised by the Verto ping/pong handler.

Examples

import { VertoPongError } from '@signalwire/js';

client.errors$.subscribe((err) => {
  if (err instanceof VertoPongError) {
    console.warn('heartbeat missed, reconnecting:', err.originalError);
  }
});

embeddableCall

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

embeddableCall(options): Promise<Call>

Creates a call using an embed token for simple, embeddable integrations.

import { embeddableCall } from '@signalwire/js';

const call = await embeddableCall({
  to: '/public/conference',
  embedToken: 'YOUR_EMBED_TOKEN',
  host: 'your-space.signalwire.com',
});

getLogger

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getLogger(): InternalSDKLogger

Returns the SDK’s current logger. Useful when a host application wants to attach its own transport (e.g. a remote log sink) without replacing the entire logger via setLogger.

Returns

The active logger instance (the built-in one, unless setLogger has been called).

Examples

import { getLogger } from '@signalwire/js';

const logger = getLogger();
logger.info('app ready');

isSelfParticipant

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

isSelfParticipant(participant): participant is SelfParticipant

Type guard that checks if a participant is the local SelfParticipant.

Parameters

participant

ParticipantRequired

Participant to test.

Returns

participant is SelfParticipant

Examples

Narrow at the type level

import { isSelfParticipant } from '@signalwire/js';

call.participants$.subscribe((participants) => {
  for (const p of participants) {
    if (isSelfParticipant(p)) {
      // p is typed as SelfParticipant here, local-only methods are available.
      p.startScreenShare?.();
    }
  }
});

setDebugOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setDebugOptions(options): void

Configure debug options (e.g., { logWsTraffic: true }).

Parameters

options

DebugOptions | null

Debug options to apply, or null to clear all overrides. See DebugOptions.

Returns

void

Examples

Enable WebSocket-traffic logging

import { setDebugOptions } from '@signalwire/js';

setDebugOptions({ logWsTraffic: true });

Clear all debug overrides

setDebugOptions(null);

setLogLevel

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLogLevel(level): void

Set the log level for the built-in logger. Has no effect when a custom logger is set via setLogger().

Parameters

level

LogLevelRequired

New minimum log level for the built-in logger. See LogLevel.

Returns

void

Examples

Switch to verbose logging in development

import { setLogLevel } from '@signalwire/js';

if (import.meta.env.DEV) {
  setLogLevel('debug');
}

setLogger

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLogger(logger): void

Replace the built-in logger with a custom implementation. Pass null to restore defaults.

Parameters

logger

SDKLogger | null

Custom logger implementation, or null to restore the default. See SDKLogger.

Returns

void

Examples

Plug in a custom logger

import { setLogger } from '@signalwire/js';

setLogger({
  trace: (...args) => myTelemetry.send('trace', args),
  debug: (...args) => myTelemetry.send('debug', args),
  info:  (...args) => myTelemetry.send('info', args),
  warn:  (...args) => myTelemetry.send('warn', args),
  error: (...args) => myTelemetry.send('error', args),
});

Restore the default logger

setLogger(null);

AddressHistory<TAddress>

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Address history entry from conversation messages Contains a reference to the sender address as an observable

Remarks

Uses a generic type parameter to maintain type safety while avoiding circular dependencies. The Address class provides the concrete type.

Type Parameters

TAddress

never

The Address type, provided by the implementation

Properties

ended

number

Wall-clock timestamp (ms since epoch) when this history entry ended.

fromAddress$

Observable<TAddress> | undefined

Observable of the originating address for this history entry, if known.

id

stringRequired

Unique ID of this history entry.

kind

stringRequired

Kind of history entry (e.g. call, message).

started

numberRequired

Wall-clock timestamp (ms since epoch) when this history entry started.

status

stringRequired

Final status of the interaction (e.g. completed, missed).

AudioConstraintsEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Event emitted when audio constraints change on a call.

Properties

constraints

MediaTrackConstraintsRequired

The new constraints applied. See MediaTrackConstraints.

method

applyConstraints | trackReplacementRequired

How the constraints were applied.

timestamp

numberRequired

Timestamp when the event occurred (epoch ms).

AuthenticateContext

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Context provided by the SDK when calling CredentialProvider.authenticate.

Contains optional parameters the SDK generates internally (e.g., DPoP fingerprint) that the implementor can forward to their server-side token endpoint.

Properties

fingerprint

string

JWK Thumbprint (RFC 7638) of the SDK’s ephemeral DPoP key pair. When present, the implementor should forward this value as the fingerprint parameter to the server-side SAT issuance endpoint alongside scope: "sat:refresh". This enables the server to bind the SAT to the SDK’s key pair, allowing automatic Client Bound SAT refresh without developer intervention. When absent (e.g., Web Crypto API not available), the implementor should proceed without DPoP binding.

Call

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Public interface for an active WebRTC call.

Provides access to media streams, participants, layout, signaling events, and control actions (hangup, mute, transfer, etc.).

Extends

CallState

Properties

address

CallAddress

Address associated with the remote party of the call. See CallAddress.

address$

Observable<CallAddress | undefined>

Observable of the address associated with this call. See CallAddress.

bandwidthConstrained$

Observable<boolean>

Observable that emits true while the call is bandwidth-constrained.

capabilities

Capability[]

Set of capabilities currently granted to the local participant on this call. See Capability.

capabilities$

Observable<Capability[]>

Observable of the local participant’s current capability set on this call. See Capability.

direction

CallDirection

Whether this call is inbound or outbound. See CallDirection.

errors$

Observable<CallError>

Observable stream of errors raised on this call. See CallError.

from

string

URI of the calling party.

fromName

string

Display name of the calling party.

isNetworkHealthy

boolean

Whether the connection currently meets quality thresholds.

isNetworkHealthy$

Observable<boolean>

Observable of the call’s current network-health state.

layout

string

Name of the currently active video layout.

layout$

Observable<string>

Observable of the currently active layout name.

layoutLayers

LayoutLayer[]

Position and state of each layer in the active layout. See LayoutLayer.

layoutLayers$

Observable<LayoutLayer[]>

Observable of the active layout’s layer positions. See LayoutLayer.

layouts

string[]

List of layout names available on this call.

layouts$

Observable<string[]>

Observable of the list of available layout names.

localStream

MediaStream | null

Sync getter, returns null before the stream is created. See MediaStream.

localStream$

Observable<MediaStream>

Observable that emits only non-null MediaStreams (waits until the stream exists). See MediaStream.

mediaDirections

MediaDirections

Send/receive direction for each media track. See MediaDirections.

mediaDirections$

Observable<MediaDirections>

Observable of the per-track media direction state. See MediaDirections.

mediaParamsUpdated$

Observable<MediaParamsEvent>

Observable that emits when media parameters are renegotiated. See MediaParamsEvent.

networkIssues

CallNetworkIssue[]

Recent network issues detected during the call. See CallNetworkIssue.

networkIssues$

Observable<CallNetworkIssue[]>

Observable stream of detected network issues. See CallNetworkIssue.

networkMetrics

CallNetworkMetrics[]

Recent network-metric samples for the call. See CallNetworkMetrics.

networkMetrics$

Observable<CallNetworkMetrics[]>

Observable of periodic network-metric samples. See CallNetworkMetrics.

qualityLevel$

Observable<QualityLevel>

Observable of the categorical call-quality level. See QualityLevel.

qualityScore$

Observable<number>

Observable of the numeric call-quality score (0-5).

recoveryEvent$

Observable<RecoveryEvent>

Observable stream of call-recovery events. See RecoveryEvent.

recoveryState$

Observable<RecoveryState>

Observable of the current recovery state. See RecoveryState.

remoteStream

MediaStream | null

Remote MediaStream for the call, or null if not yet available. See MediaStream.

remoteStream$

Observable<MediaStream>

Observable that emits only non-null MediaStreams (waits until the stream exists). See MediaStream.

rtcPeerConnection

RTCPeerConnection | undefined

Underlying RTCPeerConnection, or undefined if not yet established.

self

CallSelfParticipant | null

Local participant on the call, or null before join. See CallSelfParticipant.

self$

Observable<CallSelfParticipant | null>

Observable of the local participant, or null before join. See CallSelfParticipant.

signalingEvent$

Observable<Record<string, unknown>>

Observable stream of raw signaling events.

to

string

URI of the called party.

toName

string

Display name of the called party.

userVariables

Record<string, unknown>

Map of arbitrary user-defined variables associated with the call.

userVariables$

Observable<Record<string, unknown>>

answer()

answer(options?): void

Parameters

options

MediaOptions

Per-call options for this operation (media constraints, RPC timeouts, or transfer target depending on context). See MediaOptions.

Returns

void

execute()

execute<T>(request, options?): Promise<T>

Type Parameters

Type Parameter	Default type
`T` extends `JSONRPCResponse`	`JSONRPCResponse`

Parameters

request

JSONRPCRequestRequired

Outgoing JSON-RPC request to send. See JSONRPCRequest.

options

PendingRPCOptions

Per-call options for this operation (media constraints, RPC timeouts, or transfer target depending on context). See PendingRPCOptions.

Returns

Promise<T>

executeMethod()

executeMethod<T>(target, method, args): Promise<T>

Type Parameters

Type Parameter	Default type
`T` extends `JSONRPCResponse`	`JSONRPCResponse`

Parameters

target

stringRequired

Target identifier (member ID or destination URI) for the operation.

method

stringRequired

RPC method name to execute on the server.

args

Record<string, unknown>Required

sendDigits(digits): Promise<void>

Parameters

digits

stringRequired

DTMF digit string to send.

Returns

Promise<void>

setLayout()

setLayout(layout, positions): Promise<void>

Parameters

layout

stringRequired

Name of the currently active video layout.

positions

Record<string, VideoPosition>Required

Map of member IDs to layout positions. See VideoPosition.

Returns

Promise<void>

setMeta()

setMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Promise<void>

subscribe(eventType): Observable<Record<string, unknown>>

Parameters

eventType

stringRequired

transfer(options): Promise<void>

Parameters

options

TransferOptionsRequired

Per-call options for this operation (media constraints, RPC timeouts, or transfer target depending on context). See TransferOptions.

Returns

Promise<void>

updateMeta()

updateMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag associated with the call or member.

Returns

Promise<void>

Inherited from

CallState. updateMeta

CallAddress

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Minimal address interface for call context Avoids circular dependency with full Address class

Properties

displayName

string

Human-readable display name for the address.

id

stringRequired

Server-assigned ID of the address.

textMessages$

Observable<CallTextMessageCollection | undefined>Required

Observable of the text-message collection for this address.

type

string

Kind of address (e.g. sip, room, subscriber).

Methods

sendText()

sendText(text): Promise<void>

Parameters

text

stringRequired

Address as a URI or plain text.

Returns

Promise<void>

CallCapabilitiesState

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

numberRequired

Number of recovery attempts made during the call.

status

stringRequired

Final call status.

CallError

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Structured error emitted on call.errors$.

Provides actionable metadata so consumers can react without resorting to instanceof checks on raw Error objects.

Properties

callId

stringRequired

ID of the call that produced this error.

error

ErrorRequired

The underlying error.

fatal

booleanRequired

Whether the error terminates the call. When true, the call will automatically transition to 'failed' and be destroyed, no further action is needed from the consumer.

kind

CallErrorKindRequired

Semantic category of the error. See CallErrorKind.

CallNetworkIssue

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

A single network issue detected by the WebRTC stats monitor on an active call. Issues are emitted on call.networkIssues$; use them to drive UI warnings or quality-degradation flows.

Properties

severity

warning | criticalRequired

Severity of the issue. warning indicates degradation; critical indicates the call may not be usable.

threshold

number

Threshold value (in the metric’s unit) that was crossed to trigger this issue.

timestamp

numberRequired

Wall-clock timestamp (ms since epoch) when the issue was detected.

type

Kind of network issue detected.

value

number

Observed value of the metric that triggered the issue.

CallNetworkMetrics

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

string

Display name of the callee.

userVariables

Record<string, unknown>

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Base participant interface for call participants Defines the full public contract for participant objects exposed by Call

Extended by

CallSelfParticipant

Observable of whether this participant is currently visible in the layout.

Methods

end()

end(): Promise<void>

Returns

Promise<void>

mute()

mute(): Promise<void>

Returns

Promise<void>

muteVideo()

muteVideo(): Promise<void>

Returns

Promise<void>

remove()

remove(): Promise<void>

Returns

Promise<void>

setAudioInputSensitivity()

setAudioInputSensitivity(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

setAudioInputVolume()

setAudioInputVolume(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

setAudioOutputVolume()

setAudioOutputVolume(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

setMeta()

setMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for this participant, if any.

Returns

Promise<void>

setPosition()

setPosition(value): Promise<void>

Parameters

value

VideoPositionRequired

updateMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for this participant, if any.

Returns

Promise<void>

CallSelfParticipant

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Self participant interface with control methods Extends CallParticipant with methods for controlling the local participant

Extends

CallParticipant

Properties

screenShareStatus

ScreenShareStatusRequired

Current screen-share status for this participant. See ScreenShareStatus.

screenShareStatus$

Observable<ScreenShareStatus>Required

Observable of current screen-share status for this participant. See ScreenShareStatus.

studioAudio

booleanRequired

Whether studio-audio processing is enabled for this participant.

studioAudio$

Observable<boolean>Required

Observable<boolean | undefined>Required

Observable of whether this participant is currently visible in the layout.

Methods

addAdditionalDevice()

addAdditionalDevice(options): Promise<void>

Parameters

options

MediaOptionsRequired

Per-operation options (media options, device-select options, or capture override depending on context). See MediaOptions.

Returns

Promise<void>

addAudioInputDevice()

addAudioInputDevice(options?): Promise<void>

Parameters

options

{ constraints?: MediaTrackConstraints; stream?: MediaStream; }

Per-operation options (media options, device-select options, or capture override depending on context). See MediaTrackConstraints and MediaStream.

Returns

Promise<void>

addInputDevices()

addInputDevices(options?): Promise<void>

Parameters

options

MediaOptions

Per-operation options (media options, device-select options, or capture override depending on context). See MediaOptions.

Returns

Promise<void>

addVideoInputDevice()

addVideoInputDevice(options?): Promise<void>

Parameters

options

{ constraints?: MediaTrackConstraints; stream?: MediaStream; }

Per-operation options (media options, device-select options, or capture override depending on context). See MediaTrackConstraints and MediaStream.

Returns

Promise<void>

disableStudioAudio()

disableStudioAudio(): Promise<void>

Returns

Promise<void>

enableStudioAudio()

enableStudioAudio(): Promise<void>

Returns

Promise<void>

end()

end(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. end

mute()

mute(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. mute

muteVideo()

muteVideo(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. muteVideo

remove()

remove(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. remove

removeAdditionalDevice()

removeAdditionalDevice(id): Promise<void>

Parameters

id

stringRequired

Unique participant ID, assigned by the media server.

Returns

Promise<void>

selectAudioInputDevice()

selectAudioInputDevice(device, options?): void

Parameters

device

MediaDeviceInfoRequired

Media device to use for this participant. See MediaDeviceInfo.

options

SelectDeviceOptions

Per-operation options (media options, device-select options, or capture override depending on context). See SelectDeviceOptions.

Returns

void

selectAudioOutputDevice()

selectAudioOutputDevice(device, options?): void

Parameters

device

MediaDeviceInfoRequired

Media device to use for this participant. See MediaDeviceInfo.

options

SelectDeviceOptions

Per-operation options (media options, device-select options, or capture override depending on context). See SelectDeviceOptions.

Returns

void

selectVideoInputDevice()

selectVideoInputDevice(device, options?): void

Parameters

device

MediaDeviceInfoRequired

Media device to use for this participant. See MediaDeviceInfo.

options

SelectDeviceOptions

Per-operation options (media options, device-select options, or capture override depending on context). See SelectDeviceOptions.

Returns

void

setAudioInputDeviceConstraints()

setAudioInputDeviceConstraints(constraints): Promise<void>

Parameters

constraints

MediaTrackConstraintsRequired

Media-track constraints applied to this participant’s input. See MediaTrackConstraints.

Returns

Promise<void>

setAudioInputSensitivity()

setAudioInputSensitivity(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

Inherited from

CallParticipant. setAudioInputSensitivity

setAudioInputVolume()

setAudioInputVolume(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

Inherited from

CallParticipant. setAudioInputVolume

setAudioOutputVolume()

setAudioOutputVolume(value): Promise<void>

Parameters

value

numberRequired

New value for the property being set.

Returns

Promise<void>

Inherited from

CallParticipant. setAudioOutputVolume

setInputDevicesConstraints()

setInputDevicesConstraints(constraints): Promise<void>

Parameters

constraints

{ audio: MediaTrackConstraints; video: MediaTrackConstraints; }Required

Media-track constraints applied to this participant’s input. See MediaTrackConstraints.

Returns

Promise<void>

setMeta()

setMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for the local participant, if any.

Returns

Promise<void>

Inherited from

CallParticipant. setMeta

setPosition()

setPosition(value): Promise<void>

Parameters

value

VideoPositionRequired

New value for the property being set. See VideoPosition.

Returns

Promise<void>

Inherited from

CallParticipant. setPosition

setVideoInputDeviceConstraints()

setVideoInputDeviceConstraints(constraints): Promise<void>

Parameters

constraints

MediaTrackConstraintsRequired

Media-track constraints applied to this participant’s input. See MediaTrackConstraints.

Returns

Promise<void>

startScreenShare()

startScreenShare(): Promise<void>

Returns

Promise<void>

stopScreenShare()

stopScreenShare(): Promise<void>

Returns

Promise<void>

toggleAudioInputAutoGain()

toggleAudioInputAutoGain(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleAudioInputAutoGain

toggleDeaf()

toggleDeaf(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleDeaf

toggleEchoCancellation()

toggleEchoCancellation(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleEchoCancellation

toggleHandraise()

toggleHandraise(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleHandraise

toggleLowbitrate()

toggleLowbitrate(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleLowbitrate

toggleMute()

toggleMute(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleMute

toggleMuteVideo()

toggleMuteVideo(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleMuteVideo

toggleNoiseSuppression()

toggleNoiseSuppression(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. toggleNoiseSuppression

unmute()

unmute(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. unmute

unmuteVideo()

unmuteVideo(): Promise<void>

Returns

Promise<void>

Inherited from

CallParticipant. unmuteVideo

updateMeta()

updateMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for the local participant, if any.

Returns

Promise<void>

Inherited from

CallParticipant. updateMeta

CallState

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Observable state of a call (status, recording, participants, etc.).

Extended by

Call

Observable of the current streaming state.

Methods

setMeta()

setMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for the call state.

Returns

Promise<void>

updateMeta()

updateMeta(meta): Promise<void>

Parameters

meta

Record<string, unknown>Required

Arbitrary metadata bag for the call state.

Returns

Promise<void>

ConstraintFallbackEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Event emitted when getUserMedia falls back to looser constraints.

Properties

actualDevice

MediaDeviceInfo | nullRequired

The device that the browser actually provided. See MediaDeviceInfo.

fallbackLevel

exact | preferred | defaultRequired

The constraint level that succeeded.

kind

audioinput | videoinputRequired

The kind of input device.

requestedDevice

MediaDeviceInfo | nullRequired

The device that was originally requested. See MediaDeviceInfo.

CredentialNoRefreshHandlerWarning

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Emitted when a credential has an expiry_at but the provider supplies no refresh() handler. The session will terminate at expiry with no fallback.

Implementors who want long-lived sessions must provide a refresh() handler or mint tokens with the sat:refresh scope (Client Bound SAT path). Subscribe via client.warnings$.

Properties

code

"credential_no_refresh_handler"Required

Discriminant identifying this warning.

source

"CredentialProvider"Required

The SDK subsystem that emitted the warning.

message

stringRequired

Human-readable description of the warning.

expiresAt

numberRequired

Token expiry timestamp (epoch milliseconds).

CredentialProvider

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Provides authentication credentials to the SDK.

Implementors are responsible for:

Obtaining credentials (e.g. via API calls, user login flows, or third-party auth services).
Returning a valid SDKCredential with either a token or authorizationState.
Setting expiry_at when the credential has a known expiration so the SDK can schedule refresh.
Handling errors and never leaking sensitive data through error messages.

The SDK owns the credential lifecycle: it calls authenticate once during initialization and, if refresh is provided and expiry_at is set, schedules automatic refresh before expiry.

Refresh precedence

The SDK selects exactly one refresh mechanism per session, evaluated at connect time (and re-evaluated on reconnect):

`refresh` provided	SAT carries `sat:refresh` scope	Active mechanism
yes	yes	Client Bound SAT (DPoP, internal)
yes	no	Developer-provided `refresh()`
no	yes	Client Bound SAT (DPoP, internal)
no	no	None, session ends at `expiry_at`

When the SDK falls back to the developer-provided refresh() because the SAT lacked sat:refresh scope, a credential_refresh_fallback event is emitted on SignalWire.warnings$ so application code can observe the transition.

Mint a SAT via POST /api/fabric/subscribers/tokens with fingerprint and scope: ["sat:refresh"] (both currently optional on that endpoint) to enable the Client Bound SAT path; otherwise provide refresh() here.

Properties

refresh

() => Promise<SDKCredential>

Obtains fresh credentials before the current ones expire. Optional. Implementor responsibilities: - Resolve with a new SDKCredential containing an updated token (or authorizationState) and expiry_at. - Reject (throw) if refresh is not possible, the SDK will stop the refresh schedule. SDK behavior: - Only called when expiry_at was set on the previous credential AND the SAT does not carry sat:refresh scope (otherwise the SDK refreshes internally via Client Bound SAT). See the precedence table above. - Scheduled automatically before expiry; implementors do not need to manage timing. - On rejection, the refresh schedule stops and the session continues with the current credentials until they expire.

Methods

authenticate()

authenticate(context?): Promise<SDKCredential>

Obtains the initial credentials. Called once during client initialization.

Implementor responsibilities:

Resolve with a valid SDKCredential on success.
Reject (throw) on failure, this will cause client initialization to fail.
When context.fingerprint is provided, forward it to the server-side token endpoint with scope: "sat:refresh" to enable automatic token refresh. Ignoring context.fingerprint causes the SDK to fall back to refresh() (if provided) or end the session at expiry.

SDK behavior:

Awaits this method before establishing the WebSocket connection.
On rejection, propagates the error to the caller of SignalWire().

Parameters

context

AuthenticateContext

Authentication context provided by the SDK at credential-request time. See AuthenticateContext.

Returns

Promise<SDKCredential>

CredentialRefreshFallbackWarning

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Emitted when the SDK falls back to the developer-provided CredentialProvider.refresh because the Client Bound SAT path could not take over.

Common causes:

The minted SAT lacks sat:refresh scope (reason: 'no-scope').
The /devices/token exchange failed transiently (reason: 'endpoint-failed'; see DeviceTokenError).

Subscribe via client.warnings$ to detect:

SDKs running with plain SATs that rely on developer-managed refresh
Deployments expected to use bound tokens that silently downgraded to bearer (a security-relevant signal for fleet observability)

Properties

code

"credential_refresh_fallback"Required

Discriminant identifying this warning.

source

"CredentialProvider"Required

The SDK subsystem that emitted the warning.

reason

CredentialRefreshFallbackReasonRequired

Why the fallback occurred. See CredentialRefreshFallbackReason.

message

stringRequired

Human-readable description of the fallback.

DebugOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Debug options that control verbose SDK logging.

Properties

logWsTraffic

boolean

Log all WebSocket send/recv traffic to the console.

DeviceController

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Interface for media device management.

Provides reactive access to available media devices, device selection, and monitoring for device changes (connect/disconnect).

Properties

audioInputDevices

MediaDeviceInfo[]Required

Current snapshot of available audio input devices. See MediaDeviceInfo.

audioInputDevices$

Observable<MediaDeviceInfo[]>Required

Observable list of available audio input (microphone) devices. See MediaDeviceInfo.

audioInputDisabled

booleanRequired

Whether audio input is currently disabled.

audioInputDisabled$

Observable<boolean>Required

Observable that emits true when audio input is disabled (receive-only).

audioOutputDevices

MediaDeviceInfo[]Required

Current snapshot of available audio output devices. See MediaDeviceInfo.

audioOutputDevices$

Observable<MediaDeviceInfo[]>Required

Observable list of available audio output (speaker) devices. See MediaDeviceInfo.

deviceRecovered$

Observable<DeviceRecoveryEvent>Required

Observable that emits when the SDK auto-switches a device due to disconnect, reconnect, or recovery. See DeviceRecoveryEvent.

errors$

Observable<Error>Required

Observable stream of errors from device enumeration and monitoring.

selectedAudioInputDevice

MediaDeviceInfo | nullRequired

Currently selected audio input device, or null if none. See MediaDeviceInfo.

selectedAudioInputDevice$

Observable<MediaDeviceInfo | null>Required

Observable of the currently selected audio input device, or null if none. See MediaDeviceInfo.

selectedAudioInputDeviceConstraints

boolean | MediaTrackConstraintsRequired

Media track constraints for the selected audio input device. Returns false when disabled. See MediaTrackConstraints.

selectedAudioOutputDevice

MediaDeviceInfo | nullRequired

Currently selected audio output device, or null if none. See MediaDeviceInfo.

selectedAudioOutputDevice$

Observable<MediaDeviceInfo | null>Required

Observable of the currently selected audio output device, or null if none. See MediaDeviceInfo.

selectedVideoInputDevice

MediaDeviceInfo | nullRequired

Currently selected video input device, or null if none. See MediaDeviceInfo.

selectedVideoInputDevice$

Observable<MediaDeviceInfo | null>Required

Observable of the currently selected video input device, or null if none. See MediaDeviceInfo.

selectedVideoInputDeviceConstraints

boolean | MediaTrackConstraintsRequired

Media track constraints for the selected video input device. Returns false when disabled. See MediaTrackConstraints.

videoInputDevices

MediaDeviceInfo[]Required

Current snapshot of available video input devices. See MediaDeviceInfo.

videoInputDevices$

Observable<MediaDeviceInfo[]>Required

Observable list of available video input (camera) devices. See MediaDeviceInfo.

videoInputDisabled

booleanRequired

Whether video input is currently disabled.

videoInputDisabled$

Observable<boolean>Required

Observable that emits true when video input is disabled (receive-only).

Methods

clearDeviceState()

clearDeviceState(): Promise<void>

Clears all device state (history, selections, persisted prefs) and re-enumerates.

Returns

Promise<void>

deviceInfoToConstraints()

deviceInfoToConstraints(deviceInfo): MediaTrackConstraints

Converts a MediaDeviceInfo to track constraints suitable for getUserMedia.

Parameters

getDeviceCapabilities()

getDeviceCapabilities(deviceInfo): Promise<MediaTrackCapabilities | null>

Returns the capabilities of a media device.

Parameters

deviceInfo

MediaDeviceInfoRequired

The device to query. See MediaDeviceInfo.

Returns

Promise<MediaTrackCapabilities | null>

The device capabilities, or null if unavailable.

isValidDevice()

isValidDevice(deviceInfo): Promise<boolean>

Checks whether a device is still available and usable.

Parameters

deviceInfo

MediaDeviceInfo | nullRequired

The device to validate, or null. See MediaDeviceInfo.

Returns

Promise<boolean>

true if the device is valid and available. Returns false for null, audio output devices, or unavailable devices.

selectAudioInputDevice()

selectAudioInputDevice(device): void

Sets the preferred audio input device for future calls.

Parameters

device

MediaDeviceInfo | nullRequired

The device to select, or null to use the system default. See MediaDeviceInfo.

Returns

void

selectAudioOutputDevice()

selectAudioOutputDevice(device): void

Sets the preferred audio output device for future calls.

Parameters

device

MediaDeviceInfo | nullRequired

The device to select, or null to use the system default. See MediaDeviceInfo.

Returns

void

selectVideoInputDevice()

selectVideoInputDevice(device): void

Sets the preferred video input device for future calls.

Parameters

device

MediaDeviceInfo | nullRequired

The device to select, or null to use the system default. See MediaDeviceInfo.

Returns

void

setStorageManager()

setStorageManager(storageManager): void

Injects the storage manager for device persistence.

Parameters

storageManager

StorageManagerRequired

Optional storage manager used to persist device selections.

Returns

void

DeviceRecoveryEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Event emitted when the SDK auto-switches a device.

Properties

kind

audioinput | audiooutput | videoinputRequired

The kind of device that was switched.

newDevice

MediaDeviceInfo | nullRequired

The device that was selected as a replacement (null if none available). See MediaDeviceInfo.

previousDevice

MediaDeviceInfo | nullRequired

The device that was previously selected (null if none). See MediaDeviceInfo.

reason

The reason for the device switch.

DiagnosticEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

A single diagnostic event in the session timeline.

Properties

details

Readonly<Record<string, unknown>>

Additional details about the event.

event

stringRequired

Event description string.

timestamp

numberRequired

Timestamp when the event occurred (epoch ms).

DialOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Options for SignalWire.dial. Extends MediaOptions with dial-specific settings.

Extends

MediaOptions

Properties

nodeId

string

Optional node ID for routing the call

preferredAudioCodecs

string[]

Preferred audio codecs for this call (overrides global preferences).

preferredVideoCodecs

string[]

Preferred video codecs for this call (overrides global preferences).

stereo

boolean

Enable stereo Opus for this call (overrides global preferences).

userVariables

Record<string, unknown>

Custom variables sent with the Verto invite. Merged with client.preferences.userVariables and any query-string variables on the destination URI; values here take precedence.

Inherited from MediaOptions

audio

AddressProvider<Address> (see Address)

Properties

addresses

Address[]

Current snapshot of all addresses in the directory

addresses$

Observable<Address[]>

Observable stream of all addresses in the directory Emits a new array whenever addresses are added, removed, or updated

hasMore$

Observable<boolean>

Observable indicating whether more addresses can be loaded from the server

loading

boolean

Whether the directory is currently loading.

loading$

Observable<boolean>

Observable indicating the current loading state Emits true when loading, false when idle

Methods

findAddressIdByURI()

findAddressIdByURI(uri): Promise<string | undefined>

Find an address ID by searching for a name

Parameters

uri

stringRequired

The address name to search for

Returns

Promise<string | undefined>

Promise resolving to the address ID, or undefined if not found

get()

get(addressId): Address | undefined

Get a specific address by ID

Parameters

addressId

stringRequired

The address ID to retrieve

Returns

Address | undefined

The address instance, or undefined if not found

get$()

get$(id): Observable<Address> | undefined

Get an observable stream for a specific address by ID

Parameters

id

stringRequired

The address ID to retrieve

Returns

Observable<Address> | undefined

Observable of the address, or undefined if not found

Inherited from

AddressProvider.get$

loadMore()

loadMore(): void

Load more addresses from the server Only loads if hasMore is true

Returns

void

JSONRPCErrorResponse

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Shape of a JSON-RPC 2.0 error response. Returned from WebRTCCall.execute and executeMethod when the server reports an error.

Properties

error

TError

Error object describing the failure.

id

stringRequired

ID matching the original request.

jsonrpc

"2.0"Required

JSON-RPC protocol version. Always "2.0".

result

TError

Always absent on error responses (typed for union discrimination).

JSONRPCRequest<TParams>

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Shape of an outgoing JSON-RPC 2.0 request. Used as the input to WebRTCCall.execute for direct RPC sends.

Type Parameters

Type Parameter	Default type
`TParams`	`unknown`

Properties

id

stringRequired

Request ID, echoed back in the matching response.

jsonrpc

"2.0"Required

JSON-RPC protocol version. Always "2.0".

method

stringRequired

RPC method name.

params

TParams

Method-specific parameters.

JSONRPCSuccessResponse<TResult>

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Shape of a JSON-RPC 2.0 successful response. Returned from WebRTCCall.execute and executeMethod on success.

Type Parameters

Type Parameter	Default type
`TResult`	`unknown`

Properties

error

undefined

Always absent on success responses (typed for union discrimination).

id

stringRequired

ID matching the original request.

jsonrpc

"2.0"Required

JSON-RPC protocol version. Always "2.0".

result

TResultRequired

Method-specific result payload.

LayoutLayer

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Position, size, and state of a single layer in a video call layout. Layers are emitted by call.layoutLayers$ and update whenever the server reflows the layout.

Properties

Properties

audio

RTCRtpTransceiverDirectionRequired

Audio direction. See RTCRtpTransceiverDirection.

video

RTCRtpTransceiverDirectionRequired

Video direction. See RTCRtpTransceiverDirection.

MediaOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Options controlling which media tracks to send and receive.

Extended by

DialOptions
CallOptions

Enable video input. Defaults to false when not specified.

MediaParamsEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Event emitted when server-pushed media params are applied.

Properties

audio

MediaTrackConstraints

Audio constraints pushed by the server, if any. See MediaTrackConstraints.

timestamp

numberRequired

Timestamp when the event occurred (epoch ms).

video

MediaTrackConstraints

Video constraints pushed by the server, if any. See MediaTrackConstraints.

MemberCapabilities

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

There’s a difference in searchParams between URL from lib and URL from url (node) that makes using the same not possible for us.

Constructors

Constructor

new NodeSocketAdapter(address, options?): NodeSocketClient

Parameters

address

string | URLRequired

WebSocket URL to connect to. See URL.

options

unknown

Underlying socket-library options.

Returns

NodeSocketClient

Constructor

new NodeSocketAdapter(address, protocols?, options?): NodeSocketClient

Parameters

address

string | URLRequired

WebSocket URL to connect to. See URL.

protocols

string | string[]

Optional WebSocket sub-protocol(s) to request.

options

unknown

Underlying socket-library options.

MediaDeviceInfo

The audio device the user selected in the browser picker, if any. See MediaDeviceInfo.

selectedVideoDevice

MediaDeviceInfo

The video device the user selected in the browser picker, if any. See MediaDeviceInfo.

video

booleanRequired

Whether video permission was granted.

PlatformCapabilities

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Browser/platform WebRTC capability flags.

Properties

Test a specific audio device instead of the currently selected one. See MediaDeviceInfo.

duration

number

How long to run the media test in seconds (default: 10).

skipMediaTest

boolean

Skip the media/bandwidth test, only test signaling + TURN + devices.

videoDevice

MediaDeviceInfo

Test a specific video device instead of the currently selected one. See MediaDeviceInfo.

PreflightResult

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

readonly string[]Required

Human-readable warnings.

RecoveryEvent

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Event emitted when a recovery action is taken on a call.

Properties

action

The recovery action that was taken.

attempt

number

Current attempt number (for multi-attempt recoveries).

maxAttempts

number

Maximum number of attempts allowed.

reason

stringRequired

Human-readable description of why recovery was triggered.

timestamp

numberRequired

Timestamp when the event occurred (epoch ms).

SATClaims

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SAT claims returned by /api/fabric/subscriber/info.

Properties

cnf

object

Confirmation claim binding the token to a key.

cnf.jkt

string

DPoP key thumbprint binding the SAT to a specific key.

expires_at

number

Token expiry timestamp in seconds since epoch.

scope

string[]

Token scopes (e.g., [“sat:refresh”]).

SDKCredential

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Authentication credentials for the SDK.

At least one of token or authorizationState must be provided.

Properties

authorizationState

string

Pre-authorized session state (alternative to token).

expiry_at

number

Token expiry timestamp in milliseconds since epoch. When set, the SDK attempts credential refresh before expiry.

token

string

JWT subscriber access token (SAT).

SDKLogger

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Logger interface that consumers can implement to replace the built-in logger. All methods accept variadic arguments matching the browser console API.

Methods

debug()

debug(...args): void

Parameters

args

unknown[]Required

Variadic log arguments.

Returns

void

error()

error(...args): void

Parameters

args

unknown[]Required

Variadic log arguments.

Returns

void

info()

info(...args): void

Parameters

args

unknown[]Required

Variadic log arguments.

Returns

void

trace()

trace(...args): void

Parameters

args

unknown[]Required

Variadic log arguments.

Returns

void

warn()

warn(...args): void

Parameters

args

unknown[]Required

Variadic log arguments.

Returns

void

SelectDeviceOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Options for selecting a media device.

Properties

savePreference

boolean

If true, persist this device selection as the user’s preferred device.

SessionDiagnostics

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Structured diagnostic bundle for a session.

Properties

calls

readonly CallDiagnosticSummary[]Required

Quality summary per call. See CallDiagnosticSummary.

capabilities

PlatformCapabilitiesRequired

Platform capabilities detected at construction time. See PlatformCapabilities.

deviceChanges

readonly DeviceRecoveryEvent[]Required

Device changes that occurred during the session. See DeviceRecoveryEvent.

devices

objectRequired

Current device list snapshot.

devices.audioInput

readonly MediaDeviceInfo[]Required

Snapshot of audio input devices visible to the session. See MediaDeviceInfo.

devices.audioOutput

readonly MediaDeviceInfo[]Required

Snapshot of audio output devices visible to the session. See MediaDeviceInfo.

devices.videoInput

readonly MediaDeviceInfo[]Required

Snapshot of video input devices visible to the session. See MediaDeviceInfo.

events

readonly DiagnosticEvent[]Required

Timeline of significant events during the session. See DiagnosticEvent.

sdkVersion

stringRequired

SDK version.

userAgent

stringRequired

Browser/platform user agent string.

SessionState

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Extended session interface that adds call management and authentication state on top of the narrow ClientSession contract.

Accessible via client.session. Call and CallFactory continue to depend only on the narrow ClientSession interface.

Extends

ClientSession

Properties

authenticated

booleanRequired

Current authentication state. Returns true if the session is currently authenticated.

authenticated$

Observable<boolean>Required

Observable that emits true once the session has been authenticated, and false after disconnect.

calls

Call[]Required

Current snapshot of all active calls. See Call.

calls$

Observable<Call[]>Required

Observable stream of all currently active calls (both inbound and outbound). See Call.

incomingCalls

Call[]Required

Current snapshot of active inbound calls. See Call.

incomingCalls$

Observable<Call[]>Required

Observable stream of currently active inbound calls. Filters calls$ to only include calls with direction === 'inbound'. See Call.

Inherited from ClientSession

iceServers

RTCIceServer[] | undefinedRequired

ICE servers configuration for WebRTC peer connections Used by VertoManager to configure RTCPeerConnection. See RTCIceServer.

signalingEvent$

Observable<Record<string, unknown>>Required

Observable stream of incoming signaling events Used by Call to listen for call-related events from the server

Methods

execute()

execute<T>(request, options?): Promise<T>

Execute an RPC request through the session transport

Type Parameters

Type Parameter	Default type
`T` extends `JSONRPCResponse`	`JSONRPCResponse`

Parameters

request

JSONRPCRequestRequired

The JSON-RPC request to execute. See JSONRPCRequest.

options

PendingRPCOptions

Optional RPC execution options (timeout, etc.) See PendingRPCOptions.

Returns

Promise<T>

Promise resolving to the RPC response

Inherited from

ClientSession.execute

SignalWireOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

NodeSocketAdapter | WebSocketAdapter

Custom WebSocket constructor. See NodeSocketAdapter and WebSocketAdapter.

Storage

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Key-value storage interface for persisting SDK preferences and state.

Methods

clear()

clear(scope): Promise<void>

Clears all keys in the given scope. Implementations may scope the clear to SDK keys only.

Parameters

scope

StorageScopeRequired

Storage scope (e.g. session vs. persistent).

Returns

Promise<void>

getItem()

getItem(key, scope): Promise<string | null>

Parameters

key

stringRequired

Storage key to read or write.

scope

StorageScopeRequired

Storage scope (e.g. session vs. persistent).

Returns

Promise<string | null>

removeItem()

removeItem(key, scope): Promise<void>

Parameters

key

stringRequired

Storage key to read or write.

scope

StorageScopeRequired

Storage scope (e.g. session vs. persistent).

Returns

Promise<void>

setItem()

setItem(key, value, scope): Promise<void>

Parameters

key

stringRequired

Storage key to read or write.

value

string | nullRequired

Value to write, or null to clear the key.

scope

StorageScopeRequired

Storage scope (e.g. session vs. persistent).

Returns

Promise<void>

StoredDevicePreference

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Serializable subset of MediaDeviceInfo for persistence.

Uses a generic type parameter to maintain type safety while avoiding circular dependencies. The Address class provides the concrete type.

Type Parameters

Type Parameter	Default type	Description
`TAddress`	`never`	The Address type, provided by the implementation

Properties

Target destination URI (address or SIP URI) to transfer the call to.

WebRTCApiProvider

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Provides custom WebRTC API implementations for non-standard environments.

Use this when the standard browser WebRTC APIs are not available or need to be replaced (e.g., Citrix HDX, React Native, Electron).

Examples

import { SignalWire, type WebRTCApiProvider } from '@signalwire/js';

const provider: WebRTCApiProvider = {
  RTCPeerConnection: CustomRTCPeerConnection,
  mediaDevices: {
    getUserMedia: (constraints) => customGetUserMedia(constraints),
    enumerateDevices: () => customEnumerateDevices(),
    addEventListener: (type, listener) => { ... },
    removeEventListener: (type, listener) => { ... },
  }
};

const client = new SignalWire(credentialProvider, { webRTCApiProvider: provider });

Properties

mediaDevices

WebRTCMediaDevicesRequired

Custom media device access. Only the methods used by the SDK are required. See WebRTCMediaDevices.

RTCPeerConnection

(configuration?) => RTCPeerConnectionRequired

Custom RTCPeerConnection constructor.

WebRTCMediaDevices

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Subset of the MediaDevices interface actually used by the SDK.

Implementations only need to provide these methods, the full browser MediaDevices type is intentionally not required so that React Native and other non-browser environments can conform without polyfilling unused APIs.

Methods

addEventListener()

addEventListener(type, listener): void

Parameters

type

stringRequired

Event type to listen for.

listener

EventListenerOrEventListenerObjectRequired

Listener invoked when the event fires.

Returns

void

enumerateDevices()

enumerateDevices(): Promise<MediaDeviceInfo[]>

Returns

Promise<MediaDeviceInfo[]>

getDisplayMedia()?

optional getDisplayMedia(options): Promise<MediaStream>

Parameters

options

DisplayMediaStreamOptionsRequired

Options to pass to getDisplayMedia.

Returns

Promise<MediaStream>

getUserMedia()

getUserMedia(constraints): Promise<MediaStream>

Parameters

constraints

MediaStreamConstraintsRequired

Media-track constraints to pass to getUserMedia.

Returns

Promise<MediaStream>

removeEventListener()

removeEventListener(type, listener): void

Parameters

type

stringRequired

Event type to listen for.

listener

EventListenerOrEventListenerObjectRequired

Listener invoked when the event fires.

Returns

void

Participant

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Participant represents a remote member on an active WebRTCCall. Instances are created by the call when members join and removed when they leave, applications obtain them through call.participants$, not by construction.

Each participant exposes every per-member piece of state the SDK tracks: mute state (audio/video), microphone processing flags (auto-gain, noise suppression, echo cancellation), display name, hand-raise, talking detection, sensitivity/volume levels, and current layout position. State is exposed in two complementary forms, a snapshot getter (e.g. audioMuted) for one-shot reads and an observable (audioMuted$) for reactive UI binding.

Control methods (muteAudio, setMeta, toggleLowbitrate, etc.) issue server-side requests scoped to this member. Their effect depends on the caller’s capabilities, inspect the local SelfCapabilities before exposing controls in your UI. For the local participant, which adds device selection, screen sharing, and local media stream control, use SelfParticipant.

Extends

Destroyable

Extended by

SelfParticipant

Implements

CallParticipant

Constructors

Constructor

new Participant(id, executeMethod, deviceController): Participant

Parameters

id

stringRequired

Unique identifier for this entity.

executeMethod

ExecuteMethodRequired

Function used to send execute RPC calls on this entity. See ExecuteMethod.

deviceController

DeviceControllerRequired

Device controller responsible for media-device enumeration and selection. See DeviceController.

Returns

Participant

Properties

id

stringRequired

Unique member ID of this participant.

Accessors

addressId$\ \ Observable of the participant’s address ID. audioMuted$\ \ Observable indicating whether the participant’s audio is muted. autoGain$\ \ Observable indicating whether auto-gain control is enabled. deaf$\ \ Observable indicating whether the participant is deafened. denoise$\ \ Observable indicating whether noise reduction is active. destroyed$\ \ Observable that emits when the instance is destroyed echoCancellation$\ \ Observable indicating whether echo cancellation is enabled. handraised$\ \ Observable indicating whether the participant has raised their hand. inputSensitivity$\ \ Observable of the conference-only microphone energy/gate sensitivity level for this member. inputVolume$\ \ Observable of the participant’s server-side microphone input volume as reported by the mix engine. isAudience\ \ Whether the participant is an audience member (view-only). isTalking$\ \ Observable indicating whether the participant is currently speaking. lowbitrate$\ \ Observable indicating whether low-bitrate mode is active. meta$\ \ Observable of custom metadata for this participant. name$\ \ Observable of the participant’s display name. nodeId$\ \ Observable of the server node ID for this participant. noiseSuppression$\ \ Observable indicating whether noise suppression is enabled. outputVolume$\ \ Observable of the participant’s server-side speaker output volume as reported by the mix engine (FreeSWITCH channel write volume). position$\ \ Observable of the participant’s layout position. type$\ \ Observable of the participant type (e.g. 'member', 'screen'). userId$\ \ Observable of the participant’s user ID. videoMuted$\ \ Observable indicating whether the participant’s video is muted. visible$\ \ Observable indicating whether the participant is visible in the layout.

Methods

destroy\ \ Destroys the participant, releasing all subscriptions and references. end\ \ Ends the call for this participant. mute\ \ Mutes the participant’s audio. muteVideo\ \ Mutes the participant’s video. remove\ \ Removes this participant from the call. setAudioInputSensitivity\ \ Adjusts the conference-only microphone energy gate / sensitivity level for this member. setAudioInputVolume\ \ Sets the server-side microphone volume on this participant’s bridged call leg. setAudioOutputVolume\ \ Sets the server-side speaker volume on this participant’s bridged call leg (FreeSWITCH channel write volume), what this participant hears from the mix before it reaches their client. setMeta\ \ Replaces custom metadata for this participant. setPosition\ \ Sets the participant’s position in the video layout. toggleAudioInputAutoGain\ \ Toggles automatic gain control on the audio input. toggleDeaf\ \ Toggles the deafened state (mutes/unmutes incoming audio). toggleEchoCancellation\ \ Toggles echo cancellation on the audio input. toggleHandraise\ \ Toggles the hand-raised state. toggleLowbitrate\ \ Toggles the participant’s low-bitrate mode. toggleMute\ \ Toggles the participant’s audio mute state. toggleMuteVideo\ \ Toggles the participant’s video mute state. toggleNoiseSuppression\ \ Toggles noise suppression on the audio input. unmute\ \ Unmutes the participant’s audio. unmuteVideo\ \ Unmutes the participant’s video. updateMeta\ \ Merges values into custom metadata (unlike setMeta which replaces).

addressId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get addressId$(): Observable<string | undefined>

Observable of the participant’s address ID.

addressId

get addressId(): string | undefined

Address ID of this participant, or undefined if not available.

Examples

participant.addressId$.subscribe((addressId) => {
  console.log('addressId:', addressId);
});

audioMuted$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get audioMuted$(): Observable<boolean | undefined>

Observable indicating whether the participant’s audio is muted.

audioMuted

get audioMuted(): boolean

Whether the participant’s audio is muted.

Examples

participant.audioMuted$.subscribe((audioMuted) => {
  console.log('audioMuted:', audioMuted);
});

autoGain$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get autoGain$(): Observable<boolean | undefined>

Observable indicating whether auto-gain control is enabled.

autoGain

get autoGain(): boolean

Whether automatic gain control is enabled.

Examples

participant.autoGain$.subscribe((autoGain) => {
  console.log('autoGain:', autoGain);
});

deaf$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get deaf$(): Observable<boolean | undefined>

Observable indicating whether the participant is deafened.

deaf

get deaf(): boolean

Whether the participant is deafened (incoming audio muted).

Examples

participant.deaf$.subscribe((deaf) => {
  console.log('deaf:', deaf);
});

denoise$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get denoise$(): Observable<boolean | undefined>

Observable indicating whether noise reduction is active.

denoise

get denoise(): boolean

Whether noise reduction (denoise) is active.

Examples

participant.denoise$.subscribe((denoise) => {
  console.log('denoise:', denoise);
});

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Destroys the participant, releasing all subscriptions and references.

Returns

void

Examples

participant.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Destroyable.destroyed$

Examples

participant.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

echoCancellation$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get echoCancellation$(): Observable<boolean | undefined>

Observable indicating whether echo cancellation is enabled.

echoCancellation

get echoCancellation(): boolean

Whether echo cancellation is enabled.

Examples

participant.echoCancellation$.subscribe((echoCancellation) => {
  console.log('echoCancellation:', echoCancellation);
});

end

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

end(): Promise<void>

Ends the call for this participant.

Examples

await participant.end();

See

WebRTCCall.status$, transitions to 'destroyed' after the call ends.
Gated by SelfCapabilities.end.

handraised$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get handraised$(): Observable<boolean | undefined>

Observable indicating whether the participant has raised their hand.

handraised

get handraised(): boolean

Whether the participant has raised their hand.

Examples

participant.handraised$.subscribe((handraised) => {
  console.log('handraised:', handraised);
});

inputSensitivity$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputSensitivity$(): Observable<number | undefined>

Observable of the conference-only microphone energy/gate sensitivity level for this member. Routes through the conferencing mix engine and has no effect on 1:1 WebRTC calls. Populated from member.updated events for conference members.

See setAudioInputSensitivity

inputSensitivity

get inputSensitivity(): number | undefined

Current conference-only microphone sensitivity/gate level, or undefined if not set. Applies only to conference members.

Examples

participant.inputSensitivity$.subscribe((inputSensitivity) => {
  console.log('inputSensitivity:', inputSensitivity);
});

inputVolume$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputVolume$(): Observable<number | undefined>

Observable of the participant’s server-side microphone input volume as reported by the mix engine. This is gain applied on the bridged audio leg (FreeSWITCH channel read volume), NOT the local browser mic. For a local PC mic control, see Call.setLocalMicrophoneGain.

See setAudioInputVolume

inputVolume

get inputVolume(): number | undefined

Current server-side microphone input volume as reported by the mix engine, or undefined if not set. Not the local PC mic, see Call.setLocalMicrophoneGain for browser-side control.

Examples

participant.inputVolume$.subscribe((inputVolume) => {
  console.log('inputVolume:', inputVolume);
});

isAudience

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isAudience(): boolean

Whether the participant is an audience member (view-only).

Examples

console.log(participant.isAudience);

isTalking$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isTalking$(): Observable<boolean | undefined>

Observable indicating whether the participant is currently speaking.

isTalking

get isTalking(): boolean

Whether the participant is currently speaking.

Examples

participant.isTalking$.subscribe((isTalking) => {
  console.log('isTalking:', isTalking);
});

lowbitrate$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get lowbitrate$(): Observable<boolean | undefined>

Observable indicating whether low-bitrate mode is active.

lowbitrate

get lowbitrate(): boolean

Whether low-bitrate mode is active.

Examples

participant.lowbitrate$.subscribe((lowbitrate) => {
  console.log('lowbitrate:', lowbitrate);
});

meta$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get meta$(): Observable<Record<string, unknown> | undefined>

Observable of custom metadata for this participant.

meta

get meta(): Record<string, unknown> | undefined

Custom metadata for this participant, or undefined if not set.

Examples

participant.meta$.subscribe((meta) => {
  console.log('meta:', meta);
});

mute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

mute(): Promise<void>

Mutes the participant’s audio.

Examples

await participant.mute();

See

audioMuted$, reactive state pair.
toggleMute / unmute.

name$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get name$(): Observable<string | undefined>

Observable of the participant’s display name.

name

get name(): string | undefined

Display name of this participant.

Examples

participant.name$.subscribe((name) => {
  console.log('name:', name);
});

nodeId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get nodeId$(): Observable<string | undefined>

Observable of the server node ID for this participant.

nodeId

get nodeId(): string | undefined

Server node ID for this participant, or undefined if not available.

Examples

participant.nodeId$.subscribe((nodeId) => {
  console.log('nodeId:', nodeId);
});

noiseSuppression$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get noiseSuppression$(): Observable<boolean | undefined>

Observable indicating whether noise suppression is enabled.

noiseSuppression

get noiseSuppression(): boolean

Whether noise suppression is enabled.

Examples

participant.noiseSuppression$.subscribe((noiseSuppression) => {
  console.log('noiseSuppression:', noiseSuppression);
});

outputVolume$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get outputVolume$(): Observable<number | undefined>

Observable of the participant’s server-side speaker output volume as reported by the mix engine (FreeSWITCH channel write volume). NOT the local HTML <audio> element volume, set that on your own element.

See setAudioOutputVolume

outputVolume

get outputVolume(): number | undefined

Current server-side speaker output volume from the mix engine, or undefined if not set. Not the local <audio> element volume.

Examples

participant.outputVolume$.subscribe((outputVolume) => {
  console.log('outputVolume:', outputVolume);
});

position$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get position$(): Observable<LayoutLayer | undefined>

Observable of the participant’s layout position.

position

get position(): LayoutLayer | undefined

Current layout position.

Examples

participant.position$.subscribe((position) => {
  console.log('position:', position);
});

remove

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

remove(): Promise<void>

Removes this participant from the call.

Returns

Promise<void>

Examples

await participant.remove();

See

WebRTCCall.participants$, emits a new list without the removed member.
Gated by SelfCapabilities.member.remove.

setAudioInputSensitivity

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioInputSensitivity(value): Promise<void>

Adjusts the conference-only microphone energy gate / sensitivity level for this member. Routes through the conferencing mix engine (signalwire.conferencing member.set_input_sensitivity) and has no effect on 1:1 WebRTC calls, for those, use browser audio constraints via Call.setNoiseSuppression / Call.setAutoGainControl.

This is not a local PC mic gain control; it only changes how the server-side mixer decides to open the mic gate on this participant.

Parameters

value

numberRequired

Sensitivity level as understood by the conference engine (integer, larger values are more sensitive).

Returns

Promise<void>

Examples

await participant.setAudioInputSensitivity(value);

See

inputSensitivity$, reactive state pair.
Gated by SelfCapabilities.self.microphoneSensitivity.

setAudioInputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioInputVolume(value): Promise<void>

Sets the server-side microphone volume on this participant’s bridged call leg. Applies a multiplier to the audio flowing through the mix engine (FreeSWITCH channel read volume), changes what other participants hear, not what the local browser captures.

For local PC mic gain, use Call.setLocalMicrophoneGain instead.

Parameters

value

numberRequired

Volume level (0-100).

Returns

Promise<void>

Examples

await participant.setAudioInputVolume(value);

See

inputVolume$, reactive state pair.
Gated by SelfCapabilities.self.microphoneVolume.

setAudioOutputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioOutputVolume(value): Promise<void>

Sets the server-side speaker volume on this participant’s bridged call leg (FreeSWITCH channel write volume), what this participant hears from the mix before it reaches their client.

For local playback volume (the <audio> element the consumer attaches remoteStream to), set audioElement.volume directly in the consumer’s code.

Parameters

value

numberRequired

Volume level (0-100).

Returns

Promise<void>

Examples

await participant.setAudioOutputVolume(value);

See

outputVolume$, reactive state pair.
Gated by SelfCapabilities.self.speakerVolume.

setMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMeta(_meta): Promise<void>

Replaces custom metadata for this participant.

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

Metadata object to set.

Returns

Promise<void>

Throws

Throws unconditionally, implementation pending.

Examples

await participant.setMeta(_meta);

setPosition

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setPosition(value): Promise<void>

Sets the participant’s position in the video layout.

Parameters

value

VideoPositionRequired

The VideoPosition to assign (e.g. 'auto', 'reserved-0').

Returns

Promise<void>

Examples

await participant.setPosition(value);

See

position$, reactive layer position.
WebRTCCall.layoutLayers$, all positions for the active layout.
Gated by SelfCapabilities.self.position (for self) or SelfCapabilities.member.position (for moderation).

toggleAudioInputAutoGain

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleAudioInputAutoGain(): Promise<void>

Toggles automatic gain control on the audio input.

Returns

Promise<void>

Examples

await participant.toggleAudioInputAutoGain();

See

autoGain$, reactive state pair.
toggleEchoCancellation / toggleNoiseSuppression.

toggleDeaf

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleDeaf(): Promise<void>

Toggles the deafened state (mutes/unmutes incoming audio).

Returns

Promise<void>

Examples

await participant.toggleDeaf();

See

deaf$, reactive state pair.
Gated by SelfCapabilities.self.deaf.

toggleEchoCancellation

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleEchoCancellation(): Promise<void>

Toggles echo cancellation on the audio input.

Returns

Promise<void>

Examples

await participant.toggleEchoCancellation();

See

echoCancellation$, reactive state pair.
toggleAudioInputAutoGain / toggleNoiseSuppression.
SelfParticipant.enableStudioAudio, disable all three at once.

toggleHandraise

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleHandraise(): Promise<void>

Toggles the hand-raised state.

Returns

Promise<void>

Examples

await participant.toggleHandraise();

See

handraised$, reactive state pair.
raiseHandPriority$, whether the room prioritizes raised hands in layout.
Gated by SelfCapabilities.self.raisehand.

toggleLowbitrate

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleLowbitrate(): Promise<void>

Returns

Promise<void>

Examples

await participant.toggleLowbitrate();

toggleMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleMute(): Promise<void>

Toggles the participant’s audio mute state.

Returns

Promise<void>

Examples

await participant.toggleMute();

See

audioMuted$, reactive state pair.
mute / unmute, force a specific state.
Gated by SelfCapabilities.self.muteAudio.

toggleNoiseSuppression

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleNoiseSuppression(): Promise<void>

Toggles noise suppression on the audio input.

Returns

Promise<void>

Examples

await participant.toggleNoiseSuppression();

See

noiseSuppression$, reactive state pair.
toggleEchoCancellation / toggleAudioInputAutoGain.

type$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get type$(): Observable<string | undefined>

Observable of the participant type (e.g. 'member', 'screen').

type

get type(): string | undefined

Participant type (e.g. 'member', 'screen').

Examples

participant.type$.subscribe((type) => {
  console.log('type:', type);
});

unmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

unmute(): Promise<void>

Unmutes the participant’s audio.

Returns

Promise<void>

Examples

await participant.unmute();

See

audioMuted$, reactive state pair.
toggleMute / mute.

updateMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMeta(_meta): Promise<void>

Merges values into custom metadata (unlike setMeta which replaces).

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

Metadata to merge.

Returns

Promise<void>

Throws

Throws unconditionally, implementation pending.

Examples

await participant.updateMeta(_meta);

userId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get userId$(): Observable<string | undefined>

Observable of the participant’s user ID.

userId

get userId(): string | undefined

User ID of this participant, or undefined if not available.

Examples

participant.userId$.subscribe((userId) => {
  console.log('userId:', userId);
});

visible$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get visible$(): Observable<boolean | undefined>

Observable indicating whether the participant is visible in the layout.

visible

get visible(): boolean

Whether the participant is visible in the layout.

Examples

participant.visible$.subscribe((visible) => {
  console.log('visible:', visible);
});

SelfCapabilities

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SelfCapabilities manages the capability state for the self participant.

Capabilities are received from the server via call.joined events and determine what actions the current participant is allowed to perform.

Each capability is exposed as both:

An observable (e.g., end$) for reactive state management
A synchronous getter (e.g., end) for immediate access

Member-level capabilities are accessed via the grouped self / member accessors:

capabilities.self.muteAudio (sync)
capabilities.self$ (observable)

When a new call.joined event is received, the capabilities state is completely replaced (not merged).

Each capability is exposed in both forms on every page below, an observable (e.g. end$) for reactive UI binding, and a synchronous getter (e.g. end) for one-shot reads. The accessor cards below list the observable; click through for both signatures plus an example.

Extends

Destroyable

Constructors

Constructor

new SelfCapabilities(): SelfCapabilities

Returns

SelfCapabilities

Inherited from

Destroyable.constructor

Accessors

destroyed$\ \ Observable that emits when the instance is destroyed device$\ \ Observable for device capability end$\ \ Observable for end call capability lock$\ \ Observable for lock capability member$\ \ Observable for other member capabilities screenshare$\ \ Observable for screenshare capability self$\ \ Observable for self member capabilities sendDigit$\ \ Observable for send digit capability setLayout$\ \ Observable for set layout capability state$\ \ Observable for the full capabilities state vmutedHide$\ \ Observable for vmuted hide capability

Methods

destroy\ \ Cleans up subscriptions and subjects owned by this instance.

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Returns

void

Inherited from

Destroyable.destroy

Examples

capabilities.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Destroyable.destroyed$

Examples

capabilities.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

device$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get device$(): Observable<boolean>

Observable for device capability

device

get device(): boolean

Current device capability

Examples

capabilities.device$.subscribe((device) => {
  console.log('device:', device);
});

end$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get end$(): Observable<boolean>

Observable for end call capability

end

get end(): boolean

Current end call capability

Examples

capabilities.end$.subscribe((end) => {
  console.log('end:', end);
});

lock$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get lock$(): Observable<OnOffCapability>

Observable for lock capability

lock

get lock(): OnOffCapability

Current lock capability

Examples

capabilities.lock$.subscribe((lock) => {
  console.log('lock:', lock);
});

member$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get member$(): Observable<MemberCapabilities>

Observable for other member capabilities

member

get member(): MemberCapabilities

Current other member capabilities

Examples

capabilities.member$.subscribe((member) => {
  console.log('member:', member);
});

screenshare$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get screenshare$(): Observable<boolean>

Observable for screenshare capability

screenshare

get screenshare(): boolean

Current screenshare capability

Examples

capabilities.screenshare$.subscribe((screenshare) => {
  console.log('screenshare:', screenshare);
});

self$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get self$(): Observable<MemberCapabilities>

Observable for self member capabilities

self

get self(): MemberCapabilities

Current self member capabilities

Examples

capabilities.self$.subscribe((self) => {
  console.log('self:', self);
});

sendDigit$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get sendDigit$(): Observable<boolean>

Observable for send digit capability

sendDigit

get sendDigit(): boolean

Current send digit capability

Examples

capabilities.sendDigit$.subscribe((sendDigit) => {
  console.log('sendDigit:', sendDigit);
});

setLayout$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get setLayout$(): Observable<boolean>

Observable for set layout capability

setLayout

get setLayout(): boolean

Current set layout capability

Examples

capabilities.setLayout$.subscribe((setLayout) => {
  console.log('setLayout:', setLayout);
});

state$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get state$(): Observable<CallCapabilitiesState>

Observable for the full capabilities state

state

get state(): CallCapabilitiesState

Current full capabilities state

Examples

capabilities.state$.subscribe((state) => {
  console.log('state:', state);
});

vmutedHide$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get vmutedHide$(): Observable<OnOffCapability>

Observable for vmuted hide capability

vmutedHide

get vmutedHide(): OnOffCapability

Current vmuted hide capability

Examples

capabilities.vmutedHide$.subscribe((vmutedHide) => {
  console.log('vmutedHide:', vmutedHide);
});

SelfParticipant

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SelfParticipant is the local user’s view of themselves on a call. It extends Participant, inheriting every remote-side observable and control method, and adds the local-only surface area: device selection, screen sharing, the local MediaStream, and the per-call SelfCapabilities that gate which controls the server allows. Instances are created by the call on join and obtainable via call.self$.

Device-related methods (selectAudio*, selectVideo*, addAudioInputDevice, disableVideoInput, etc.) update the local capture and renegotiate the peer connection automatically. Screen-share methods (startScreenShare, stopScreenShare) acquire a getDisplayMedia track, publish it to the call, and update screenShareStatus$ accordingly. Media-processing toggles (setAutoGainControl, setEchoCancellation, setNoiseSuppression) modify the active audio track in place.

For checking whether a given action is permitted before exposing it in the UI, read capabilities (the underlying SelfCapabilities instance, which itself exposes each capability as both a snapshot and an observable).

Extends

Participant

Implements

CallSelfParticipant

Properties

capabilities

SelfCapabilities

Capabilities for this participant. Contains all capability flags as both observables and values.

id

stringRequired

Unique member ID of this participant.

Accessors

addressId$\ \ Observable of the participant’s address ID. audioMuted$\ \ Observable indicating whether the participant’s audio is muted. autoGain$\ \ Observable indicating whether auto-gain control is enabled. deaf$\ \ Observable indicating whether the participant is deafened. denoise$\ \ Observable indicating whether noise reduction is active. destroyed$\ \ Observable that emits when the instance is destroyed echoCancellation$\ \ Observable indicating whether echo cancellation is enabled. handraised$\ \ Observable indicating whether the participant has raised their hand. inputSensitivity$\ \ Observable of the conference-only microphone energy/gate sensitivity level for this member. inputVolume$\ \ Observable of the participant’s server-side microphone input volume as reported by the mix engine. isAudience\ \ Whether the participant is an audience member (view-only). isTalking$\ \ Observable indicating whether the participant is currently speaking. lowbitrate$\ \ Observable indicating whether low-bitrate mode is active. meta$\ \ Observable of custom metadata for this participant. name$\ \ Observable of the participant’s display name. nodeId$\ \ Observable of the server node ID for this participant. noiseSuppression$\ \ Observable indicating whether noise suppression is enabled. outputVolume$\ \ Observable of the participant’s server-side speaker output volume as reported by the mix engine (FreeSWITCH channel write volume). position$\ \ Observable of the participant’s layout position. screenShareStatus$\ \ Observable of the current screen share status. studioAudio$\ \ Observable indicating whether studio audio (raw/unprocessed audio) mode is enabled. type$\ \ Observable of the participant type (e.g. 'member', 'screen'). userId$\ \ Observable of the participant’s user ID. videoMuted$\ \ Observable indicating whether the participant’s video is muted. visible$\ \ Observable indicating whether the participant is visible in the layout.

Methods

addAdditionalDevice\ \ Adds an additional media input device to the call. addAudioInputDevice\ \ Adds or replaces the primary audio input device with optional constraints or stream. addInputDevices\ \ Adds or replaces primary input devices (audio and/or video). addVideoInputDevice\ \ Adds or replaces the primary video input device with optional constraints or stream. destroy\ \ Destroys the participant, releasing all subscriptions and references. disableStudioAudio\ \ Disables studio audio mode by restoring all audio processing to enabled. Sets echoCancellation, noiseSuppression, and autoGainControl to true. enableStudioAudio\ \ Enables studio audio mode by disabling all audio processing. Sets echoCancellation, noiseSuppression, and autoGainControl to false. end\ \ Ends the call for this participant. mute\ \ Mutes local audio. Falls back to local device mute if the server RPC fails. muteVideo\ \ Mutes local video. Falls back to local device mute if the server RPC fails. remove\ \ Removes this participant from the call. removeAdditionalDevice\ \ Removes an additional media input device by ID. selectAudioInputDevice\ \ Selects the audio input device for future calls. Optionally saves as a preference. selectAudioOutputDevice\ \ Selects the audio output device. Optionally saves as a preference. selectVideoInputDevice\ \ Selects the video input device for future calls. Optionally saves as a preference. setAudioInputDeviceConstraints\ \ Updates the audio input track constraints for the active call. setAudioInputSensitivity\ \ Adjusts the conference-only microphone energy gate / sensitivity level for this member. setAudioInputVolume\ \ Sets the server-side microphone volume on this participant’s bridged call leg. setAudioOutputVolume\ \ Sets the server-side speaker volume on this participant’s bridged call leg (FreeSWITCH channel write volume), what this participant hears from the mix before it reaches their client. setInputDevicesConstraints\ \ Updates both audio and video input track constraints for the active call. setMeta\ \ Replaces custom metadata for this participant. setPosition\ \ Sets the participant’s position in the video layout. setVideoInputDeviceConstraints\ \ Updates the video input track constraints for the active call. startScreenShare\ \ Starts sharing the local screen. stopScreenShare\ \ Stops the current screen share. toggleAudioInputAutoGain\ \ Toggles automatic gain control. Exits studio mode if active. toggleDeaf\ \ Toggles the deafened state (mutes/unmutes incoming audio). toggleEchoCancellation\ \ Toggles echo cancellation. Exits studio mode if active. toggleHandraise\ \ Toggles the hand-raised state. toggleLowbitrate\ \ Participant.toggleLowbitrate toggleMute\ \ Toggles the participant’s audio mute state. toggleMuteVideo\ \ Toggles the participant’s video mute state. toggleNoiseSuppression\ \ Toggles noise suppression. Exits studio mode if active. unmute\ \ Unmutes local audio. Falls back to local device unmute if the server RPC fails. unmuteVideo\ \ Unmutes local video. Falls back to local device unmute if the server RPC fails. updateMeta\ \ Merges values into custom metadata (unlike setMeta which replaces).

addAdditionalDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addAdditionalDevice(options): Promise<void>

Adds an additional media input device to the call.

Parameters

options

MediaOptionsRequired

Media constraints for the additional capture. See MediaOptions.

Returns

Promise<void>

Examples

await selfParticipant.addAdditionalDevice(options);

addAudioInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addAudioInputDevice(__namedParameters?): Promise<void>

Adds or replaces the primary audio input device with optional constraints or stream.

Parameters

__namedParameters

{ constraints?: MediaTrackConstraints; stream?: MediaStream; }

Capture options: either explicit constraints or a pre-acquired stream. See MediaTrackConstraints and MediaStream.

Returns

Promise<void>

Examples

await selfParticipant.addAudioInputDevice(__namedParameters);

addInputDevices

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addInputDevices(options?): Promise<void>

Adds or replaces primary input devices (audio and/or video).

Parameters

options

MediaOptions

Media constraints to apply when capturing the new input devices. See MediaOptions.

Returns

Promise<void>

Examples

await selfParticipant.addInputDevices(options);

addressId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get addressId$(): Observable<string | undefined>

Observable of the participant’s address ID.

Inherited from

Participant. addressId$

addressId

get addressId(): string | undefined

Address ID of this participant, or undefined if not available.

Inherited from

Participant. addressId

Examples

selfParticipant.addressId$.subscribe((addressId) => {
  console.log('addressId:', addressId);
});

audioMuted$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get audioMuted$(): Observable<boolean | undefined>

Observable indicating whether the participant’s audio is muted.

Inherited from

Participant. audioMuted$

audioMuted

get audioMuted(): boolean

Whether the participant’s audio is muted.

Inherited from

Participant. audioMuted

Examples

selfParticipant.audioMuted$.subscribe((audioMuted) => {
  console.log('audioMuted:', audioMuted);
});

autoGain$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get autoGain$(): Observable<boolean | undefined>

Observable indicating whether auto-gain control is enabled.

Inherited from

Participant. autoGain$

autoGain

get autoGain(): boolean

Whether automatic gain control is enabled.

Inherited from

Participant. autoGain

Examples

selfParticipant.autoGain$.subscribe((autoGain) => {
  console.log('autoGain:', autoGain);
});

deaf$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get deaf$(): Observable<boolean | undefined>

Observable indicating whether the participant is deafened.

Inherited from

Participant. deaf$

deaf

get deaf(): boolean

Whether the participant is deafened (incoming audio muted).

Inherited from

Participant. deaf

Examples

selfParticipant.deaf$.subscribe((deaf) => {
  console.log('deaf:', deaf);
});

denoise$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get denoise$(): Observable<boolean | undefined>

Observable indicating whether noise reduction is active.

Inherited from

Participant. denoise$

denoise

get denoise(): boolean

Whether noise reduction (denoise) is active.

Inherited from

Participant. denoise

Examples

selfParticipant.denoise$.subscribe((denoise) => {
  console.log('denoise:', denoise);
});

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Destroys the participant, releasing all subscriptions and references.

Returns

void

Examples

selfParticipant.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Participant. destroyed$

Examples

selfParticipant.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

disableStudioAudio

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disableStudioAudio(): Promise<void>

Disables studio audio mode by restoring all audio processing to enabled. Sets echoCancellation, noiseSuppression, and autoGainControl to true.

Returns

Promise<void>

Examples

await selfParticipant.disableStudioAudio();

See

studioAudio$, reactive state pair.
enableStudioAudio.

echoCancellation$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get echoCancellation$(): Observable<boolean | undefined>

Observable indicating whether echo cancellation is enabled.

Inherited from

Participant. echoCancellation$

echoCancellation

get echoCancellation(): boolean

Whether echo cancellation is enabled.

Inherited from

Participant. echoCancellation

Examples

selfParticipant.echoCancellation$.subscribe((echoCancellation) => {
  console.log('echoCancellation:', echoCancellation);
});

enableStudioAudio

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enableStudioAudio(): Promise<void>

Enables studio audio mode by disabling all audio processing. Sets echoCancellation, noiseSuppression, and autoGainControl to false.

Returns

Promise<void>

Examples

await selfParticipant.enableStudioAudio();

See

studioAudio$, reactive state pair.
disableStudioAudio, restore default processing.
Per-flag toggles: toggleEchoCancellation, toggleAudioInputAutoGain, toggleNoiseSuppression.

end

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

end(): Promise<void>

Ends the call for this participant.

Returns

Promise<void>

Inherited from

Participant. end

Examples

await selfParticipant.end();

handraised$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get handraised$(): Observable<boolean | undefined>

Observable indicating whether the participant has raised their hand.

Inherited from

Participant. handraised$

handraised

get handraised(): boolean

Whether the participant has raised their hand.

Inherited from

Participant. handraised

Examples

selfParticipant.handraised$.subscribe((handraised) => {
  console.log('handraised:', handraised);
});

inputSensitivity$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputSensitivity$(): Observable<number | undefined>

See

setAudioInputSensitivity

Inherited from

Participant. inputSensitivity$

inputSensitivity

get inputSensitivity(): number | undefined

Current conference-only microphone sensitivity/gate level, or undefined if not set. Applies only to conference members.

Inherited from

Participant. inputSensitivity

Examples

selfParticipant.inputSensitivity$.subscribe((inputSensitivity) => {
  console.log('inputSensitivity:', inputSensitivity);
});

inputVolume$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputVolume$(): Observable<number | undefined>

See

setAudioInputVolume

Inherited from

Participant. inputVolume$

inputVolume

get inputVolume(): number | undefined

Current server-side microphone input volume as reported by the mix engine, or undefined if not set. Not the local PC mic, see Call.setLocalMicrophoneGain for browser-side control.

Inherited from

Participant. inputVolume

Examples

selfParticipant.inputVolume$.subscribe((inputVolume) => {
  console.log('inputVolume:', inputVolume);
});

isAudience

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isAudience(): boolean

Whether the participant is an audience member (view-only).

Inherited from

Participant. isAudience

Examples

console.log(selfParticipant.isAudience);

isTalking$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isTalking$(): Observable<boolean | undefined>

Observable indicating whether the participant is currently speaking.

Inherited from

Participant. isTalking$

isTalking

get isTalking(): boolean

Whether the participant is currently speaking.

Inherited from

Participant. isTalking

Examples

selfParticipant.isTalking$.subscribe((isTalking) => {
  console.log('isTalking:', isTalking);
});

lowbitrate$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get lowbitrate$(): Observable<boolean | undefined>

Observable indicating whether low-bitrate mode is active.

Inherited from

Participant. lowbitrate$

lowbitrate

get lowbitrate(): boolean

Whether low-bitrate mode is active.

Inherited from

Participant. lowbitrate

Examples

selfParticipant.lowbitrate$.subscribe((lowbitrate) => {
  console.log('lowbitrate:', lowbitrate);
});

meta$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get meta$(): Observable<Record<string, unknown> | undefined>

Observable of custom metadata for this participant.

Inherited from

Participant. meta$

meta

get meta(): Record<string, unknown> | undefined

Custom metadata for this participant, or undefined if not set.

Inherited from

Participant. meta

Examples

selfParticipant.meta$.subscribe((meta) => {
  console.log('meta:', meta);
});

mute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

mute(): Promise<void>

Mutes local audio. Falls back to local device mute if the server RPC fails.

Returns

Promise<void>

Examples

await selfParticipant.mute();

name$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get name$(): Observable<string | undefined>

Observable of the participant’s display name.

Inherited from

Participant. name$

name

get name(): string | undefined

Display name of this participant.

Inherited from

Participant. name

Examples

selfParticipant.name$.subscribe((name) => {
  console.log('name:', name);
});

nodeId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get nodeId$(): Observable<string | undefined>

Observable of the server node ID for this participant.

Inherited from

Participant. nodeId$

nodeId

get nodeId(): string | undefined

Server node ID for this participant, or undefined if not available.

Inherited from

Participant. nodeId

Examples

selfParticipant.nodeId$.subscribe((nodeId) => {
  console.log('nodeId:', nodeId);
});

noiseSuppression$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get noiseSuppression$(): Observable<boolean | undefined>

Observable indicating whether noise suppression is enabled.

Inherited from

Participant. noiseSuppression$

noiseSuppression

get noiseSuppression(): boolean

Whether noise suppression is enabled.

Inherited from

Participant. noiseSuppression

Examples

selfParticipant.noiseSuppression$.subscribe((noiseSuppression) => {
  console.log('noiseSuppression:', noiseSuppression);
});

outputVolume$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get outputVolume$(): Observable<number | undefined>

See

setAudioOutputVolume

Inherited from

Participant. outputVolume$

outputVolume

get outputVolume(): number | undefined

Current server-side speaker output volume from the mix engine, or undefined if not set. Not the local <audio> element volume.

Inherited from

Participant. outputVolume

Examples

selfParticipant.outputVolume$.subscribe((outputVolume) => {
  console.log('outputVolume:', outputVolume);
});

position$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get position$(): Observable<LayoutLayer | undefined>

Observable of the participant’s layout position.

Inherited from

Participant. position$

position

get position(): LayoutLayer | undefined

Current layout position.

Inherited from

Participant. position

Examples

selfParticipant.position$.subscribe((position) => {
  console.log('position:', position);
});

remove

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

remove(): Promise<void>

Removes this participant from the call.

Returns

Promise<void>

Inherited from

Participant. remove

Examples

await selfParticipant.remove();

removeAdditionalDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

removeAdditionalDevice(id): Promise<void>

Removes an additional media input device by ID.

Parameters

id

stringRequired

ID of the additional device previously added via addAdditionalDevice.

Returns

Promise<void>

Examples

await selfParticipant.removeAdditionalDevice(id);

screenShareStatus$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get screenShareStatus$(): Observable<ScreenShareStatus>

Observable of the current screen share status.

screenShareStatus

get screenShareStatus(): ScreenShareStatus

Current screen share status.

Examples

selfParticipant.screenShareStatus$.subscribe((screenShareStatus) => {
  console.log('screenShareStatus:', screenShareStatus);
});

selectAudioInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectAudioInputDevice(device, options?): void

Selects the audio input device for future calls. Optionally saves as a preference.

Parameters

device

MediaDeviceInfoRequired

Device to select. See MediaDeviceInfo.

options

SelectDeviceOptions

Selection options, including whether to persist the choice. See SelectDeviceOptions.

Returns

void

Examples

selfParticipant.selectAudioInputDevice(device, options);

selectAudioOutputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectAudioOutputDevice(device, options?): void

Selects the audio output device. Optionally saves as a preference.

Parameters

device

MediaDeviceInfoRequired

Device to select. See MediaDeviceInfo.

options

SelectDeviceOptions

Selection options, including whether to persist the choice. See SelectDeviceOptions.

Returns

void

Examples

selfParticipant.selectAudioOutputDevice(device, options);

setAudioInputDeviceConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioInputDeviceConstraints(constraints): Promise<void>

Updates the audio input track constraints for the active call.

Parameters

constraints

MediaTrackConstraintsRequired

Media-track constraints to apply to the current audio input. See MediaTrackConstraints.

Returns

Promise<void>

Examples

await selfParticipant.setAudioInputDeviceConstraints(constraints);

setAudioInputSensitivity

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioInputSensitivity(value): Promise<void>

This is not a local PC mic gain control; it only changes how the server-side mixer decides to open the mic gate on this participant.

Parameters

value

numberRequired

Sensitivity level as understood by the conference engine (integer, larger values are more sensitive).

Returns

Promise<void>

Inherited from

Participant. setAudioInputSensitivity

Examples

await selfParticipant.setAudioInputSensitivity(value);

setAudioInputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioInputVolume(value): Promise<void>

For local PC mic gain, use Call.setLocalMicrophoneGain instead.

Parameters

value

numberRequired

Volume level (0-100).

Returns

Promise<void>

Inherited from

Participant. setAudioInputVolume

Examples

await selfParticipant.setAudioInputVolume(value);

setAudioOutputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAudioOutputVolume(value): Promise<void>

Sets the server-side speaker volume on this participant’s bridged call leg (FreeSWITCH channel write volume), what this participant hears from the mix before it reaches their client.

For local playback volume (the <audio> element the consumer attaches remoteStream to), set audioElement.volume directly in the consumer’s code.

Parameters

value

numberRequired

Volume level (0-100).

Returns

Promise<void>

Inherited from

Participant. setAudioOutputVolume

Examples

await selfParticipant.setAudioOutputVolume(value);

setInputDevicesConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setInputDevicesConstraints(constraints): Promise<void>

Updates both audio and video input track constraints for the active call.

Parameters

constraints

{ audio: MediaTrackConstraints; video: MediaTrackConstraints; }Required

Constraints for both audio and video input devices. See MediaTrackConstraints.

Returns

Promise<void>

Examples

await selfParticipant.setInputDevicesConstraints(constraints);

setMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMeta(_meta): Promise<void>

Replaces custom metadata for this participant.

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

Metadata object to set.

Returns

Promise<void>

Throws

Throws unconditionally, implementation pending.

Inherited from

Participant. setMeta

Examples

await selfParticipant.setMeta(_meta);

setPosition

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setPosition(value): Promise<void>

Sets the participant’s position in the video layout.

Parameters

value

VideoPositionRequired

The VideoPosition to assign (e.g. 'auto', 'reserved-0').

Returns

Promise<void>

Inherited from

Participant. setPosition

Examples

await selfParticipant.setPosition(value);

startScreenShare

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startScreenShare(): Promise<void>

Starts sharing the local screen.

Returns

Promise<void>

Examples

await selfParticipant.startScreenShare();

See

screenShareStatus$, reactive state.
stopScreenShare, end the share.
Gated by SelfCapabilities.screenshare.

stopScreenShare

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

stopScreenShare(): Promise<void>

Stops the current screen share.

Returns

Promise<void>

Examples

await selfParticipant.stopScreenShare();

See

screenShareStatus$, reactive state.
startScreenShare.

studioAudio$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get studioAudio$(): Observable<boolean>

Observable indicating whether studio audio (raw/unprocessed audio) mode is enabled.

studioAudio

get studioAudio(): boolean

Whether studio audio (raw/unprocessed audio) mode is currently enabled.

Examples

selfParticipant.studioAudio$.subscribe((studioAudio) => {
  console.log('studioAudio:', studioAudio);
});

toggleAudioInputAutoGain

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleAudioInputAutoGain(): Promise<void>

Toggles automatic gain control. Exits studio mode if active.

Returns

Promise<void>

Examples

await selfParticipant.toggleAudioInputAutoGain();

toggleDeaf

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleDeaf(): Promise<void>

Toggles the deafened state (mutes/unmutes incoming audio).

Returns

Promise<void>

Inherited from

Participant. toggleDeaf

Examples

await selfParticipant.toggleDeaf();

toggleEchoCancellation

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleEchoCancellation(): Promise<void>

Toggles echo cancellation. Exits studio mode if active.

Returns

Promise<void>

Examples

await selfParticipant.toggleEchoCancellation();

toggleHandraise

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleHandraise(): Promise<void>

Toggles the hand-raised state.

Returns

Promise<void>

Inherited from

Participant. toggleHandraise

Examples

await selfParticipant.toggleHandraise();

toggleLowbitrate

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleLowbitrate(): Promise<void>

Returns

Promise<void>

Inherited from

Participant. toggleLowbitrate

Examples

await selfParticipant.toggleLowbitrate();

toggleMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleMute(): Promise<void>

Toggles the participant’s audio mute state.

Returns

Promise<void>

Inherited from

Participant. toggleMute

Examples

await selfParticipant.toggleMute();

toggleNoiseSuppression

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleNoiseSuppression(): Promise<void>

Toggles noise suppression. Exits studio mode if active.

Returns

Promise<void>

Examples

await selfParticipant.toggleNoiseSuppression();

type$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get type$(): Observable<string | undefined>

Observable of the participant type (e.g. 'member', 'screen').

Inherited from

Participant. type$

type

get type(): string | undefined

Participant type (e.g. 'member', 'screen').

Inherited from

Participant. type

Examples

selfParticipant.type$.subscribe((type) => {
  console.log('type:', type);
});

unmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

unmute(): Promise<void>

Unmutes local audio. Falls back to local device unmute if the server RPC fails.

Returns

Promise<void>

Examples

await selfParticipant.unmute();

updateMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMeta(_meta): Promise<void>

Merges values into custom metadata (unlike setMeta which replaces).

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

Metadata to merge.

Returns

Promise<void>

Throws

Throws unconditionally, implementation pending.

Inherited from

Participant. updateMeta

Examples

await selfParticipant.updateMeta(_meta);

userId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get userId$(): Observable<string | undefined>

Observable of the participant’s user ID.

Inherited from

Participant. userId$

userId

get userId(): string | undefined

User ID of this participant, or undefined if not available.

Inherited from

Participant. userId

Examples

selfParticipant.userId$.subscribe((userId) => {
  console.log('userId:', userId);
});

visible$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get visible$(): Observable<boolean | undefined>

Observable indicating whether the participant is visible in the layout.

Inherited from

Participant. visible$

visible

get visible(): boolean

Whether the participant is visible in the layout.

Inherited from

Participant. visible

Examples

selfParticipant.visible$.subscribe((visible) => {
  console.log('visible:', visible);
});

SignalWire

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SignalWire is the top-level client for the Browser SDK and the only class applications instantiate directly. A single instance owns the WebSocket transport, the authenticated session, the local media-device controller, and the call factory used by dial. Every other entity in the SDK, WebRTCCall, User, Address, is produced or fetched through it.

Lifecycle: construct with a CredentialProvider, then await connection-readiness via ready$ or connect before placing or receiving calls. Calls to register opt the user into inbound calls; unregister reverses it. destroy tears down all transports, timers, and subscriptions, hold a reference to the client for the lifetime of your app and call destroy() exactly once on tear-down.

Device management methods (enable*, disable*, select*, applySelected*) operate on a shared device pool surfaced through observable accessors (audioInputDevices$, selectedVideoInputDevice$, etc.). Selections are persisted via the configured StorageManager when ClientPreferences.enableSavePreferences is set. Most state is exposed in two forms, a snapshot getter and an observable ($) for reactive UI binding.

Examples

const client = new SignalWire(new StaticCredentialProvider({ token: 'YOUR_TOKEN' }));
await client.connect();
await client.register();
client.errors$.subscribe(err => console.error(err));
const call = await client.dial('/public/my-room', { audio: true, video: true });

Extends

Destroyable

Implements

DeviceController

Constructors

Constructor

new SignalWire(credentialProvider, options?): SignalWire

Creates a new SignalWire client and begins connecting.

Parameters

credentialProvider

CredentialProvider | undefinedRequired

Provider that supplies authentication credentials. See CredentialProvider.

options

SignalWireOptions

Configuration options (connection, device monitoring, preferences). See SignalWireOptions.

Properties

preferences

ClientPreferencesRequired

Global SDK preferences (timeouts, ICE config, media defaults).

Accessors

audioInputDevices$\ \ Observable list of available audio input (microphone) devices. audioInputDisabled$\ \ Observable that emits true when audio input is disabled (receive-only). audioOutputDevices$\ \ Observable list of available audio output (speaker) devices. destroyed$\ \ Observable that emits when the instance is destroyed deviceRecovered$\ \ Observable that emits when the SDK auto-switches a device. directory$\ \ Observable that emits the Directory instance once the client is connected, or undefined while disconnected. errors$\ \ Observable stream of errors from transport, authentication, and devices. isConnected$\ \ Observable that emits when the connection state changes. isRegistered$\ \ Observable that emits when the user registration state changes. platformCapabilities\ \ Platform WebRTC capabilities detected at construction time. ready$\ \ Observable that emits true when the client is both connected and authenticated. selectedAudioInputDevice$\ \ Observable of the currently selected audio input device. selectedAudioInputDeviceConstraints\ \ Media track constraints for the selected audio input device. Returns false when disabled. selectedAudioOutputDevice$\ \ Observable of the currently selected audio output device. selectedVideoInputDevice$\ \ Observable of the currently selected video input device. selectedVideoInputDeviceConstraints\ \ Media track constraints for the selected video input device. Returns false when disabled. session\ \ The underlying client session for advanced RPC operations. user$\ \ Observable that emits the User profile once fetched, or undefined before authentication completes. videoInputDevices$\ \ Observable list of available video input (camera) devices. videoInputDisabled$\ \ Observable that emits true when video input is disabled (receive-only). warnings$\ \ Observable stream of non-fatal SDK warnings (e.g. credential refresh fallback).

Methods

applySelectedAudioOutputDevice\ \ Apply the currently selected audio output device to an HTMLMediaElement (e.g. clearDeviceState\ \ Clears all device state and re-enumerates. connect\ \ Establishes the WebSocket connection and authenticates the session. destroy\ \ Destroys the client, clearing timers and releasing all resources. deviceInfoToConstraints\ \ Converts a MediaDeviceInfo to track constraints suitable for getUserMedia. dial\ \ Places an outbound call to the given destination. disableAudioInput\ \ Disables audio input (receive-only mode). No audio track will be acquired. disableDeviceMonitoring\ \ Stops monitoring for media device changes. disableVideoInput\ \ Disables video input (receive-only mode). No video track will be acquired. disconnect\ \ Disconnects the WebSocket and tears down the current session. enableAudioInput\ \ Re-enables audio input, restoring the last selection or auto-selecting. enableDeviceMonitoring\ \ Starts monitoring for media device changes (connect/disconnect). enableVideoInput\ \ Re-enables video input, restoring the last selection or auto-selecting. enumerateDevices\ \ Forces a device re-enumeration. exportDiagnostics\ \ Export a structured diagnostic bundle for support/debugging. Includes connection events, call summaries, and device changes. getDeviceCapabilities\ \ Returns the capabilities of a media device. isValidDevice\ \ Checks whether a device is still available and usable. preflight\ \ Runs a multi-phase connectivity test against the given destination. register\ \ Registers the user as online to receive inbound calls and events. requestMediaPermissions\ \ Triggers the browser’s media permission dialog and captures the user’s device selections. resetToDefaults\ \ Clears all SDK-persisted state and resets to defaults. selectAudioInputDevice\ \ Sets the preferred audio input device. selectAudioOutputDevice\ \ Sets the preferred audio output device. selectVideoInputDevice\ \ Sets the preferred video input device. setStorageManager\ \ Injects a storage manager into the device controller for persistence. unregister\ \ Unregisters the user, going offline for inbound calls.

applySelectedAudioOutputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

applySelectedAudioOutputDevice(element): Promise<boolean>

Apply the currently selected audio output device to an HTMLMediaElement (e.g. the <audio> or <video> element the consumer attached the remote stream to). Uses HTMLMediaElement.setSinkId under the hood. Returns a Promise<boolean>: true if the sink was applied, false if the browser doesn’t support setSinkId or no device is selected.

Parameters

element

HTMLMediaElementRequired

HTML media element to route audio output to.

Returns

Promise<boolean>

Examples

audioEl.srcObject = call.remoteStream;
await client.applySelectedAudioOutputDevice(audioEl);

audioInputDevices$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get audioInputDevices$(): Observable<MediaDeviceInfo[]>

Observable list of available audio input (microphone) devices.

audioInputDevices

get audioInputDevices(): MediaDeviceInfo[]

Current snapshot of available audio input devices.

Examples

client.audioInputDevices$.subscribe((audioInputDevices) => {
  console.log('audioInputDevices:', audioInputDevices);
});

audioInputDisabled$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get audioInputDisabled$(): Observable<boolean>

Observable that emits true when audio input is disabled (receive-only).

audioInputDisabled

get audioInputDisabled(): boolean

Whether audio input is currently disabled.

Examples

client.audioInputDisabled$.subscribe((audioInputDisabled) => {
  console.log('audioInputDisabled:', audioInputDisabled);
});

audioOutputDevices$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get audioOutputDevices$(): Observable<MediaDeviceInfo[]>

Observable list of available audio output (speaker) devices.

audioOutputDevices

get audioOutputDevices(): MediaDeviceInfo[]

Current snapshot of available audio output devices.

Examples

client.audioOutputDevices$.subscribe((audioOutputDevices) => {
  console.log('audioOutputDevices:', audioOutputDevices);
});

clearDeviceState

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

clearDeviceState(): Promise<void>

Clears all device state and re-enumerates.

Returns

Promise<void>

Examples

await client.clearDeviceState();

connect

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

connect(): Promise<void>

Establishes the WebSocket connection and authenticates the session.

Reconnection behavior

After a successful connection the underlying WebSocketController automatically attempts to reconnect whenever the socket closes unexpectedly (e.g. network change, server restart). Reconnection uses an exponential back-off strategy:

First retry after reconnectDelayMin (default 0.1 s).
Each subsequent retry doubles the delay up to reconnectDelayMax (default 3 s).
The delay resets to reconnectDelayMin once a connection succeeds.
A per-attempt connectionTimeout (default 10 s) aborts the attempt and schedules the next retry if the server does not respond.

Calling disconnect stops the reconnection loop entirely.

Message handling during temporary disconnections

While the socket is not in the connected state, outgoing messagesare queued in an internal buffer. Once the connection is re-established the queue is flushed in order so no outgoing RPC call is lost.

Incoming server-to-client messages that arrive while the socket is down are not buffered by the SDK, they are expected to be re-delivered by the server after the session is re-authenticated. Active RPC calls that were awaiting a response will time out (default 5 s) and reject with an RPCTimeoutError; callers should handle this and retry if appropriate.

The connection status can be observed via the status$ observable on the transport layer, which emits 'connecting', 'connected', 'reconnecting', 'disconnecting', or 'disconnected'.

Returns

Promise<void>

Examples

await client.connect();

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Destroys the client, clearing timers and releasing all resources.

Returns

void

Examples

client.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Destroyable.destroyed$

Examples

client.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

deviceInfoToConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

deviceInfoToConstraints(deviceInfo): MediaTrackConstraints

Converts a MediaDeviceInfo to track constraints suitable for getUserMedia.

Parameters

deviceInfo

MediaDeviceInfo | nullRequired

Device descriptor to convert, or null for unconstrained capture. See MediaDeviceInfo.

Returns

MediaTrackConstraints

Examples

client.deviceInfoToConstraints(deviceInfo);

deviceRecovered$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get deviceRecovered$(): Observable<DeviceRecoveryEvent>

Observable that emits when the SDK auto-switches a device.

Observable that emits when the SDK auto-switches a device due to disconnect, reconnect, or recovery.

Examples

client.deviceRecovered$.subscribe((deviceRecovered) => {
  console.log('deviceRecovered:', deviceRecovered);
});

dial

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

dial(destination, options?): Promise<Call>

Places an outbound call to the given destination.

Waits for authentication before dialing. Media options are merged from saved preferences, destination query parameters (e.g. ?channel=video), and the provided options (highest priority).

Returns a Call in 'ringing' state. Subscribe to Call.status$ to track progression through 'connected' → 'disconnected'.

Parameters

destination

string | AddressRequired

Address URI string (e.g. '/public/my-room') or Address instance.

options

DialOptions

Media and dial options (audio/video, device constraints). Overrides defaults. See DialOptions.

Returns

Promise<Call>

The created Call instance.

Throws

If authentication is not complete or call creation fails.

Examples

const call = await client.dial('/public/conference', {
  audio: true,
  video: true,
});
call.status$.subscribe(status => console.log('Call:', status));

directory$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get directory$(): Observable<Directory | undefined>

Observable that emits the Directory instance once the client is connected, or undefined while disconnected. Subscribe to this to safely wait for the directory to become available without risking an error.

Examples

client.directory$.subscribe(dir => {
  if (dir) dir.addresses$.subscribe(console.log);
});

disableAudioInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disableAudioInput(): void

Disables audio input (receive-only mode). No audio track will be acquired.

Returns

void

Examples

client.disableAudioInput();

disableDeviceMonitoring

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disableDeviceMonitoring(): void

Stops monitoring for media device changes.

Examples

client.disableDeviceMonitoring();

disconnect

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disconnect(): Promise<void>

Disconnects the WebSocket and tears down the current session.

The client can be reconnected by calling connect again, which creates a fresh transport and session.

Examples

await client.disconnect();

enableAudioInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enableAudioInput(): void

Re-enables audio input, restoring the last selection or auto-selecting.

Examples

client.enableAudioInput();

enableDeviceMonitoring

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enableDeviceMonitoring(): void

Starts monitoring for media device changes (connect/disconnect).

Examples

client.enableDeviceMonitoring();

enumerateDevices

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enumerateDevices(): Promise<void>

Forces a device re-enumeration.

Examples

await client.enumerateDevices();

errors$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get errors$(): Observable<Error>

Observable stream of errors from transport, authentication, and devices.

Examples

client.errors$.subscribe((errors) => {
  console.log('errors:', errors);
});

exportDiagnostics

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

exportDiagnostics(): SessionDiagnostics

Snapshots the client’s accumulated diagnostic data into a single serializable bundle, connection events, recent call summaries, and device-change history, for inclusion in support tickets or local debug exports.

The returned object is a plain JSON-serializable structure; safe to JSON.stringify and ship to a support endpoint.

Returns

SessionDiagnostics, a structured snapshot containing connection events, call summaries, and device change history at the moment of the call.

Examples

Download the diagnostics bundle

const diag = client.exportDiagnostics();
const blob = new Blob([JSON.stringify(diag, null, 2)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
Object.assign(document.createElement('a'), { href: url, download: 'signalwire-diag.json' }).click();
URL.revokeObjectURL(url);

Attach diagnostics to a support form

supportForm.addEventListener('submit', async (e) => {
  e.preventDefault();
  await fetch('/api/support', {
    method: 'POST',
    body: JSON.stringify({
      message: messageInput.value,
      diagnostics: client.exportDiagnostics(),
    }),
  });
});

getDeviceCapabilities

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getDeviceCapabilities(deviceInfo): Promise<MediaTrackCapabilities | null>

Returns the capabilities of a media device.

Parameters

deviceInfo

MediaDeviceInfoRequired

The device to query. See MediaDeviceInfo.

Returns

Promise<MediaTrackCapabilities | null>

The device capabilities, or null if unavailable.

Examples

await client.getDeviceCapabilities(deviceInfo);

isConnected$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isConnected$(): Observable<boolean>

Observable that emits when the connection state changes.

isConnected

get isConnected(): boolean

Whether the client is currently connected.

Examples

client.isConnected$.subscribe((isConnected) => {
  console.log('isConnected:', isConnected);
});

isRegistered$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isRegistered$(): Observable<boolean>

Observable that emits when the user registration state changes.

isRegistered

get isRegistered(): boolean

Whether the user is currently registered.

Examples

client.isRegistered$.subscribe((isRegistered) => {
  console.log('isRegistered:', isRegistered);
});

isValidDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

isValidDevice(deviceInfo): Promise<boolean>

Checks whether a device is still available and usable.

Parameters

deviceInfo

MediaDeviceInfo | null

The device to validate, or null. See MediaDeviceInfo.

Returns

Promise<boolean>

true if the device is valid and available. Returns false for null, audio output devices, or unavailable devices.

Examples

await client.isValidDevice(deviceInfo);

platformCapabilities

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get platformCapabilities(): PlatformCapabilities

Platform WebRTC capabilities detected at construction time.

Examples

console.log(client.platformCapabilities);

preflight

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

preflight(destination, options?): Promise<PreflightResult>

Runs a multi-phase connectivity test against the given destination.

The test checks:

Signaling, WebSocket connected, RTT measurement
Devices, getUserMedia succeeds with selected (or specified) devices
ICE/TURN, gathers ICE candidates to verify STUN/TURN reachability
Media/bandwidth (unless skipMediaTest), dials the destination, collects getStats() for duration seconds, computes bandwidth estimates

Parameters

destination

stringRequired

A destination to dial for the media test (e.g. '/private/network-test').

options

PreflightOptions

Preflight options (duration, skipMediaTest, device overrides). See PreflightOptions.

Returns

Promise<PreflightResult>

A PreflightResult describing connectivity health.

Examples

const result = await client.preflight('/private/network-test', { duration: 5 });
if (!result.ok) console.warn('Connectivity issues:', result.warnings);

ready$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get ready$(): Observable<boolean>

Observable that emits true when the client is both connected and authenticated.

Examples

client.ready$.subscribe((ready) => {
  console.log('ready:', ready);
});

register

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

register(): Promise<void>

Registers the user as online to receive inbound calls and events.

Waits for authentication to complete before sending the registration. If the initial attempt fails, reauthentication is attempted automatically.

After register() resolves, inbound calls addressed to this user surface through session.incomingCalls$. Call unregister to stop receiving calls without disconnecting the client.

Returns

Promise<void>

Throws

If registration and reauthentication both fail.

Examples

Register and watch for inbound calls

await client.register();

client.session.incomingCalls$.subscribe((calls) => {
  const ringing = calls.find((c) => c.status === 'ringing');
  if (ringing) {
    ringing.answer({ audio: true, video: true });
  }
});

Track registration state reactively

client.isRegistered$.subscribe((registered) => {
  console.log('registered:', registered);
});

See

session, exposes incomingCalls$.
unregister, reverse this.
isRegistered$, reactive state.
Inbound Calls guide.

requestMediaPermissions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

requestMediaPermissions(options?): Promise<PermissionResult>

Triggers the browser’s media permission dialog and captures the user’s device selections.

Parameters

options

{ audio?: boolean; video?: boolean; }

Which permissions to request.

Returns

Promise<PermissionResult>

The permission result with selected devices.

Examples

await client.requestMediaPermissions(options);

resetToDefaults

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

resetToDefaults(): Promise<void>

Clears all SDK-persisted state and resets to defaults.

This clears device preferences, device history, authorization state, attached call IDs, and all SDK storage keys, then re-enumerates devices.

Returns

Promise<void>

Examples

await client.resetToDefaults();

selectAudioInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectAudioInputDevice(device): void

Sets the preferred audio input device.

Parameters

device

MediaDeviceInfo | nullRequired

Device to select. Pass null to clear the current selection. See MediaDeviceInfo.

Returns

void

Examples

client.selectAudioInputDevice(device);

See

audioInputDevices$, list of available microphones.
selectedAudioInputDevice$, reactive state of the currently selected device.
deviceRecovered$, emits when the SDK auto-switches on hardware change.

selectAudioOutputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectAudioOutputDevice(device): void

Sets the preferred audio output device.

Parameters

device

MediaDeviceInfo | nullRequired

Device to select. Pass null to clear the current selection. See MediaDeviceInfo.

Returns

void

Examples

client.selectAudioOutputDevice(device);

See

audioOutputDevices$, list of available speakers.
selectedAudioOutputDevice$, reactive state.
Routing via setSinkId requires browser support (Chromium yes, Firefox no).

selectedAudioInputDevice$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selectedAudioInputDevice$(): Observable<MediaDeviceInfo | null>

Observable of the currently selected audio input device.

selectedAudioInputDevice

get selectedAudioInputDevice(): MediaDeviceInfo | null

Currently selected audio input device, or null if none.

Examples

client.selectedAudioInputDevice$.subscribe((selectedAudioInputDevice) => {
  console.log('selectedAudioInputDevice:', selectedAudioInputDevice);
});

selectedAudioInputDeviceConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selectedAudioInputDeviceConstraints(): boolean | MediaTrackConstraints

Media track constraints for the selected audio input device. Returns false when disabled.

Examples

console.log(client.selectedAudioInputDeviceConstraints);

selectedAudioOutputDevice$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selectedAudioOutputDevice$(): Observable<MediaDeviceInfo | null>

Observable of the currently selected audio output device.

selectedAudioOutputDevice

get selectedAudioOutputDevice(): MediaDeviceInfo | null

Currently selected audio output device, or null if none.

Examples

client.selectedAudioOutputDevice$.subscribe((selectedAudioOutputDevice) => {
  console.log('selectedAudioOutputDevice:', selectedAudioOutputDevice);
});

session

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get session(): ClientSessionWrapper

The active client session. Exposes the SessionState surface, including the lists of active and inbound calls, once the client is connected and authenticated.

This is the entry point for inbound calls: subscribe to session.incomingCalls$ after calling register() to receive notification of ringing calls.

Examples

Inbound calls

await client.register();

client.session.incomingCalls$.subscribe((calls) => {
  const ringing = calls.find((c) => c.status === 'ringing');
  if (ringing) {
    ringing.answer({ audio: true, video: true });
  }
});

Reattached calls after page reload

const existing = client.session.calls;
if (existing.length > 0) {
  const call = existing[0];
  // re-bind call.status$, call.remoteStream$, etc. to your UI
}

See

SessionState, full interface, including calls$, incomingCalls$, authenticated$.
register, must be called before inbound calls route to this session.
Inbound Calls guide, end-to-end accept/reject flow.

setStorageManager

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setStorageManager(storageManager): void

Injects a storage manager into the device controller for persistence.

Parameters

storageManager

StorageManagerRequired

Storage manager implementation used to persist device and session state.

Returns

void

Examples

client.setStorageManager(storageManager);

unregister

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

unregister(): Promise<void>

Unregisters the user, going offline for inbound calls.

The WebSocket connection remains open; use disconnect to fully close it.

Returns

Promise<void>

Examples

await client.unregister();

user$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get user$(): Observable<User | undefined>

Observable that emits the User profile once fetched, or undefined before authentication completes.

Examples

client.user$.subscribe(u => {
  if (u) console.log('Logged in as', u.email);
});

user

get user(): User | undefined

Current user snapshot, or undefined if not yet authenticated.

warnings$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get warnings$(): Observable<SDKWarning>

Observable stream of non-fatal SDK warnings.

Subscribe to detect SDK behaviors that affect session liveness or developer-facing contracts but do not warrant disconnection, for example, a fallback from Client Bound SAT refresh to the developer-provided refresh() because the SAT lacks sat:refresh scope. Each warning is discriminated by its code. See SDKWarning.

Independent from errors$: existing error consumers are not notified, so reacting to a warning does not trigger error-handling code paths (disconnect cascades, user-facing toasts).

Examples

client.warnings$.subscribe((warning) => {
  switch (warning.code) {
    case 'credential_refresh_fallback':
      console.warn('Fell back to developer refresh:', warning.reason);
      break;
    case 'credential_no_refresh_handler':
      console.warn('Session will end at', new Date(warning.expiresAt));
      break;
  }
});

CallDirection

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type CallDirection = "inbound" | "outbound"

Whether the call is inbound (received) or outbound (initiated).

CallErrorKind

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type CallErrorKind = "media" | "signaling" | "timeout" | "rejected" | "network" | "internal"

Semantic category of a call-lifecycle error.

'media' - RTCPeerConnection / media device failure
'signaling' - Verto / JSON-RPC protocol error
'timeout' - Call setup timed out waiting for a response
'rejected' - Remote side rejected the call
'network' - Transport lost during an active call
'internal' - Unexpected / unknown error

CallStatus

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type CallStatus = "new" | "trying" | "ringing" | "connecting" | "connected" | "recovering" | "disconnecting" | "disconnected" | "failed" | "destroyed"

Lifecycle status of a call.

Capability

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type Capability = "self" | "self.mute" | "self.mute.audio" | "self.mute.audio.on" | "self.mute.audio.off" | "self.mute.video" | "self.mute.video.on" | "self.mute.video.off" | "self.deaf" | "self.deaf.on" | "self.deaf.off" | "self.microphone" | "self.microphone.volume.set" | "self.microphone.sensitivity.set" | "self.speaker" | "self.speaker.volume.set" | "self.position.set" | "self.meta" | "self.audioflags.set" | "member" | "member.mute" | "member.mute.audio" | "member.mute.audio.on" | "member.mute.audio.off" | "member.mute.video" | "member.mute.video.on" | "member.mute.video.off" | "member.deaf" | "member.deaf.on" | "member.deaf.off" | "member.microphone" | "member.microphone.volume.set" | "member.microphone.sensitivity.set" | "member.speaker" | "member.speaker.volume.set" | "member.position.set" | "member.meta" | "member.audioflags.set" | "layout" | "layout.set" | "digit" | "digit.send" | "vmuted" | "vmuted.hide" | "vmuted.hide.on" | "vmuted.hide.off" | "lock" | "lock.on" | "lock.off" | "device" | "screenshare" | "end"

Feature capability string that controls what actions a participant can perform.

Capabilities are organized into categories:

self.*, Actions the local participant can perform on themselves (mute, deaf, volume, position, meta).
member.*, Actions that can be performed on other participants.
layout.*, Layout management for the video canvas.
digit.*, DTMF digit sending.
vmuted.*, Visibility control for muted video participants.
lock.*, Room lock/unlock control.
device / screenshare, Device and screen share capabilities.
end, Permission to end the call or room.

CredentialRefreshFallbackReason

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type CredentialRefreshFallbackReason =
  | "no-scope"
  | "no-dpop-support"
  | "endpoint-failed"
  | "activation-timeout"
  | (string & {})

Diagnostic detail for CredentialRefreshFallbackWarning.

Stable values, but treat unknown strings as “fell back for an unspecified cause”, do not branch on this value for control flow. New values may be added in future releases.

'no-scope' - The minted SAT lacks sat:refresh scope
'no-dpop-support' - The platform does not support DPoP key binding
'endpoint-failed' - The /devices/token exchange failed transiently (see DeviceTokenError)
'activation-timeout' - Device-token activation did not resolve in time

ExecuteMethod

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type ExecuteMethod = <T>(target, method, args) => Promise<T>

Callback type for executing call methods Injected to avoid circular dependency with Call class

Type Parameters

Type Parameter	Default type
`T` extends `JSONRPCResponse`	`JSONRPCResponse`

Parameters

Parameter	Type
`target`	`string` \| `MemberTarget`
`method`	`string`
`args`	`Record`<`string`, `unknown`>

Returns

Promise<T>

JSONRPCResponse<TResult>

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type JSONRPCResponse<TResult> = JSONRPCSuccessResponse<TResult> | JSONRPCErrorResponse

Type Parameters

Type Parameter	Default type
`TResult`	`unknown`

LogLevel

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent"

Log level names supported by the SDK.

MediaDirection

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type MediaDirection = RTCRtpTransceiverDirection

WebRTC transceiver direction for a single media kind.

QualityLevel

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type QualityLevel = "excellent" | "good" | "fair" | "poor" | "critical"

Simplified quality level for UI indicators, derived from MOS score.

RecoveryState

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type RecoveryState = "idle" | "debouncing" | "recovering" | "cooldown"

State of the recovery pipeline state machine (Section 19.7).

ResilienceCallStatus

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type ResilienceCallStatus = "new" | "trying" | "ringing" | "connecting" | "connected" | "recovering" | "disconnecting" | "disconnected" | "failed" | "destroyed"

Extended call status that includes the ‘recovering’ state.

Used when the SDK is attempting to recover a call after a network disruption or media failure.

ScreenShareStatus

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type ScreenShareStatus = "none" | "starting" | "started" | "stopping"

SDKWarning

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type SDKWarning = CredentialRefreshFallbackWarning | CredentialNoRefreshHandlerWarning

Non-fatal warning emitted via client.warnings$.

Use to detect SDK behaviors that affect session liveness or developer-facing contracts but do not warrant disconnection. Discriminated by code.

Existing consumers of errors$ are NOT notified, warnings$ is a separate channel so application code can react to warnings without triggering error-handling code paths (e.g., disconnect cascades, user-facing toasts).

CredentialRefreshFallbackWarning, code: 'credential_refresh_fallback'
CredentialNoRefreshHandlerWarning, code: 'credential_no_refresh_handler'

UserPresence

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type UserPresence = "online" | "offline" | "busy"

User online presence state.

WebSocketAdapter

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type WebSocketAdapter = (url, protocols?) => WebSocketClient

Browser-compatible WebSocket constructor type.

Parameters

Parameter	Type
`url`	`string` \| `URL`
`protocols?`	`string` \| `string`[]

Returns

WebSocketClient

User

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

User is the authenticated user’s profile as returned by the SignalWire fabric. A single instance is created and populated automatically when a SignalWire client connects and the SAT is validated; applications retrieve it via client.user$.

The class exposes the user’s identity (id, email, displayName, name fields), organizational metadata (companyName, country, region, timeZone, jobTitle), and the fabric addresses available for dialing. appSettings carries the display name advertised to other participants and the OAuth-style scopes granted to the current session; satClaims exposes any extended capability claims encoded in the token (e.g. a refresh scope). pushNotificationKey is used by mobile and web-push integrations to register the user for inbound-call notifications.

User extends Fetchable, meaning the profile is populated lazily and fetched$ emits true once the initial fetch completes. There are no mutating methods on this class: the profile is read-only from the SDK’s perspective.

Extends

Fetchable<GetUserInfoResponse>

Constructors

Constructor

new User(http): User

Parameters

Inherited from Fetchable

fetched$

Observable<boolean>Required

Observable that emits true once the user profile has been fetched.

fromPath

stringRequired

Origin path or URI captured at construction time, used for routing inbound calls.

Accessors

destroyed$\ \ Observable that emits when the instance is destroyed

Methods

destroy\ \ Cleans up subscriptions and subjects owned by this instance.

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Returns

void

Inherited from

Fetchable.destroy

Examples

user.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Fetchable.destroyed$

Examples

user.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

Overview

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Browser SDK Web Components

Fresh

The Browser SDK contains a suite of flexible web components that can be used to create UI.

Install

npm\ \ @signalwire/web-components

npm install @signalwire/web-components@latest

Or load from a CDN:

<script type="module" src="https://unpkg.com/@signalwire/web-components"></script>

Components

Ready-to-use call UI elements. Most components consume context from a parent <sw-call-provider> (or <sw-call-media>) automatically.

Component	Description
`<sw-audio-level>`	Real-time audio level visualizer, animated bar graph
`<sw-call-controls>`	Mute audio, mute video, screen share, and hangup buttons
`<sw-call-dialpad>`	Context-aware DTMF dialpad, sends tones to the active call or bubbles a `sw-dial` event
`<sw-call-media>`	Remote video container and root context provider, wrap call components inside it
`<sw-call-provider>`	Top-level context provider that bridges an external `Call` and `DeviceController` into Lit context
`<sw-call-status>`	Displays call state label and elapsed duration timer
`<sw-call-widget>`	All-in-one call widget, handles client init, dialing, media, controls, and optional AI transcript
`<sw-click-to-call>`	Single-button widget that dials on click and shows mute/hangup once connected
`<sw-device-selector>`	Drop-up buttons for microphone, camera, and speaker selection with optional live preview
`<sw-directory>`	Searchable contact list with dial actions from the SDK directory
`<sw-local-camera>`	Local camera preview with a muted overlay
`<sw-participant-controls>`	Per-participant moderation controls: mute, video mute, remove, volume, pin
`<sw-participants>`	Renders positioned overlays for each remote participant
`<sw-self-media>`	Local video preview, consumes `callContext` from a parent `<sw-call-media>`

UI Primitives

Low-level layout and control components used to build custom interfaces. These are presentational and do not couple to the SDK.

Component	Description
`<sw-ui-alert>`	Confirm / alert dialog primitive, use directly or via the `showPrompt()` helper
`<sw-ui-background>`	Decorative full-bleed background that crossfades from a blurred thumbnail to a hi-res image
`<sw-ui-call-layout>`	Fluid call layout, splits into video + transcript based on container aspect ratio
`<sw-ui-content-drawer>`	Slide-in drawer for agent-pushed content (markdown, HTML, snippets) mid-call
`<sw-ui-control-bar>`	Call controls bar: mic, camera, speaker, screen share, hand raise, transcript, fullscreen, hang-up
`<sw-ui-dialpad>`	Presentational 12-key DTMF keypad, pure UI, no SDK coupling
`<sw-ui-dropup>`	Tiny pop-up menu that opens above its anchor and closes on outside click
`<sw-ui-icon>`	Inline SVG icon component backed by the bundled icon set
`<sw-ui-modal>`	Native `<dialog>` wrapper with bounce-in/out animations and body scroll lock
`<sw-ui-responsive-container>`	Aspect-ratio-aware sizing wrapper for hosting call surfaces inside a modal
`<sw-ui-split-button>`	Pill-shaped icon button with optional chevron dropdown, atomic block for control bars
`<sw-ui-transcript-view>`	Chat-bubble timeline rendering AI transcript entries with rich `meta` payloads

sw-audio-level

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Real-time audio-level meter rendered as a row (or column) of bars.

<sw-audio-level></sw-audio-level>

Pipes a MediaStream through the Web Audio API (AnalyserNode, fftSize=256, smoothingTimeConstant=0.8) and updates an animation loop once per frame. Each bar represents an averaged frequency band; bar height (vertical) or width (horizontal) is proportional to the average magnitude. Color thresholds:

level > 0.05 → bar becomes “active” (--interactive-status-success)
level > 0.40 → yellow (--interactive-status-warning)
level > 0.70 → red (--interactive-button-destructive-bg)

The component handles AudioContext / source / analyser teardown automatically on disconnect, when the source changes, and when releaseResources() is invoked. Always call releaseResources() before stopping the underlying MediaStream tracks if you want a clean, synchronous teardown, used by <sw-device-selector>.

If the supplied stream has no audio tracks, the component logs a warning and renders an empty meter.

Input precedence (most specific wins): .stream > .call (uses localStream) > context (uses localStream from callStateContext).

Class: SwAudioLevel · Module: packages/web-components/src/components/sw-audio-level.ts

class: `SwAudioLevel`, `sw-audio-level`

Fields

stream

MediaStream | undefined

Explicit MediaStream to analyze, highest precedence.

call

Call | undefined

Explicit Call, when set, analyzes the call’s localStream. Bypassed by .stream if both are set.

bars

numberDefaults to 5

Number of bars to display (default: 5)

orientation

'vertical' | 'horizontal'Defaults to 'vertical'

Orientation of the bars: ‘vertical’ or ‘horizontal’

autoRequest

booleanDefaults to false

When true, automatically calls getUserMedia({ audio: true }) to acquire a microphone stream instead of requiring the consumer to set .stream.

maxSize

numberDefaults to 32

Maximum height/width of bars in pixels

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
`releaseResources`	public	Public method to release all audio resources immediately<br>Call this before stopping the MediaStream tracks to ensure proper cleanup		`void`

Attributes

Name	Field	Inherited From
`stream`	stream
`call`	call
`bars`	bars
`orientation`	orientation
`auto-request`	autoRequest
`maxSize`	maxSize

CSS Properties

Name	Default	Description
`--interactive-status-success`	`#22c55e`	Color for low audio levels.
`--interactive-status-warning`	`#ffd700`	Color for medium audio levels.
`--interactive-button-destructive-bg`	`#dc2626`	Color for high audio levels.
`--sw-audio-bar-width`	`4px`	Width of each vertical bar (height when horizontal).
`--sw-audio-bar-gap`	`2px`	Gap between audio level bars.
`--sw-audio-bar-radius`	`2px`	Border radius of each bar.
`--sw-audio-bar-background`	`rgba(255,255,255,0.2)`	Background color of inactive bars.

CSS Parts

Name	Description
`container`	The flex container holding all bars. Style for layout, padding, or background.
`bar`	Every individual bar element.
`bar-active`	Applied additionally when the bar is above the activity threshold (~5% of full scale). Lets you style silent vs. active bars differently.

sw-call-controls

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Reactive call-control bar that bridges device + call-state context to the presentational <sw-ui-control-bar> primitive.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-controls></sw-call-controls>
</sw-call-provider>

sw-call-controls is the SDK-aware sibling of <sw-ui-control-bar>: it subscribes to devicesContext for mic / camera / speaker state and to callStateContext for self-participant capabilities (screenshare, handraise, end, …) and then forwards the user’s intent to the underlying Call and DeviceController.

Input precedence (most specific wins): .call > context. When .call is set, screen-share / hand-raise / hang-up are driven directly off the call. Mic / camera / speaker toggles always require devicesContext; without it, those buttons render in their default (unbound) state.

Buttons are auto-hidden when the corresponding capability is absent from callState.capabilities (e.g. screenshare, handraise, end). Every event from <sw-ui-control-bar> bubbles through, so parents can still listen to sw-mic-toggle, sw-camera-toggle, sw-device-change, etc., without re-handling them here.

Class: SwCallControls · Module: packages/web-components/src/components/sw-call-controls.ts

class: `SwCallControls`, `sw-call-controls`

showSettings field.

showFullscreen

booleanDefaults to true

showFullscreen field.

Attributes

Name	Field	Inherited From
`show-screen-share`	showScreenShare
`show-hand-raise`	showHandRaise
`show-transcript`	showTranscript
`transcript-active`	transcriptActive
`show-settings`	showSettings
`show-fullscreen`	showFullscreen
`call`	call

Events

Name	Detail	Description
`sw-call-hangup`	,	Re-dispatched after the user clicks hang-up so
`sw-camera-toggle`	`{ muted: boolean }`	Bubbled from `<sw-ui-control-bar>`
`sw-device-change`	`{ kind: 'mic'	'camera'
`sw-fullscreen-toggle`	`{ fullscreen: boolean }`	Bubbled
`sw-hand-raise-toggle`	`{ raised: boolean }`	Bubbled
`sw-mic-toggle`	`{ muted: boolean }`	Bubbled from `<sw-ui-control-bar>`
`sw-screen-share-toggle`	`{ active: boolean }`	Bubbled
`sw-settings-change`	`{ settingId: string }`	Bubbled
`sw-speaker-toggle`	`{ muted: boolean }`	Bubbled from `<sw-ui-control-bar>`
`sw-transcript-toggle`	,	Bubbled when the transcript button is clicked. No detail.

sw-call-dialpad

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Context-aware DTMF dialpad, sends tones over the active call when one exists, otherwise bubbles a sw-dial event for the parent to act on (e.g. as a “start a call to these digits” signal).

<sw-call-dialpad></sw-call-dialpad>

Wraps the presentational <sw-ui-dialpad> primitive and connects it to the active call. When callState.status === 'connected' (or the explicit .call is connected), each digit press is forwarded to call.sendDigits(). When no call is active, sw-dial bubbles up unchanged so a parent can interpret it as “the user wants to start a new call to these digits”.

Use show-call-button to render an inline “Call” button beneath the keypad, and allow-text to permit free-text entry in the display field, useful for vanity numbers, SIP URIs, or destination addresses.

Input precedence (most specific wins): .call > context.

Class: SwCallDialpad · Module: packages/web-components/src/components/sw-call-dialpad.ts

class: `SwCallDialpad`, `sw-call-dialpad`

Fields

call

Call | undefined

Explicit Call, when set, drives DTMF directly and bypasses context.

showCallButton

booleanDefaults to false

Whether to display the call button below the keypad.

allowText

booleanDefaults to false

Allow free-text input in the display field (e.g., SIP URIs, vanity letters).

placeholder

stringDefaults to 'Enter number'

Placeholder text shown in the digit display input.

Attributes

Name	Field	Inherited From
`show-call-button`	showCallButton
`allow-text`	allowText
`call`	call
`placeholder`	placeholder

CSS Parts

Name	Description
`container`	Forwarded `<sw-ui-dialpad>` outer container.
`display`	Forwarded display / input field.
`keypad`	Forwarded grid of digit keys.
`key`	Forwarded individual digit button.
`key-pressed`	Forwarded digit button while pressed.
`call-button`	Forwarded “Call” button (only when `show-call-button`).

Events

Name	Detail	Description
`sw-dial`	,	User pressed the call button while no call is connected.
`sw-digit-press`	,	A digit was pressed. While the call is connected

sw-call-media

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Renders the remote MCU video stream with aspect-ratio-aware sizing, plus a default slot positioned as an overlay layer on top of the video.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-media>
    <sw-self-media></sw-self-media>
    <sw-participants></sw-participants>
  </sw-call-media>
</sw-call-provider>

sw-call-media is the visual canvas of the call. It binds to a remote MediaStream (provided directly via .stream, derived from a .call, or pulled from callStateContext) and attaches it to an internal <video> element with autoplay, muted, and playsinline.

To keep the rendered area inside the viewport regardless of host size, a ResizeObserver (debounced 50 ms) watches the host element, the <video>``resize event watches the intrinsic media dimensions, and a window``resize listener watches the viewport. A “contain” fitting algorithm picks the constraining dimension and re-applies a centered transform: translate(...). Audio-only tracks fall back to filling the container.

The element can run standalone (pass .call or .stream directly) or inside a provider (<sw-call-provider> / <sw-call-widget>), where it picks up the active call from context. Input precedence (most specific wins): .stream > .call > context.

Class: SwCallMedia · Module: packages/web-components/src/components/sw-call-media.ts

class: `SwCallMedia`, `sw-call-media`

Fields

call

Call | undefined

Explicit Call, when set, subscribes directly to its observables instead of relying on context. Overridden by .stream if both are set.

stream

MediaStream | nullDefaults to null

Explicit remote MediaStream, highest precedence. Bypasses both .call and context. Useful for raw rendering with no SDK at all.

Attributes

Name	Field	Inherited From
`call`	call

CSS Properties

Name	Default	Description
`--bg-page`	`#0e0e18`	Background color shown behind the video (visible while the stream is loading or letterboxed for audio-only calls).

CSS Parts

Name	Description
`container`	Outer container (`.mcu-content`) that holds the video plus overlay layers. Style for backgrounds, drop shadows, etc.
`video`	The internal `<video>` element rendering the MCU stream. Useful for `object-fit`, filters, and rounded corners.

Slots

Name	Description
	Default slot rendered as an absolutely-positioned overlay layer above the remote video. Use it to compose `<sw-participants>`, `<sw-self-media>`, captions, branding, status chips, or any other UI.

sw-call-provider

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Top-level context provider that bridges an external Call and/or DeviceController into Lit context for every descendant SDK-aware component to consume.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-media></sw-call-media>
  <sw-call-controls></sw-call-controls>
</sw-call-provider>

Internally instantiates two reactive controllers:

CallStateContextController, subscribes to the Call’s observables (status$, self$, participants$, layoutLayers$, capabilities$, …) and exposes the latest snapshot through callStateContext.
DevicesContextController, subscribes to the DeviceController for device lists / selected devices / permissions and exposes them through devicesContext. It also wires the active Call so mute / unmute / device-switch operations route correctly.

Re-assigning .call or .deviceController cleanly disconnects the previous source and reconnects to the new one.

The host renders with display: contents, so the provider does not introduce its own box, descendants lay out as if they were direct children of the parent. Use <sw-call-widget> if you want a packaged, styled widget instead of just the context plumbing.

Class: SwCallProvider · Module: packages/web-components/src/components/sw-call-provider.ts

class: `SwCallProvider`, `sw-call-provider`

Fields

call

Call | undefinedDefaults to undefined

call field.

deviceController

DeviceController | undefinedDefaults to undefined

deviceController field.

Slots

Name	Description
	Default slot for any descendant components that should consume `callStateContext` and/or `devicesContext`.

sw-call-status

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Compact status pill that mirrors the live call state plus a running duration timer once the call is connected.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-status></sw-call-status>
</sw-call-provider>

Subscribes to call.status$ (or to callStateContext.status when nested inside <sw-call-provider> / <sw-call-widget>) and renders three pieces of UI:

A circular status indicator dot whose color/animation reflects the current state, pulsing yellow for connecting/ringing/trying/ recovering, solid green for connected, pulsing red for disconnecting, solid red for disconnected/failed, gray for new/destroyed.
A status label, mapped from the SDK’s CallStatus enum to a human-readable string (“Connecting…”, “Ringing…”, “Connected”, …).
A monospace M:SS (or H:MM:SS) duration counter that starts when the call enters connected and resets when it leaves.

Input precedence (most specific wins): .call > context. The label uses aria-live="polite" so screen readers are notified of state transitions without interrupting the user.

Class: SwCallStatus · Module: packages/web-components/src/components/sw-call-status.ts

class: `SwCallStatus`, `sw-call-status`

Fields

call

Call | undefined

Explicit Call, when set, subscribes directly to its observables and bypasses context.

Attributes

Name	Field	Inherited From
`call`	call

CSS Properties

Name	Default	Description
`--type-family-body`		Font family inherited from the design tokens.
`--type-size-small`		Font size for the label.
`--radius-md`		Border radius of the container pill.
`--fg-default`		Default label color.
`--bg-surface-raised`		Indicator color in idle states (`new`, `destroyed`).
`--interactive-status-success`		Color used while connected.
`--interactive-status-warning`		Color used during connection / recovery.
`--interactive-button-destructive-bg`		Color used for failure / disconnect states.

CSS Parts

Name	Description
`container`	Outer pill that wraps the indicator, label, and timer.
`status-text`	The text label (`role=“status”`, `aria-live=“polite”`).
`duration`	The running timer (only rendered while `connected`).

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

All-in-one call widget, handles client initialisation, dialling, media, controls and optional AI transcript in either inline or modal mode.

<sw-call-widget
  token="YOUR_GUEST_TOKEN"
  destination="/private/sales"
></sw-call-widget>

The widget owns the entire call lifecycle:

Builds a SignalWire credential provider from token (+ optional host) and connects on demand via client-factory.
Wires CallStateContextController, DevicesContextController, TranscriptController, and UserEventController so every nested SDK-aware component picks up live state for free.
Composes the visual layout from <sw-ui-call-layout>, <sw-call-media>, <sw-local-camera>, <sw-call-controls>, and optionally <sw-ui-transcript-view> and <sw-ui-content-drawer>.
Shows an <sw-ui-modal> overlay when modal is set, or renders inline (within the host’s bounding box) when it isn’t.
Listens for incoming-call signals via IncomingCallController when allow-incoming-calls is enabled and prompts the user to accept.

Use the imperative dial() and hangup() methods to trigger the widget programmatically, or click any element placed in the default slot (the trigger) when in idle state.

Class: SwCallWidget · Module: packages/web-components/src/components/sw-call-widget/sw-call-widget.ts

class: `SwCallWidget`, `sw-call-widget`

Fields

token

stringDefaults to ''

token field.

host

stringDefaults to ''

host field.

destination

stringDefaults to ''

destination field.

booleanDefaults to false

Skip auto-loading the SignalWire brand fonts (Lexend, Instrument Sans, JetBrains Mono) from Google Fonts. Set this when fonts are self-hosted or loaded elsewhere.

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
`dial`				`Promise<void>`
`hangup`				`Promise<void>`

Attributes

Name	Field	Inherited From
`token`	token
`host`	host
`destination`	destination
`modal`	modal
`transcription`	transcription
`allow-incoming-calls`	allowIncomingCalls
`audio-only`	audioOnly
`user-variables`	userVariables
`disable-auto-theme`	disableAutoTheme
`disable-auto-fonts`	disableAutoFonts

Slots

Name	Description
`background`	Background element behind the call view, e.g. `<sw-ui-background default>`.
	Default slot. Trigger element shown when idle; clicking it dials.

Events

Name	Detail	Description
`signalwire-address:event`	,	Forwarded SignalWire custom user events.
`sw-call-ended`	,	The call reached a terminal state, user hangup,
`sw-dial`	,	The widget began dialing (programmatic or via trigger).
`sw-display-content`	,	Forwarded from a `display_content` user event.

sw-device-selector

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Single-button popover that lets the user pick microphone, camera, and speaker devices, with optional live preview of each.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-device-selector></sw-device-selector>
</sw-call-provider>

The trigger renders as a small icon button; clicking it opens a panel with three sections (Microphone, Camera, Speaker), each populated from the corresponding observable on the bound DeviceController: audioInputDevices$, videoInputDevices$, audioOutputDevices$. The currently selected device is read from selectedAudio[Input|Output]Device$ / selectedVideoInputDevice$.

When show-preview is set, the open panel also renders:

A live camera preview powered by <sw-local-camera> for the selected video input.
A real-time microphone level meter (<sw-audio-level>) for the selected audio input.
A “Test speaker” button that plays a short tone through the selected audio output (uses setSinkId() where supported).

Streams are acquired only while the popover is open and stopped as soon as it closes, no permanent media access. The popover closes on outside click via a composedPath()-aware document listener.

Class: SwDeviceSelector · Module: packages/web-components/src/components/sw-device-selector/sw-device-selector.ts

class: `SwDeviceSelector`, `sw-device-selector`

Fields

deviceController

DeviceController | undefined

deviceController field.

showPreview

booleanDefaults to false

Render inline previews (camera video, mic level, speaker test) inside each section while the panel is open. Streams are acquired only while the panel is open and stopped when it closes.

Attributes

Name	Field	Inherited From
`show-preview`	showPreview
`deviceController`	deviceController

CSS Properties

Name	Default	Description
`--ctrl-bg`		Background color of the trigger button.
`--ctrl-bg-hover`		Background color on hover.
`--ctrl-color`		Foreground (icon + text) color.
`--ctrl-radius`		Trigger button border radius.
`--bg-surface`		Popover panel background.
`--bg-surface-raised`		Popover row hover background.
`--border-default`		Popover borders & dividers.
`--fg-default`		Primary text color inside the panel.
`--fg-muted`		Secondary text color (device sub-labels, kind hints).
`--radius-md`		Panel border radius.
`--shadow-md`		Panel drop shadow.

Events

Name	Detail	Description
`sw-device-change`	,	User picked a device from one of the dropdowns.

sw-directory

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Searchable, paginated contact list bound to a DirectoryService.

<sw-directory></sw-directory>

Displays the live addresses$ observable from a directory service as a scrollable list with a built-in search input. Each row is selectable and exposes per-channel call buttons (audio / video / messaging) when the corresponding channel is advertised by the address. The list also surfaces the service’s loading$ and hasMore$ observables and calls loadMore() (when available) for infinite-scroll pagination.

Class: SwDirectory · Module: packages/web-components/src/components/sw-directory.ts

class: `SwDirectory`, `sw-directory`

Fields

Attributes

Name	Field	Inherited From
`directory`	directory

CSS Properties

Name	Default	Description
`--interactive-button-primary-bg`	`#044ef4`	Primary brand color.
`--interactive-button-primary-hover`	`#0342cf`	Primary color on hover.
`--interactive-status-success`	`#22c55e`	Success / positive color.
`--fg-default`	`#f0f0f4`	Primary text color.
`--fg-muted`	`#a0a0aa`	Secondary / muted text color.
`--bg-surface`	`#181a28`	Component background color.
`--bg-surface-raised`	`#222436`	Background on hover.
`--interactive-dropdown-hover`	`#333338`	Background on active/press.
`--border-default`	`rgba(255,255,255,0.12)`	Border color.

CSS Parts

Name	Description
`container`	Outer flex container.
`search`	Search-input row at the top of the list.
`list`	The scrollable list of addresses.
`item`	One row in the list.
`item-selected`	A row when it is selected.
`action`	Per-row call button (audio / video / messaging).

Events

Name	Detail	Description
`sw-address-select`	,	The user clicked a row.
`sw-dial`	,	The user clicked a per-channel call button.

sw-local-camera

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Aspect-ratio-aware preview tile for the local camera, with a “camera off” placeholder when video is muted or the stream is missing.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-local-camera></sw-local-camera>
</sw-call-provider>

Designed for small picture-in-picture-style previews, typically slotted into <sw-ui-call-layout>’s floating-video slot or used standalone in a settings panel. The element reads getSettings() on the active video track to detect the natural orientation (landscape, portrait, or square) and rewrites --sw-local-camera-aspect so its container hugs the track.

Input precedence (most specific wins): .stream / .videoMuted >.call > context. Any of .stream and .videoMuted can be set independently, for example, you can supply an explicit stream from a “join” preview screen while still letting videoMuted come from devicesContext.

The mirror attribute reflects to the host so it can be styled with :host([mirror]) and is the natural default for selfie cameras.

Class: SwLocalCamera · Module: packages/web-components/src/components/sw-local-camera.ts

class: `SwLocalCamera`, `sw-local-camera`

Fields

stream

MediaStream | nullDefaults to null

Explicit stream, highest precedence.

videoMuted

boolean | undefined

Explicit muted flag, overrides devicesContext.videoMuted.

call

Call | undefined

Explicit Call, used when .stream is not set. Bypasses context.

mirror

booleanDefaults to false

mirror field.

Attributes

Name	Field	Inherited From
`video-muted`	videoMuted
`mirror`	mirror
`call`	call

CSS Properties

Name	Default	Description
`--sw-local-camera-aspect`	`16/9`	Aspect ratio of the tile. Automatically rewritten to match the active track’s orientation (e.g. `9 / 16` for portrait phone cameras).

CSS Parts

Name	Description
`video`	The internal `<video>` element rendering the local stream (`autoplay`, `muted`, `playsinline`).
`placeholder`	The “camera off” overlay shown while video is muted or no stream is bound.

sw-participant-controls

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Per-participant action panel, mute / unmute audio & video, adjust volume, pin / unpin, and remove a single participant from the call.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-participant-controls participant-id="123"></sw-participant-controls>
</sw-call-provider>

Identifies the target participant from the participant-id attribute by looking it up in callState.participants (or in the live Call when .call is set). Available actions are gated by the call’s capabilities list, for instance, “Remove” only renders when the server has granted the end_member (or equivalent) capability to the local user, and audio/video mute toggles require member_mute / etc.

Designed to be slotted into <sw-participants>’s controls-${memberId} named slot, but it works standalone anywhere you have a participant-id.

Input precedence (most specific wins): .call > context.

Class: SwParticipantControls · Module: packages/web-components/src/components/sw-participant-controls.ts

class: `SwParticipantControls`, `sw-participant-controls`

Fields

participantId

stringDefaults to ''

participantId field.

showVolume

booleanDefaults to false

showVolume field.

showPin

booleanDefaults to false

showPin field.

call

Call | undefined

Explicit Call, when set, subscribes directly and bypasses context.

Attributes

Name	Field	Inherited From
`participant-id`	participantId
`show-volume`	showVolume
`show-pin`	showPin
`call`	call

CSS Properties

Name	Default	Description
`--bg-page`		Panel background.
`--bg-surface`		Hover background for action buttons.
`--bg-surface-raised`		Active/pressed button background.
`--fg-default`		Foreground text & icon color.
`--border-default`		Border between sections.
`--radius-md`		Panel border radius.
`--shadow-md`		Panel drop shadow.
`--type-family-body`		Body font family.
`--type-size-small`		Body font size.
`--interactive-button-destructive-bg`		Background for the “Remove” button.
`--interactive-button-destructive-hover`		Hover background for “Remove”.
`--transition-fast`		Transition duration for hover/active states.

Events

Name	Detail	Description
`sw-participant-mute-audio`	,	Audio mute toggled.
`sw-participant-mute-video`	,	Video mute toggled.
`sw-participant-pin-toggle`	,	Pin / unpin clicked.
`sw-participant-remove`	,	Remove-from-call clicked.
`sw-participant-volume-change`	,	Volume slider released.

sw-participants

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Renders one absolutely-positioned overlay tile per remote participant in the MCU layout, plus per-participant menu hooks.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-media>
    <sw-participants></sw-participants>
  </sw-call-media>
</sw-call-provider>

Subscribes to call.layoutLayers$ and call.participants$ and renders a <div> for each layer whose member_id matches a remote participant (the local user is excluded, use <sw-self-media> for that). Each overlay is positioned via percentage top / left / width / height, so it tracks the MCU layout exactly as the renderer sees it.

Each tile also exposes a small ”⋯” menu trigger in its top-left corner. Clicking it opens a popover whose content is provided by a named slot keyed on the participant’s id: controls-${memberId}. Drop a <sw-participant-controls> (or any UI of your choosing) into that slot to expose mute / volume / pin / remove actions for that participant only.

Input precedence (most specific wins): .call > context. Mounting <sw-participants> outside <sw-call-media> is allowed but usually you want it to overlay the remote video, so it should live inside the default slot of <sw-call-media>.

Class: SwParticipants · Module: packages/web-components/src/components/sw-participants.ts

class: `SwParticipants`, `sw-participants`

Fields

call

Call | undefined

Explicit Call, when set, subscribes directly and bypasses context.

Attributes

Name	Field	Inherited From
`call`	call

Slots

Name	Description
	Default slot for any overlay content rendered above the tiles.
`controls-{memberId}`	Replace `{memberId}` with a participant’s `member_id` to inject the popover content shown when that participant’s ”⋯” trigger is clicked.

Events

Name	Detail	Description
`sw-participant-mute-audio`	,	User muted/unmuted a participant’s audio.
`sw-participant-mute-video`	,	User muted/unmuted a participant’s video.
`sw-participant-remove`	,	User removed a participant from the call.

sw-self-media

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Local video overlay automatically positioned over the matching tile in the MCU layout.

<sw-call-provider token="YOUR_GUEST_TOKEN">
  <sw-call-media>
    <sw-self-media></sw-self-media>
  </sw-call-media>
</sw-call-provider>

sw-self-media is designed to be slotted inside<sw-call-media>. It listens to three observables on the Call:

call.localStream$ for the camera/microphone stream of this user;
call.layoutLayers$ for the percentage-based rectangles used by the MCU;
call.self$ for the self participant’s id.

It then finds the layer whose member_id === self.id and positions an absolutely-placed container at the matching x / y / width / height (all expressed as percentages of the parent). When the layout changes mid-call (gallery → spotlight, presenter joining, …) the overlay re-positions automatically.

Unlike <sw-call-media> and <sw-audio-level>, this element does not accept a raw .stream prop, it needs layoutLayers and self.id to place itself, both of which only come from a Call. Input precedence (most specific wins): .call > context.

Apply the boolean mirror attribute to flip the video horizontally, which is the natural default for front-facing camera previews.

Class: SwSelfMedia · Module: packages/web-components/src/components/sw-self-media.ts

class: `SwSelfMedia`, `sw-self-media`

Fields

mirror

booleanDefaults to false

mirror field.

call

Call | undefined

Explicit Call, when set, subscribes directly and bypasses context.

Attributes

Name	Field	Inherited From
`mirror`	mirror
`call`	call

CSS Parts

Name	Description
`container`	The absolutely-positioned overlay div whose `top` / `left` / `width` / `height` track the MCU layer rectangle.
`video`	The internal `<video>` element rendering the local `MediaStream` (`autoplay`, `playsinline`, `muted`).

sw-ui-alert

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Modal confirmation / alert dialog primitive built on the native <dialog> element. Resolves a Promise with the user’s choice when used via the companion showPrompt() helper.

<sw-ui-alert id="confirm" title="Hang up?" confirm-label="Hang up" cancel-label="Stay"></sw-ui-alert>

Two interaction modes are selectable through the reflected type attribute:

confirm (default), renders both Cancel and OK buttons; the returned Promise resolves to true on accept and false on reject / dialog close.
alert, renders only OK; the Promise resolves to true once acknowledged or the dialog is dismissed.

The dialog uses the platform <dialog> element so focus management, ESC-to-dismiss, and ::backdrop styling all come for free.

Class: SwUiAlert · Module: packages/web-components/src/components/UI/sw-ui-alert.ts

class: `SwUiAlert`, `sw-ui-alert`

Fields

title

string

title field.

description

stringDefaults to ''

description field.

type

PromptTypeDefaults to 'confirm'

type field.

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
`show`		Opens the prompt and returns a promise that resolves with the user’s choice.		`Promise<boolean>`

Attributes

Name	Field	Inherited From
`title`	title
`description`	description
`type`	type

CSS Properties

Name	Default	Description
`--type-family-body`		Dialog font family.
`--radius-md`		Dialog border radius.
`--shadow-md`		Dialog drop shadow.
`--interactive-button-primary-bg`		Background color of the accept button.
`--interactive-button-primary-hover`		Hover background of the accept button.

Slots

Name	Description
	Default slot for rich body content. When non-empty, takes priority over the `description` property.

Functions

Name	Description	Parameters	Return
`showPrompt`	Programmatically show a prompt and await the user’s response.	`options: { title: string; description?: string; type?: PromptType; }`	`Promise<boolean>`

Events

Name	Detail	Description
`sw-ui-alert-accept`	,	User clicked OK / accepted. No detail.
`sw-ui-alert-reject`	,	User clicked Cancel, closed via ESC, or

sw-ui-background

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Decorative full-bleed background that progressively reveals a high-resolution image, a blurred thumbnail shows immediately, then crossfades to the full image once it has finished loading.

<sw-ui-background
  src="/images/hero.jpg"
  thumbnail-src="/images/hero-blur.jpg"
></sw-ui-background>

The component owns two stacked layers:

A blurred-thumbnail layer driven by a data: URL (small, encoded inline) so something visible paints on first frame.
An <img> that crossfades in (opacity: 0 → 1, slight transform: scale settle) when its load event fires.

Set default to use the built-in SignalWire brand background; otherwise supply your own thumbnail (data URL) and src (full image URL). Designed to be slotted into <sw-ui-call-layout>’s background slot or <sw-call-widget>’s background slot.

Class: SwUiBackground · Module: packages/web-components/src/components/UI/layout/sw-ui-background.ts

class: `SwUiBackground`, `sw-ui-background`

Fields

default

booleanDefaults to false

default field.

thumbnail

string | undefined

thumbnail field.

src

string | undefined

src field.

blurAmount

stringDefaults to '20px'

blurAmount field.

Attributes

Name	Field	Inherited From
`default`	default
`thumbnail`	thumbnail
`src`	src
`blur-amount`	blurAmount

CSS Parts

Name	Description
`thumb`	The blurred low-res thumbnail layer (initially visible).
`image`	The full-resolution `<img>` layer that fades in once loaded.

sw-ui-call-layout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Fluid call layout that adapts to any container shape.

<sw-ui-call-layout>
  <!-- call surface goes here -->
</sw-ui-call-layout>

Uses the container’s aspect ratio (not just width) to decide whether the transcript pane sits beside the video (landscape) or below it (portrait / narrow). The video area is always maximised.

Wide (landscape):                Narrow (portrait):
    
     VIDEO       TRANSCR           VIDEO       
  (maximised)    (side)         (maximised)    
    
        CONTROLS                   CONTROLS      
    
                                     TRANSCRIPT

Class: SwUiCallLayout · Module: packages/web-components/src/components/UI/layout/sw-ui-call-layout.ts

class: `SwUiCallLayout`, `sw-ui-call-layout`

Fields

transcript

booleanDefaults to false

show / hide the transcript pane

loading

booleanDefaults to false

show a spinner overlay on the video area

shadow

booleanDefaults to false

apply a drop shadow to the host

fullscreen

boolean

(read-only) reflects the current fullscreen state

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
`toggleTranscript`				`void`
`toggleFullscreen`				`void`

Attributes

Name	Field	Inherited From
`transcript`	transcript
`loading`	loading
`shadow`	shadow

CSS Properties

Name	Default	Description
`--sw-call-layout-radius`		[0] - border-radius on external corners
`--sw-call-layout-shadow`		box-shadow when `shadow` is set
`--sw-call-layout-loading-bg`		[rgba(0,0,0,0.6)] - loading overlay background
`--loading-spinner-size`		[48] - spinner icon size (px, number)
`--sw-call-layout-transcript-transition`		[350ms ease-in-out] - open/close transition
`--sw-call-layout-pip-width`		[clamp(100px, 20%, 200px)] - PiP container width
`--sw-call-layout-pip-radius`		[8px] - PiP border-radius
`--sw-call-layout-pip-shadow`		[0 2px 8px rgba(0,0,0,0.5)] - PiP box-shadow
`--sw-call-layout-pip-bottom`		[12px] - PiP offset from bottom
`--sw-call-layout-pip-right`		[12px] - PiP offset from right

Slots

Name	Description
`video`	main video content
`background`	element behind the video (e.g. `<sw-ui-background>`)
`floating-video`	picture-in-picture overlay (absolute, bottom-right)
`controls`	control bar beneath the video
`transcript`	transcript panel (side or bottom)

sw-ui-content-drawer

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Slide-in drawer that displays rich content the agent pushed mid-call (a snippet, a markdown article, a sanitized HTML fragment, or plain text) without leaving the call view.

<sw-ui-content-drawer open>
  <h2>Article</h2>
  <p>Rich content pushed from the agent appears here.</p>
</sw-ui-content-drawer>

Used by <sw-call-widget> to render display_content user events from the AI agent. The drawer auto-orients itself to the available space:

Wide containers, slides in from the right at ~360 px wide.
Narrow containers (parent ≤ 480 px), slides up from the bottom at ~50 % container height for better mobile ergonomics.

Four content formats are supported, each with appropriate sanitisation:

text, rendered verbatim with whitespace preserved.
markdown, parsed via marked, sanitised via DOMPurify with a strict tag/attribute allowlist; target="_blank" links are rewritten with rel="noopener noreferrer".
code, highlighted via Prism; the language must be supplied in payload.language and is loaded lazily.
html, passed through DOMPurify with the same allowlist as markdown.

Class: SwUiContentDrawer · Module: packages/web-components/src/components/UI/layout/sw-ui-content-drawer.ts

class: `SwUiContentDrawer`, `sw-ui-content-drawer`

language field.

Attributes

Name	Field	Inherited From
`open`	open
`narrow`	narrow
`title`	title
`content`	content
`format`	format
`language`	language

CSS Properties

Name	Default	Description
`--bg-page`		Drawer background.
`--fg-default`		Primary text color.
`--border-default`		Header divider color.
`--shadow-md`		Drawer drop shadow.
`--radius-md`		Drawer corner rounding (only the visible edges).
`--type-family-body`		Body font family.
`--type-size-small`		Body font size.

CSS Parts

Name	Description
`container`	Outer drawer container.
`header`	Sticky header (title + close button).
`title`	Title heading.
`close`	Close-button anchor.
`body`	Scrollable content body.

Events

Name	Detail	Description
`sw-content-drawer-close`	,	User clicked the close button. No detail.

sw-ui-control-bar

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Call controls bar.

<sw-ui-control-bar></sw-ui-control-bar>

Buttons rendered (left to right): mic, camera, speaker, screen share, hand raise, transcript, fullscreen, hang-up. Optional buttons are hidden when their show* property is false.

Class: SwUiControlBar · Module: packages/web-components/src/components/UI/controls/sw-ui-control-bar.ts

class: `SwUiControlBar`, `sw-ui-control-bar`

settingsItems field.

Attributes

Name	Field	Inherited From
`mic-muted`	micMuted
`camera-muted`	cameraMuted
`speaker-muted`	speakerMuted
`fullscreen`	fullscreen
`screen-sharing`	screenSharing
`hand-raised`	handRaised
`transcript-active`	transcriptActive
`show-screen-share`	showScreenShare
`show-hand-raise`	showHandRaise
`show-transcript`	showTranscript
`show-settings`	showSettings
`show-fullscreen`	showFullscreen

CSS Properties

Name	Default	Description
`--sw-control-bar-bg`		[transparent] - bar background
`--sw-control-bar-padding`		[8px 16px] - bar padding
`--sw-control-bar-gap`		[8px] - gap between buttons
`--sw-control-bar-radius`		[0] - bar border-radius
`--sw-split-button-size`		[44px] - button width & height
`--sw-split-button-bg`		[rgba(255,255,255,0.12)] - button background
`--sw-split-button-bg-hover`		[rgba(255,255,255,0.22)] - button hover bg
`--sw-split-button-color`		[#fff] - icon colour
`--sw-split-button-radius`		[9999px] - button border-radius
`--sw-control-bar-hangup-bg`		hang-up background (falls back to, interactive-button-destructive-bg)
`--sw-control-bar-hangup-bg-hover`		hang-up hover bg (falls back to, interactive-button-destructive-hover)
`--sw-control-bar-hangup-color`		hang-up icon colour (defaults to #fff) The active-toggle variant uses, interactive-button-primary-{bg,hover,text} from the design tokens.

Events

Name	Detail	Description
`sw-call-hangup`	,	Hang-up button clicked. No detail.
`sw-camera-toggle`	`{ muted: boolean }`	Camera toggled
`sw-device-change`	`{ kind, deviceId, label }`	Device picked from a chevron menu
`sw-fullscreen-toggle`	`{ fullscreen: boolean }`	Fullscreen toggled
`sw-hand-raise-toggle`	`{ raised: boolean }`	Hand raise toggled
`sw-mic-toggle`	`{ muted: boolean }`	Mic toggled
`sw-screen-share-toggle`	`{ active: boolean }`	Screen share toggled
`sw-settings-change`	`{ settingId: string }`	Settings menu item picked
`sw-speaker-toggle`	`{ muted: boolean }`	Speaker toggled
`sw-transcript-toggle`	,	Transcript button clicked. No detail.
`type`	,	,

sw-ui-dialpad

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Presentational 12-key telephone keypad (0-9, *, #) for entering phone numbers, sending DTMF tones, or capturing free-text destinations.

<sw-ui-dialpad></sw-ui-dialpad>

Pure UI primitive, no call logic, no SDK coupling. Use <sw-call-dialpad> for the SDK-aware version that automatically forwards digits to an active call.

Each key shows the digit plus the standard ITU-T E.161 letter mapping (2 → ABC, 3 → DEF, …). Two long-press shortcuts are built in:

Long-press 0 → inserts + (international prefix).
Long-press the backspace button → clears the entire buffer.

Set allow-text to let users type into the display field directly (useful for SIP URIs or destination addresses that aren’t strictly digits). Set show-call-button to render an inline “Call” button.

Class: SwUiDialpad · Module: packages/web-components/src/components/UI/controls/sw-ui-dialpad.ts

class: `SwUiDialpad`, `sw-ui-dialpad`

Fields

showCallButton

booleanDefaults to false

Whether to display the call button below the keypad.

allowText

booleanDefaults to false

Allow free-text input in the display field (e.g., SIP URIs, vanity letters). Keypad buttons still append DTMF digits.

placeholder

stringDefaults to 'Enter number'

Placeholder text shown in the digit display input.

Attributes

Name	Field	Inherited From
`show-call-button`	showCallButton
`allow-text`	allowText
`placeholder`	placeholder

CSS Properties

Name	Default	Description
`--interactive-button-primary-bg`	`#044ef4`	Primary accent color.
`--interactive-button-primary-hover`	`#0342cf`	Primary color on hover.
`--interactive-status-success`	`#22c55e`	Background of the “Call” button.
`--interactive-button-destructive-bg`	`#dc2626`	Backspace / hangup color.
`--bg-surface`	`#181a28`	Container background.
`--fg-default`	`#f0f0f4`	Digit / display text color.
`--fg-muted`	`#a0a0aa`	Letter-mapping subtext color.
`--border-default`	`rgba(255,255,255,0.12)`	Borders & dividers.

CSS Parts

Name	Description
`container`	Outer dialpad container.
`display`	Number / text display field.
`keypad`	Grid of digit keys.
`key`	Individual digit button.
`key-pressed`	Digit button while pressed.
`call-button`	The call button (only when `show-call-button`).

Events

Name	Detail	Description
`sw-dial`	,	The call button was pressed.
`sw-dialpad-backspace`	,	Backspace was pressed (or long-pressed to clear).
`sw-dialpad-input`	,	Free-text input changed (only when `allow-text` is set).
`sw-digit-press`	,	A digit button was pressed.

sw-ui-dropup

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Tiny pop-up menu that opens above its anchor and closes on outside click, the building block used for the chevron menus inside <sw-ui-split-button> (mic / camera / speaker selectors).

<sw-ui-dropup>
  <button slot="anchor">Open menu</button>
  <ul>
    <li>Item one</li>
    <li>Item two</li>
  </ul>
</sw-ui-dropup>

Items are supplied as a JSON-encoded array on the items attribute (or the items property). Each entry is either a string (used as both label and id) or a DropUpItem object, { label, id, selected? }. Clicking an item dispatches sw-dropup-select with that entry as the detail and closes the menu. Any click outside the host dispatches sw-dropup-close.

Class: SwUiDropup · Module: packages/web-components/src/components/UI/controls/sw-ui-dropup.ts

class: `SwUiDropup`, `sw-ui-dropup`

Fields

items

Array<DropUpItem | string>Defaults to []

items field.

open

booleanDefaults to false

open field.

anchor

Element | undefined

anchor field.

Attributes

Name	Field	Inherited From
`open`	open
`items`	items

CSS Properties

Name	Default	Description
`--sw-dropup-offset`		[4px] - Gap between anchor and menu.
`--sw-dropup-max-width`		[200px] - Maximum menu width.
`--sw-dropup-bg`		[var(, bg-page)] - Menu background.
`--sw-dropup-border`		[1px solid var(, border-default)] - Menu border.
`--sw-dropup-radius`		[var(, radius-md)] - Menu border-radius.
`--sw-dropup-shadow`		[var(, shadow-md)] - Menu box-shadow.
`--sw-dropup-color`		[var(, fg-default)] - Item text color.
`--sw-dropup-item-hover`		[var(, bg-surface)] - Item hover background.
`--sw-dropup-item-active`		[var(, bg-surface-raised)] - Selected item background.

Events

Name	Detail	Description
`sw-dropup-close`	,	Outside click closed the menu. No detail.
`sw-dropup-select`	,	User picked an item.

sw-ui-icon

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Inline SVG icon component backed by a curated icon set.

<sw-ui-icon name="microphone"></sw-ui-icon>

Picks an SVG out of the bundled ICONS map (raw import of .svg files in this folder) by name and renders it inline so it inherits color from its host, use currentColor in your stylesheets to tint the icon. Width and height are written into the SVG markup at render time using the size property so layout doesn’t depend on extra CSS.

The full set of available names is exported as the IconName type. Unknown names render nothing rather than throwing.

Class: SwUiIcon · Module: packages/web-components/src/components/UI/icons/sw-ui-icon.ts

class: `SwUiIcon`, `sw-ui-icon`

Fields

name

IconNameDefaults to 'close'

name field.

size

numberDefaults to 24

size field.

Attributes

Name	Field	Inherited From
`name`	name
`size`	size

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Lightweight modal wrapper built on the native <dialog> element with a built-in bounce-in / bounce-out animation.

<sw-ui-modal id="dialog">
  <h2>Hello</h2>
  <p>I'm a modal.</p>
</sw-ui-modal>

Toggle visibility via the boolean open property. Opening calls dialog.showModal() (so focus is trapped, the body is inert, and the native ::backdrop is rendered); closing animates out before calling dialog.close() so the host can be removed cleanly.

The element fires a cancelablesw-modal-close event on ESC or backdrop click, call event.preventDefault() from a parent to veto the close (e.g. when there are unsaved changes in the dialog body).

Class: SwUiModal · Module: packages/web-components/src/components/UI/layout/sw-ui-modal.ts

class: `SwUiModal`, `sw-ui-modal`

Fields

open

booleanDefaults to false

open field.

Attributes

Name	Field	Inherited From
`open`	open

CSS Properties

Name	Default	Description
`--sw-modal-duration`	`0.2s`	Open / close animation duration.
`--sw-modal-animation`		Open animation (bounce-in by default).
`--sw-modal-close-animation`		Close animation (bounce-out).
`--sw-modal-backdrop-animation`		Backdrop fade-in animation.
`--sw-modal-backdrop-close-animation`		Backdrop fade-out animation.

Slots

Name	Description
	Dialog content. Receives focus via the platform `<dialog>` element’s autofocus rules.

Events

Name	Detail	Description
`sw-modal-close`	,	Cancelable. Fired on ESC or backdrop click;

sw-ui-responsive-container

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Aspect-ratio-aware sizing wrapper used to host call surfaces inside <sw-ui-modal> so the experience adapts gracefully from ultra-wide monitors down to phones.

<sw-ui-responsive-container aspect-ratio="16/9">
  <sw-call-media></sw-call-media>
</sw-ui-responsive-container>

Applies a tiered set of CSS rules based on viewport size:

≥ 1280 px (large monitors): 80 vw, 16:9 aspect, height capped at (width × 9 / 16) + 300 px to leave room for controls.
600 px - 1279 px (laptops, small monitors): 90 vw, same 16:9 baseline.
≤ 600 px (mobile portrait): 100 vw minus a 20 px gutter, fluid height up to 85 svh, drops the strict aspect ratio so portrait content fills the screen.
≤ 500 px tall, ≥ 600 px wide (landscape phones, short windows): 90 vw, 90 vh max, aspect ratio relaxed.

Class: SwUiResponsiveContainer · Module: packages/web-components/src/components/UI/layout/sw-ui-responsive-container.ts

class: `SwUiResponsiveContainer`, `sw-ui-responsive-container`

Slots

Name	Description
	Default slot for the content the container should size around.

sw-ui-split-button

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Pill-shaped icon button with an optional chevron dropdown, the atomic building block of <sw-ui-control-bar>’s mic / camera / speaker buttons.

<sw-ui-split-button icon="microphone">
  <button slot="menu">Mute</button>
  <button slot="menu">Settings</button>
</sw-ui-split-button>

Renders in two layouts:

With a chevron menu (a slotted <sw-ui-dropup> or non-empty items): a unified pill split into a main click zone and a chevron click zone with a subtle divider, [ 🎤 | ]. Clicking the icon area fires the primary event; clicking the chevron opens the dropup.
Without a chevron menu: a single pill button.

Two interaction modes are inferred from which slots have content:

Toggle mode, both active and inactive slots are populated. Each click flips the active attribute and fires sw-split-button-toggle with the new state.
Push mode, only the default slot is populated. Each click fires sw-split-button-click without toggling.

Class: SwUiSplitButton · Module: packages/web-components/src/components/UI/controls/sw-ui-split-button.ts

class: `SwUiSplitButton`, `sw-ui-split-button`

Fields

items

Array<DropUpItem | string>Defaults to []

items field.

active

booleanDefaults to false

active field.

Attributes

Name	Field	Inherited From
`active`	active
`items`	items

CSS Properties

Name	Default	Description
`--sw-split-button-size`		[44px] - Button height (width auto-fits content).
`--sw-split-button-bg`		[var(, bg-surface)] - Button background.
`--sw-split-button-bg-hover`		[var(, bg-surface-raised)] - Hover background.
`--sw-split-button-color`		[var(, fg-default)] - Icon color.
`--sw-split-button-radius`		[var(, radius-full)] - Border radius.

Slots

Name	Description
`active`	Icon shown when `active` is `true` (toggle mode).
`inactive`	Icon shown when `active` is `false` (toggle mode).
	Default slot used by push-mode buttons (no `active`/`inactive` slot).
`dropup`	Optional `<sw-ui-dropup>` to enable the chevron menu.

Events

Name	Detail	Description
`sw-split-button-click`	,	Fired in push mode after each click. No detail.
`sw-split-button-toggle`	,	Fired in toggle mode after each click.

sw-ui-transcript-view

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Chat-bubble timeline that renders an array of TranscriptEntry items, each tagged as user / agent / system with optional rich content.

<sw-ui-transcript-view></sw-ui-transcript-view>

Designed to live inside <sw-ui-call-layout>’s transcript slot or <sw-ui-content-drawer> body. The view auto-scrolls to the latest entry, distinguishes “partial” (in-progress) entries with a subtle pulse, and renders rich meta payloads:

Links, clickable anchors injected as a footer beneath the bubble.
Code, Prism-highlighted snippet (language is loaded lazily).
Display content, content the agent pushed via a display_content user event; preserved verbatim so the download button can serialise the full payload back to markdown.

The header includes a download icon that exports the entire transcript as a .md file via transcriptToMarkdown() so users can save the conversation.

Class: SwUiTranscriptView · Module: packages/web-components/src/components/UI/sw-ui-transcript-view.ts

class: `SwUiTranscriptView`, `sw-ui-transcript-view`

Fields

entries

TranscriptEntry[]Defaults to []

entries field.

stringDefaults to 'Transcript'

header field.

emptyText

stringDefaults to ''

emptyText field.

Attributes

Name	Field	Inherited From
`header`	header
`empty-text`	emptyText

CSS Properties

Name	Default	Description
`--bg-page`		Background of the transcript surface.
`--bg-surface`		Background of agent/system bubbles.
`--bg-surface-raised`		Background of user bubbles.
`--fg-default`		Primary text color.
`--border-default`		Header divider and bubble borders.
`--type-family-body`		Body font family.
`--type-size-small`		Body font size.
`--transition-fast`		Transition duration for hover / state changes.

CSS Parts

Name	Description
`container`	Outer flex column.
`header`	Sticky header row with the download button.
`download-btn`	The download icon button.
`entries`	Scrollable container for transcript bubbles.
`entry`	One transcript entry bubble.
`entry-user`	Entry bubble when from the user.
`entry-agent`	Entry bubble when from the agent.
`entry-system`	Entry bubble when from system events.
`entry-partial`	Bubble while still streaming (`state === ‘partial’`).

Events

Name	Detail	Description
`sw-transcript-download`	,	User clicked the download button.

WebRTCCall

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

WebRTCCall represents an active call between the local user and one or more remote participants. Instances are never constructed directly by applications, they are returned by SignalWire.dial for outbound calls, or surfaced through the inbound-call flow once the user has register ed.

The class owns every aspect of an in-progress call: signaling (RTCPeerConnection, Verto messages), local and remote media streams, participant roster, layout, recording/streaming state, and network-quality telemetry. State is exposed in two complementary forms, a snapshot getter (e.g. locked) for one-shot reads and an observable (e.g. locked$) for reactive UI binding. Event streams that have no snapshot equivalent end in $ only (e.g. memberJoined$, signalingEvent$).

The available control methods depend on the capabilities granted by the server at join time, inspect capabilities$ before exposing a control in your UI. Calling hangup ends the call locally and transitions status$ to disconnected; the instance is then safe to release.

Extends

Destroyable

Implements

CallManager

Constructors

Constructor

new WebRTCCall(clientSession, options, initialization, address?): WebRTCCall

Parameters

clientSession

ClientSessionRequired

Active client session created by SignalWire. Provides the signaling transport and authentication context for the call.

options

CallOptionsRequired

Media and behavior options for this call (audio/video constraints, recovery, etc.). See CallOptions.

initialization

CallInitializationRequired

Initialization payload supplied by the SDK when constructing the call. Carries direction, remote address, and any inbound-call metadata.

address

Address

Optional pre-resolved Address for the destination. When omitted, the address is derived from the dial string or inbound signaling.

Returns

WebRTCCall

Properties

id

stringRequired

Unique identifier for this call.

to

string

Destination URI this call was placed to.

Accessors

address$\ \ Observable of the address associated with this call. answered$\ \ Observable that emits true when answered, false when rejected. answerMediaOptions\ \ Media options provided when answering. Used internally by the VertoManager. bandwidthConstrained$\ \ Observable indicating whether the call is bandwidth-constrained. callEvent$\ \ Observable of all call-related event payloads (join, leave, member updates, layout changes, etc.). callStates$\ \ Observable of call state-change events. callUpdated$\ \ Observable of call-updated events. capabilities$\ \ Observable of the call’s capability flags. destroyed$\ \ Observable that emits when the instance is destroyed direction\ \ Whether this call is 'inbound' or 'outbound'. errors$\ \ Observable stream of errors from media, signaling, and peer connection layers. from\ \ Address URI of the caller. fromName\ \ Display name of the caller. isNetworkHealthy$\ \ Simple boolean health indicator derived from stats monitor. layout$\ \ Observable of the current layout name. layoutEvent$\ \ Observable of layout-changed event payloads. layoutLayers$\ \ Observable of layout layer positions for all participants. layouts$\ \ Observable of available layout names. layoutUpdates$\ \ Observable of layout-changed events. localAudioLevel$\ \ Observable of the RMS audio level of the local microphone, 0..1. Emits at ~30fps while a mic track is active. Engages the local audio pipeline on first subscription. localMicrophoneGain$\ \ Observable of the current local microphone gain (0..200, where 100 = unity). localSpeaking$\ \ Observable that is true while the local participant is speaking (RMS level above the VAD threshold, with hold time to avoid flicker). localStream$\ \ Observable of the local media stream (camera/microphone). locked$\ \ Observable indicating whether the call room is locked. mediaDirections$\ \ Observable of the current audio/video send/receive directions. mediaParamsUpdated$\ \ Observable that emits when server-pushed media params are applied. memberJoined$\ \ Observable of member-joined events, emitted when a remote participant joins the call. memberLeft$\ \ Observable of member-left events, emitted when a participant leaves the call. memberTalking$\ \ Observable of member-talking events (speech start/stop). memberUpdated$\ \ Observable of member-updated events (mute, volume, etc.). meta$\ \ Observable of custom metadata associated with the call. networkIssues$\ \ Observable of current network health issues (empty array = healthy). networkMetrics$\ \ Rolling history of raw network metrics (RTT, jitter, packet loss, bitrate). nodeId$\ \ Observable of the server node ID handling this call. participants$\ \ Observable of the participants list, emits on join/leave/update. participantsId$\ \ Observable of the current participant ID list for the call. qualityLevel$\ \ Observable of simplified quality level (excellent/good/fair/poor/critical). qualityScore$\ \ Observable of MOS quality score (1-5) computed from stats metrics. raiseHandPriority$\ \ Observable indicating whether raise-hand priority is active. recording$\ \ Observable indicating whether the call is being recorded. recoveryEvent$\ \ Observable of recovery events (keyframe requested, ICE restart, etc.). recoveryState$\ \ Observable of the recovery pipeline state machine. remoteAudioLevel$\ \ Observable of the aggregate remote audio level, 0..1 RMS. remoteStream$\ \ Observable of the remote media stream from the far end. rtcPeerConnection\ \ Underlying RTCPeerConnection, for advanced use cases. self$\ \ Observable of the local (self) participant. selfId$\ \ Observable of the local participant’s member ID. signalingEvent$\ \ Observable of raw signaling events as plain objects. status$\ \ Observable of the current call status (e.g. 'ringing', 'connected'). streaming$\ \ Observable indicating whether the call is being streamed. toName\ \ Display name of the callee. userVariables$\ \ Observable of custom user variables associated with the call. webrtcMessages$\ \ Observable of raw WebRTC message payloads received on this call.

Methods

answer\ \ Accepts an inbound call, optionally overriding media options for the answer. destroy\ \ Destroys the call, releasing all resources and subscriptions. disablePushToTalk\ \ Disable push-to-talk; mic gain returns to the configured value. enablePushToTalk\ \ Enable push-to-talk: while setPushToTalkActive has been called with false, the microphone gain is forced to 0; calling setPushToTalkActive with true restores the configured gain. execute\ \ Executes a raw JSON-RPC request on the client session. executeMethod\ \ Executes a Verto RPC method targeting a specific participant. hangup\ \ Hangs up the call and releases all resources. notifyModifyFailed\ \ Notify the recovery manager that a verto.modify signaling exchange failed. reject\ \ Rejects an inbound call, preventing media negotiation. requestIceRestart\ \ Force an ICE restart / re-INVITE. requestKeyframe\ \ Request a video keyframe via RTCP PLI/FIR. sendDigits\ \ Sends DTMF digits on the call. setAutoGainControl\ \ Toggle browser automatic gain control on the local mic at runtime. setEchoCancellation\ \ Toggle echo cancellation on the local mic at runtime. setLayout\ \ Sets the call layout and participant positions. setLocalMicrophoneGain\ \ Set the local microphone gain as a percentage applied before transmission. setMeta\ \ Replaces the call’s custom metadata. setNoiseSuppression\ \ Toggle browser noise suppression on the local mic at runtime. setPushToTalkActive\ \ While push-to-talk is enabled, sets the talk state. true = transmitting, false = silent. No-op if push-to-talk has not been enabled. startRecording\ \ Not yet implemented. Status tracked via recording$. startStreaming\ \ Not yet implemented. Status tracked via streaming$. subscribe\ \ Subscribe to a custom signaling event type on this call. toggleHold\ \ Toggles the hold state of the call (pauses/resumes local media transmission). toggleIncomingAudio\ \ Toggles whether incoming audio is received. toggleIncomingVideo\ \ Toggles whether incoming video is received. toggleLock\ \ Toggles the call lock state, preventing or allowing new participants from joining. transfer\ \ Transfers the call to another destination. updateMeta\ \ Merges values into the call’s custom metadata (unlike setMeta which replaces).

address$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get address$(): Observable<[Address](/docs/browser-sdk/v4/reference/address) | undefined>

Observable of the address associated with this call. Emits undefined until the address has been resolved by the signaling layer.

address

get address(): [Address](/docs/browser-sdk/v4/reference/address) | undefined

Snapshot of the current address associated with this call, or undefined if not yet resolved. For a reactive view, use address$ instead.

Examples

call.address$.subscribe((address) => {
  console.log('address:', address);
});

answer

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

answer(options?): void

Accepts an inbound call. The call transitions through connecting → connected as media negotiation completes.

Without options, the call answers with the media defaults configured on the SignalWire client (typically audio + video). Pass options to narrow what’s offered, for example, accepting a video call with audio only.

answer returns synchronously; observe progression through status$ or answered$.

Parameters

options

MediaOptions

Optional media constraints for the answer (audio, video, and the input-stream / constraint overrides defined on MediaOptions). When omitted, the client-level defaults apply.

Returns

void

Examples

Accept with defaults

call.answer();

Accept audio-only

call.answer({ audio: true, video: false });

Accept, then await the connection

import { filter, take } from 'rxjs';

call.answer();
const connected = await call.status$
  .pipe(filter((s) => s === 'connected'), take(1))
  .toPromise();

See

reject to decline the call instead.
answered$ to observe the acceptance state.

answerMediaOptions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get answerMediaOptions(): MediaOptions | undefined

Media options provided when answering. Used internally by the VertoManager.

Examples

console.log(call.answerMediaOptions);

answered$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get answered$(): Observable<boolean>

Observable that emits true when answered, false when rejected.

Examples

call.answered$.subscribe((answered) => {
  console.log('answered:', answered);
});

bandwidthConstrained$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get bandwidthConstrained$(): Observable<boolean>

Observable indicating whether the call is bandwidth-constrained.

Examples

call.bandwidthConstrained$.subscribe((bandwidthConstrained) => {
  console.log('bandwidthConstrained:', bandwidthConstrained);
});

callEvent$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get callEvent$(): Observable<WebrtcMessagePayload | CallJoinedPayload | CallLeftPayload | MemberUpdatedPayload | MemberJoinedPayload | MemberLeftPayload | MemberTalkingPayload | LayoutChangedPayload | CallUpdatedPayload | RoomUpdatedPayload | CallStatePayload | CallPlayPayload | CallConnectPayload | ConversationMessagePayload>

Examples

call.callEvent$.subscribe((callEvent) => {
  console.log('callEvent:', callEvent);
});

callStates$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get callStates$(): Observable<CallStatePayload>

Observable of call state-change events.

Examples

call.callStates$.subscribe((callStates) => {
  console.log('callStates:', callStates);
});

callUpdated$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get callUpdated$(): Observable<CallUpdatedPayload>

Observable of call-updated events.

Examples

call.callUpdated$.subscribe((callUpdated) => {
  console.log('callUpdated:', callUpdated);
});

capabilities$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get capabilities$(): Observable<Capability[]>

Observable of the call’s capability flags.

capabilities

get capabilities(): Capability[]

List of capabilities available in the current call.

Examples

call.capabilities$.subscribe((capabilities) => {
  console.log('capabilities:', capabilities);
});

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy(): void

Destroys the call, releasing all resources and subscriptions.

Examples

call.destroy();

destroyed$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get destroyed$(): Observable<void>

Observable that emits when the instance is destroyed

Inherited from

Destroyable.destroyed$

Examples

call.destroyed$.subscribe((destroyed) => {
  console.log('destroyed:', destroyed);
});

direction

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get direction(): CallDirection

Whether this call is 'inbound' or 'outbound'.

Examples

console.log(call.direction);

disablePushToTalk

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disablePushToTalk(): void

Tears down the push-to-talk pipeline installed by enablePushToTalk. The microphone gain returns to whatever value was configured before push-to-talk was enabled, typically full gain.

Safe to call when push-to-talk was never enabled; this is a no-op in that case.

Returns

void

Examples

Disable on call hangup

call.status$.subscribe((status) => {
  if (status === 'disconnected') call.disablePushToTalk();
});

See

enablePushToTalk, install the pipeline.
setPushToTalkActive, toggle transmit state.

enablePushToTalk

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enablePushToTalk(): void

Enable push-to-talk: while setPushToTalkActive has been called with false, the microphone gain is forced to 0; calling setPushToTalkActive with true restores the configured gain. Use this instead of mute/unmute for instant talk/silence transitions because it doesn’t rebuild the track.

This method installs the pipeline but does not attach any keyboard listener, consumers bind the key themselves and call setPushToTalkActive on keydown/keyup.

Returns

void

Examples

Bind to the Space key

call.enablePushToTalk();
call.setPushToTalkActive(false); // start silent

document.addEventListener('keydown', (e) => {
  if (e.code === 'Space' && !e.repeat) call.setPushToTalkActive(true);
});
document.addEventListener('keyup', (e) => {
  if (e.code === 'Space') call.setPushToTalkActive(false);
});

See

disablePushToTalk, tear down the pipeline.
setPushToTalkActive, toggle transmit state.

errors$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get errors$(): Observable<CallError>

Observable stream of errors from media, signaling, and peer connection layers.

Examples

call.errors$.subscribe((errors) => {
  console.log('errors:', errors);
});

execute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

execute<T>(request, options?): Promise<T>

Executes a raw JSON-RPC request on the client session.

Lower-level than executeMethod, allows full control over the RPC request structure.

Type Parameters

Type Parameter	Default type
`T` extends`JSONRPCResponse`	`JSONRPCResponse`

Parameters

request

JSONRPCRequestRequired

Complete JSON-RPC request object. See JSONRPCRequest.

options

PendingRPCOptions

Optional RPC execution options (timeout, etc.). See PendingRPCOptions.

Returns

Promise<T>

The RPC response.

Throws

If the RPC call returns an error response.

Examples

Send a raw JSON-RPC request

const response = await call.execute({
  jsonrpc: '2.0',
  id: crypto.randomUUID(),
  method: 'call.mute',
  params: { call_id: call.id },
});

See

executeMethod, higher-level wrapper for member-targeted Verto methods.

executeMethod

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

executeMethod<T>(target, method, args): Promise<T>

Executes a Verto RPC method targeting a specific participant.

Constructs call context (node_id, call_id, member_id) and sends the RPC request.

Type Parameters

Type Parameter	Default type
`T` extends`JSONRPCResponse`	`JSONRPCResponse`

Parameters

target

string | MemberTargetRequired

Target member ID string, or a MemberTarget object.

method

stringRequired

Verto method name (e.g. 'call.mute', 'call.member.remove').

args

Record<string, unknown>Required

Parameters for the RPC method.

Returns

Promise<T>

The RPC response.

Throws

If the RPC call returns an error.

Examples

Mute a remote member

await call.executeMethod(memberId, 'call.mute', { channels: ['audio'] });

Remove a member from the call

await call.executeMethod(memberId, 'call.member.remove', {});

See

execute, lower-level raw JSON-RPC send.

from

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get from(): string | undefined

Address URI of the caller.

Examples

console.log(call.from);

fromName

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get fromName(): string | undefined

Display name of the caller.

Examples

console.log(call.fromName);

hangup

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

hangup(): Promise<void>

Ends the call and releases all WebRTC resources.

Sends a Verto bye to the server, transitions status$ to disconnecting then disconnected, and destroys the call instance. After the promise resolves, the call object is no longer usable, drop your reference and let it be garbage-collected.

The promise resolves once the local teardown has completed. Server-side cleanup (recording finalization, billing) continues asynchronously and is not awaited.

Returns

Promise<void>, resolves when the local teardown has completed.

Examples

Hang up on user click

endCallButton.addEventListener('click', async () => {
  await call.hangup();
  showCallEndedUI();
});

Hang up from a status subscription

call.status$.subscribe(async (status) => {
  if (status === 'connected' && callTooLong()) {
    await call.hangup();
  }
});

See

reject to decline an inbound call before it’s answered.
status$ to observe the call’s lifecycle.

isNetworkHealthy$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get isNetworkHealthy$(): Observable<boolean>

Simple boolean health indicator derived from stats monitor.

isNetworkHealthy

get isNetworkHealthy(): boolean

Whether the network is currently healthy.

Examples

call.isNetworkHealthy$.subscribe((isNetworkHealthy) => {
  console.log('isNetworkHealthy:', isNetworkHealthy);
});

layout$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get layout$(): Observable<string>

Observable of the current layout name.

layout

get layout(): string | undefined

Current layout name, or undefined if not set.

Examples

call.layout$.subscribe((layout) => {
  console.log('layout:', layout);
});

layoutEvent$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get layoutEvent$(): Observable<LayoutChangedPayload>

Examples

call.layoutEvent$.subscribe((layoutEvent) => {
  console.log('layoutEvent:', layoutEvent);
});

layoutLayers$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get layoutLayers$(): Observable<LayoutLayer[]>

Observable of layout layer positions for all participants.

layoutLayers

get layoutLayers(): LayoutLayer[]

Current snapshot of layout layers.

Examples

call.layoutLayers$.subscribe((layoutLayers) => {
  console.log('layoutLayers:', layoutLayers);
});

layoutUpdates$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get layoutUpdates$(): Observable<LayoutChangedPayload>

Observable of layout-changed events.

Examples

call.layoutUpdates$.subscribe((layoutUpdates) => {
  console.log('layoutUpdates:', layoutUpdates);
});

layouts$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get layouts$(): Observable<string[]>

Observable of available layout names.

layouts

get layouts(): string[]

Current snapshot of available layout names.

Examples

call.layouts$.subscribe((layouts) => {
  console.log('layouts:', layouts);
});

localAudioLevel$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get localAudioLevel$(): Observable<number>

Observable of the RMS audio level of the local microphone, 0..1. Emits at ~30fps while a mic track is active. Engages the local audio pipeline on first subscription.

Examples

call.localAudioLevel$.subscribe((localAudioLevel) => {
  console.log('localAudioLevel:', localAudioLevel);
});

localMicrophoneGain$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get localMicrophoneGain$(): Observable<number>

Observable of the current local microphone gain (0..200, where 100 = unity).

Examples

call.localMicrophoneGain$.subscribe((localMicrophoneGain) => {
  console.log('localMicrophoneGain:', localMicrophoneGain);
});

localSpeaking$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get localSpeaking$(): Observable<boolean>

Observable that is true while the local participant is speaking (RMS level above the VAD threshold, with hold time to avoid flicker).

Examples

call.localSpeaking$.subscribe((localSpeaking) => {
  console.log('localSpeaking:', localSpeaking);
});

localStream$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get localStream$(): Observable<MediaStream>

Observable of the local media stream (camera/microphone).

localStream

get localStream(): MediaStream | null

Current local media stream, or null if not available.

Examples

call.localStream$.subscribe((localStream) => {
  console.log('localStream:', localStream);
});

locked$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get locked$(): Observable<boolean>

Observable indicating whether the call room is locked.

locked

get locked(): boolean

Whether the call room is locked.

Examples

call.locked$.subscribe((locked) => {
  console.log('locked:', locked);
});

mediaDirections$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get mediaDirections$(): Observable<MediaDirections>

Observable of the current audio/video send/receive directions.

mediaDirections

get mediaDirections(): MediaDirections

Current audio/video send/receive directions.

Examples

call.mediaDirections$.subscribe((mediaDirections) => {
  console.log('mediaDirections:', mediaDirections);
});

mediaParamsUpdated$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get mediaParamsUpdated$(): Observable<MediaParamsEvent>

Observable that emits when server-pushed media params are applied.

Examples

call.mediaParamsUpdated$.subscribe((mediaParamsUpdated) => {
  console.log('mediaParamsUpdated:', mediaParamsUpdated);
});

memberJoined$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get memberJoined$(): Observable<MemberJoinedPayload>

Observable of member-joined events, emitted when a remote participant joins the call.

Examples

call.memberJoined$.subscribe((memberJoined) => {
  console.log('memberJoined:', memberJoined);
});

memberLeft$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get memberLeft$(): Observable<MemberLeftPayload>

Observable of member-left events, emitted when a participant leaves the call.

Examples

call.memberLeft$.subscribe((memberLeft) => {
  console.log('memberLeft:', memberLeft);
});

memberTalking$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get memberTalking$(): Observable<MemberTalkingPayload>

Observable of member-talking events (speech start/stop).

Examples

call.memberTalking$.subscribe((memberTalking) => {
  console.log('memberTalking:', memberTalking);
});

memberUpdated$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get memberUpdated$(): Observable<MemberUpdatedPayload>

Observable of member-updated events (mute, volume, etc.).

Examples

call.memberUpdated$.subscribe((memberUpdated) => {
  console.log('memberUpdated:', memberUpdated);
});

meta$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get meta$(): Observable<Record<string, unknown>>

Observable of custom metadata associated with the call.

meta

get meta(): Record<string, unknown>

Current custom metadata of the call.

Examples

call.meta$.subscribe((meta) => {
  console.log('meta:', meta);
});

networkIssues$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get networkIssues$(): Observable<CallNetworkIssue[]>

Observable of current network health issues (empty array = healthy).

networkIssues

get networkIssues(): CallNetworkIssue[]

Current snapshot of network issues.

Examples

call.networkIssues$.subscribe((networkIssues) => {
  console.log('networkIssues:', networkIssues);
});

networkMetrics$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get networkMetrics$(): Observable<CallNetworkMetrics[]>

Rolling history of raw network metrics (RTT, jitter, packet loss, bitrate).

networkMetrics

get networkMetrics(): CallNetworkMetrics[]

Current snapshot of the metrics rolling window.

Examples

call.networkMetrics$.subscribe((networkMetrics) => {
  console.log('networkMetrics:', networkMetrics);
});

nodeId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get nodeId$(): Observable<string | null>

Observable of the server node ID handling this call.

nodeId

get nodeId(): string | null

Server node ID handling this call, or null.

Examples

call.nodeId$.subscribe((nodeId) => {
  console.log('nodeId:', nodeId);
});

notifyModifyFailed

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

notifyModifyFailed(): void

Notify the recovery manager that a verto.modify signaling exchange failed.

Returns

void

Examples

call.notifyModifyFailed();

participants$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get participants$(): Observable<CallParticipant[]>

Observable of the participants list, emits on join/leave/update.

participants

get participants(): CallParticipant[]

Current snapshot of all participants in the call.

Examples

call.participants$.subscribe((participants) => {
  console.log('participants:', participants);
});

participantsId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get protected participantsId$(): Observable<string[]>

Protected internal observable that emits the list of participant IDs currently in the call. Prefer participants$ (which emits the full CallParticipant objects) for application code.

Examples

// Within subclasses of WebRTCCall:
this.participantsId$.subscribe((ids) => {
  console.log('participant IDs:', ids);
});

See

participants$, the public counterpart with full participant objects.

qualityLevel$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get qualityLevel$(): Observable<QualityLevel>

Observable of simplified quality level (excellent/good/fair/poor/critical).

Examples

call.qualityLevel$.subscribe((qualityLevel) => {
  console.log('qualityLevel:', qualityLevel);
});

qualityScore$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get qualityScore$(): Observable<number>

Observable of MOS quality score (1-5) computed from stats metrics.

Examples

call.qualityScore$.subscribe((qualityScore) => {
  console.log('qualityScore:', qualityScore);
});

raiseHandPriority$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get raiseHandPriority$(): Observable<boolean>

Observable indicating whether raise-hand priority is active.

raiseHandPriority

get raiseHandPriority(): boolean

Whether raise-hand priority is active.

Examples

call.raiseHandPriority$.subscribe((raiseHandPriority) => {
  console.log('raiseHandPriority:', raiseHandPriority);
});

recording$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get recording$(): Observable<boolean>

Observable indicating whether the call is being recorded.

recording

get recording(): boolean

Whether the call is currently being recorded.

Examples

call.recording$.subscribe((recording) => {
  console.log('recording:', recording);
});

recoveryEvent$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get recoveryEvent$(): Observable<RecoveryEvent>

Observable of recovery events (keyframe requested, ICE restart, etc.).

Examples

call.recoveryEvent$.subscribe((recoveryEvent) => {
  console.log('recoveryEvent:', recoveryEvent);
});

recoveryState$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get recoveryState$(): Observable<RecoveryState>

Observable of the recovery pipeline state machine.

Examples

call.recoveryState$.subscribe((recoveryState) => {
  console.log('recoveryState:', recoveryState);
});

reject

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

reject(): void

Declines an inbound call before it is answered. The caller-side rings stop, no media is negotiated, and the call instance transitions to disconnected. Call reject only on inbound calls in the ringing state; calling it after answer has no effect, use hangup instead to end a connected call.

Returns

void

Examples

Reject from a UI button

declineButton.addEventListener('click', () => {
  call.reject();
});

Auto-reject calls during do-not-disturb

incomingCall.status$.subscribe((status) => {
  if (status === 'ringing' && userIsBusy()) {
    incomingCall.reject();
  }
});

See

answer to accept the call instead.
hangup to end a call that’s already connected.
answered$ emits false after rejection.

remoteAudioLevel$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get remoteAudioLevel$(): Observable<number>

Observable of the aggregate remote audio level, 0..1 RMS. The server delivers a single mixed audio stream for all remote participants, this meter reports that mix. Per-participant audio is not available client-side.

Engages a shared AudioContext on first subscription (cheap, one AnalyserNode, no GainNode, no destination) so it does not affect the caller’s audio element playback.

Examples

call.remoteAudioLevel$.subscribe((remoteAudioLevel) => {
  console.log('remoteAudioLevel:', remoteAudioLevel);
});

remoteStream$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get remoteStream$(): Observable<MediaStream>

Observable of the remote media stream from the far end.

remoteStream

get remoteStream(): MediaStream | null

Current remote media stream, or null if not available.

Examples

call.remoteStream$.subscribe((remoteStream) => {
  console.log('remoteStream:', remoteStream);
});

requestIceRestart

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

requestIceRestart(): Promise<void>

Force an ICE restart / re-INVITE.

Returns

Promise<void>

Examples

await call.requestIceRestart();

requestKeyframe

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

requestKeyframe(): void

Request a video keyframe via RTCP PLI/FIR.

Returns

void

Examples

call.requestKeyframe();

rtcPeerConnection

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get rtcPeerConnection(): RTCPeerConnection | undefined

Underlying RTCPeerConnection, for advanced use cases.

Examples

console.log(call.rtcPeerConnection);

self$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get self$(): Observable<CallSelfParticipant>

Observable of the local (self) participant.

self

get self(): CallSelfParticipant | null

The local participant, or null if not yet joined.

Examples

call.self$.subscribe((self) => {
  console.log('self:', self);
});

selfId$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selfId$(): Observable<string | null>

Observable of the local participant’s member ID.

selfId

get selfId(): string | null

Local participant’s member ID, or null if not joined.

Examples

call.selfId$.subscribe((selfId) => {
  console.log('selfId:', selfId);
});

sendDigits

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

sendDigits(dtmf): Promise<void>

Sends DTMF tones on the call. Each character in the string is transmitted as a separate tone in order, with timing managed by the server.

Accepted characters: digits 0-9, *, #, and the w / W wait separators (the lowercase w inserts a short pause, the uppercase W a longer one). Any other character produces an error from the server.

Requires the sendDigit capability, inspect call.capabilities$ before exposing a dialpad in your UI.

Parameters

dtmf

stringRequired

The digit string to send (e.g. '1234#', '1w234'). Each character is transmitted as a separate tone.

Returns

Promise<void>, resolves once the server has accepted the full string for playback.

Examples

Dial an extension after connection

await call.sendDigits('1234#');

Drive an IVR with pauses

// '1' → wait → '2' → long wait → '#'
await call.sendDigits('1w2W#');

Hook a dialpad button

dialpad.addEventListener('press', async (digit) => {
  await call.sendDigits(digit);
});

See

capabilities$ to check whether digit-sending is permitted on this call.

setAutoGainControl

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setAutoGainControl(enabled): Promise<void>

Toggle browser automatic gain control on the local mic at runtime.

Parameters

enabled

booleanRequired

Whether automatic gain control should be enabled.

Returns

Promise<void>, resolves once the new constraint has been applied to the active microphone track.

Examples

Toggle from a UI switch

agcSwitch.addEventListener('change', async (e) => {
  await call.setAutoGainControl(e.target.checked);
});

See

setEchoCancellation, setNoiseSuppression, companion processing toggles.

setEchoCancellation

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setEchoCancellation(enabled): Promise<void>

Toggle echo cancellation on the local mic at runtime. Applied via track.applyConstraints; browsers that don’t honour runtime constraints (notably iOS Safari) fall back to re-acquiring the track with the new constraint set and plumbing the replacement through the local audio pipeline if one is active.

Parameters

enabled

booleanRequired

Whether echo cancellation should be enabled.

Returns

Promise<void>, resolves after the constraint has been applied (via applyConstraints or, on browsers without runtime support, after a track replacement).

Examples

Toggle from a UI switch

echoSwitch.addEventListener('change', async (e) => {
  await call.setEchoCancellation(e.target.checked);
});

See

setAutoGainControl, setNoiseSuppression, companion processing toggles.

setLayout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLayout(layout, positions): Promise<void>

Switches the call to a named video layout and (optionally) places specific members into reserved positions.

The set of valid layout names depends on the call’s room configuration and is exposed reactively via layouts$. Member position values come from VideoPosition.

Requires the setLayout capability, inspect call.capabilities$ before exposing layout controls.

Parameters

layout

stringRequired

Layout name. Must be one of the names emitted by layouts$.

positions

Record<string, VideoPosition>Required

Map of member IDs to VideoPosition values. Pass an empty object to let the server assign positions automatically.

Returns

Promise<void>, resolves once the server has applied the layout.

Throws

Rejects if layout is not in the call’s available layouts.

Examples

Switch to a grid layout

await call.setLayout('grid-responsive', {});

Pin a member to a reserved slot

await call.setLayout('1x1-with-presenter', {
  [participantId]: 'reserved-0',
});

See

layouts$, observable list of available layout names.
layout$, currently active layout.
layoutLayers$, observable of position assignments.

setLocalMicrophoneGain

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLocalMicrophoneGain(value): void

Set the local microphone gain as a percentage applied before transmission.

0 = silent
100 = unity (no change, default)
200 = 2× digital boost (max; expect clipping / noise amplification)

Values are clamped to [0, 200]. Engages the local audio pipeline on first use (one-time cost).

Note: this is a digital multiplier applied in a Web Audio GainNode between your mic track and the RTCRtpSender, it does not change the physical mic’s hardware sensitivity. Browsers’ autoGainControl can fight the setting; call setAutoGainControl(false) for predictable behaviour.

Parameters

value

numberRequired

Gain percentage (0..200; 100 = unity).

Returns

void

Examples

call.setLocalMicrophoneGain(value);

setMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMeta(_meta): Promise<void>

Replaces the call’s custom metadata bag with the provided object. Existing keys not present in _meta are discarded. To merge instead, use updateMeta.

Metadata is observed via call.meta$ on all connected peers; use it to share UI state (e.g. a current presenter name, agenda items) across the call.

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

New metadata object. Replaces all existing keys.

Returns

Promise<void>, once implemented, resolves after the server has propagated the new metadata.

Throws

Throws unconditionally, implementation pending.

See

updateMeta, partial-merge alternative.
meta$, observable of the current metadata.

setNoiseSuppression

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setNoiseSuppression(enabled): Promise<void>

Toggle browser noise suppression on the local mic at runtime.

Parameters

enabled

booleanRequired

Whether noise suppression should be enabled.

Returns

Promise<void>, resolves once the new constraint has been applied to the active microphone track.

Examples

Toggle from a UI switch

denoiseSwitch.addEventListener('change', async (e) => {
  await call.setNoiseSuppression(e.target.checked);
});

See

setAutoGainControl, setEchoCancellation, companion processing toggles.

setPushToTalkActive

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setPushToTalkActive(active): void

While push-to-talk is enabled, sets the talk state. true = transmitting, false = silent. No-op if push-to-talk has not been enabled.

Parameters

active

booleanRequired

Whether push-to-talk transmission is currently active.

Returns

void

Examples

Bind to a press-and-hold button

talkButton.addEventListener('pointerdown', () => call.setPushToTalkActive(true));
talkButton.addEventListener('pointerup',   () => call.setPushToTalkActive(false));
talkButton.addEventListener('pointercancel', () => call.setPushToTalkActive(false));

See

enablePushToTalk, install the pipeline (required first).
disablePushToTalk, tear down the pipeline.

signalingEvent$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get signalingEvent$(): Observable<Record<string, unknown>>

Observable of raw signaling events as plain objects.

Examples

call.signalingEvent$.subscribe((signalingEvent) => {
  console.log('signalingEvent:', signalingEvent);
});

startRecording

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startRecording(): Promise<void>

Starts a server-side recording of the call. The recording captures all media on the call and is available through the SignalWire dashboard once the call ends.

Not yet implemented in v4. This method is on the API surface and will throw when called. Recording state can already be observed via recording$; server-side recordings configured outside the SDK still reflect there correctly.

Returns

Promise<void>, once implemented, resolves after the server has begun recording.

Throws

Throws unconditionally, implementation pending.

See

recording$, observable of the current recording state.
startStreaming, the parallel live-streaming method, also not yet implemented.

startStreaming

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startStreaming(): Promise<void>

Starts a server-side live stream of the call to a configured destination (e.g. RTMP).

Not yet implemented in v4. This method is on the API surface and will throw when called. Streaming state can already be observed via streaming$; server-side streams started outside the SDK still reflect there correctly.

Returns

Promise<void>, once implemented, resolves after the server has begun streaming.

Throws

Throws unconditionally, implementation pending.

See

streaming$, observable of the current streaming state.
startRecording, the parallel recording method, also not yet implemented.

status$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get status$(): Observable<CallStatus>

Observable of the current call status (e.g. 'ringing', 'connected').

status

get status(): CallStatus

Current call status.

Examples

call.status$.subscribe((status) => {
  console.log('status:', status);
});

streaming$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get streaming$(): Observable<boolean>

Observable indicating whether the call is being streamed.

streaming

get streaming(): boolean

Whether the call is currently being streamed.

Examples

call.streaming$.subscribe((streaming) => {
  console.log('streaming:', streaming);
});

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

subscribe(eventType): Observable<Record<string, unknown>>

Subscribe to a custom signaling event type on this call.

Returns a cached observable that filters callSessionEvents$ for events whose event_type matches the given string. The observable completes when the call is destroyed.

Unlike signalingEvent$ (which only emits known call-level event types), this method also matches custom/user-defined event types.

The SDK does not validate event type strings --- the server decides whether a given type is valid.

Parameters

eventType

stringRequired

The event type to subscribe to (e.g. 'my.custom.event').

Returns

Observable<Record<string, unknown>>

An observable that emits matching signaling events.

Examples

call.subscribe('my.custom.event').subscribe(event => {
  console.log('Custom event:', event);
});

toName

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get toName(): string | undefined

Display name of the callee.

Examples

console.log(call.toName);

toggleHold

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleHold(): Promise<void>

Toggles the call between active and on-hold. When on hold, the local peer stops sending audio and video, and the remote side typically hears hold music played by the server.

Hold is a call-level state distinct from per-track muting. To silence just the local microphone without affecting the call’s hold status, use the Participant audio-mute methods on call.self.

The action requires the hold capability on the call, inspect call.capabilities$ before exposing the control in your UI.

Returns

Promise<void>, resolves once the server has acknowledged the state change.

Examples

Toggle on a button click

holdButton.addEventListener('click', async () => {
  await call.toggleHold();
});

Conditional UI based on capability

import { combineLatest } from 'rxjs';

combineLatest([call.capabilities$, call.status$]).subscribe(([caps, status]) => {
  holdButton.disabled = !caps.includes('hold') || status !== 'connected';
});

toggleIncomingAudio

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleIncomingAudio(): Promise<void>

Toggles whether the local peer receives incoming audio from the call. When disabled, the local participant continues to send audio (if not muted) but discards the remote audio stream.

Not yet implemented in v4. This method is on the API surface and will throw when called. See toggleIncomingVideo for the parallel video method, also not yet implemented.

Returns

Promise<void>, once implemented, resolves after the server has acknowledged the state change.

Throws

Throws unconditionally, implementation pending.

See

toggleIncomingVideo, the parallel video toggle.

toggleLock

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleLock(): Promise<void>

Toggles the call’s locked state. While locked, the server rejects new join requests; participants already on the call are unaffected. Useful for closing the door on a meeting once everyone expected has arrived.

The current state is reflected by locked$. Requires the lock capability, inspect call.capabilities$ before exposing the control in your UI.

Returns

Promise<void>, resolves once the server has acknowledged the state change.

Examples

Toggle from a UI button

lockButton.addEventListener('click', async () => {
  await call.toggleLock();
});

Reflect lock state in the UI

call.locked$.subscribe((locked) => {
  lockButton.textContent = locked ? 'Unlock' : 'Lock';
});

See

locked$, observable of the current lock state.

transfer

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

transfer(options): Promise<void>

Blind-transfers the remote party to another destination. The local side drops out of the call once the transfer is accepted by the server; the remote party continues at the new destination.

Use a directory URI for fabric-internal targets (e.g. /public/support), a SIP URI for SIP-routed transfers, or any other dialable string the server understands. The request is rejected if the local participant lacks the transfer capability, inspect call.capabilities$ first.

Parameters

options

TransferOptionsRequired

Transfer configuration. The required destination field is the dialable target, a fabric URI, SIP URI, or any string the server’s dial plan understands. See TransferOptions.

Returns

Promise<void>, resolves when the server has accepted the transfer request. The local call will subsequently transition to disconnected.

Examples

Transfer to a queue

await call.transfer({ destination: '/public/support-queue' });

Transfer to a SIP URI

await call.transfer({ destination: 'sip:agent@example.com' });

Transfer with error handling

try {
  await call.transfer({ destination: '/public/support-queue' });
} catch (err) {
  console.error('transfer rejected:', err);
}

See

status$ to observe the local call’s progression after transfer.
capabilities$ to check whether transfer is currently permitted.

updateMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMeta(_meta): Promise<void>

Merges the provided keys into the call’s custom metadata bag, preserving existing keys not mentioned in _meta. To replace the entire bag instead, use setMeta.

The merged metadata is observed via call.meta$ on all connected peers.

Not yet implemented in v4. This method is on the API surface and will throw when called.

Parameters

_meta

Record<string, unknown>Required

Keys to merge into the metadata bag. Other existing keys are preserved.

Returns

Promise<void>, once implemented, resolves after the server has propagated the merged metadata.

Throws

Throws unconditionally, implementation pending.

See

setMeta, full-replace alternative.
meta$, observable of the current metadata.

userVariables$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get userVariables$(): Observable<Record<string, unknown>>

Observable of custom user variables associated with the call.

userVariables

get userVariables(): Record<string, unknown>
set userVariables(variables): void

a copy of the current custom user variables of the call.

Parameters

variables

Record<string, unknown>Required

User-variable key/value pairs to merge into the call.

Merge current custom user variables of the call.

Examples

call.userVariables$.subscribe((userVariables) => {
  console.log('userVariables:', userVariables);
});

webrtcMessages$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get webrtcMessages$(): Observable<WebrtcMessagePayload>

Examples

call.webrtcMessages$.subscribe((webrtcMessages) => {
  console.log('webrtcMessages:', webrtcMessages);
});

Call

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

A Call represents a one-to-one call with another browser, a SIP endpoint, or even a phone number. The Call object supports both audio and video.

Properties

Name	Type	Description
`id`	`string`	The identifier of the call.
`direction`	`string`	The direction of the call. Can be either `inbound` or `outbound`.
`state`	`string`	The state of the call. See State for all the possible call states.
`prevState`	`string`	The previous state of the call. See State for all the possible call states.
`localStream`	`MediaStream`	The local stream of the call. This can be used in a video/audio element to play the local media.
`remoteStream`	`MediaStream`	The remote stream of the call. This can be used in a video/audio element to play the remote media.

State

The state and prevState properties of a Call have the following values:

Value	Description
`new`	New Call has been created in the client.
`trying`	You are attempting to call someone.
`requesting`	Your outbound call is being sent to the server.
`recovering`	Your previous call is recovering after the page refresh. If you refresh the page during a call, you will automatically be joined with the latest call.
`ringing`	Someone is attempting to call you.
`answering`	You are attempting to answer the inbound Call.
`early`	You received the media before the Call has been answered.
`active`	Call has become active.
`held`	Call has been held.
`hangup`	Call has ended.
`destroy`	Call has been destroyed.
`purge`	Call has been purged.

Methods

answer

Start the process to answer the incoming Call.

Parameters

None

Returns

None

Example

call.answer()

deaf

Turn off the audio input track.

Example

call.deaf()

dtmf

Send a Dual Tone Multi Frequency (DTMF) string to RELAY.

Parameters

Name	Type	Required	Description
`string`	`string`	required	`DTMF` to send.

Returns

None

Examples

call.dtmf('0')

hangup

Hangs up the call.

Parameters

None

Returns

None

Examples

call.hangup()

hold

Holds the call.

Parameters

None

Returns

None

Examples

call.hold()

muteAudio

Turn off the audio output track.

Example

call.muteAudio()

muteVideo

Turn off the video output track.

Example

call.muteVideo()

setAudioInDevice

Change the audio input device used for the Call.

Example

// within an async function ..
const success = await call.setAudioInDevice('d346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398')
if (success) {
  // The Call audio input has been set to the device 'd346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398'
} else {
  // The browser does not support the .setSinkId() API..
}

setAudioOutDevice

Change the audio output device used for the Call.

Example

// within an async function ..
const success = await call.setAudioOutDevice('d346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398')
if (success) {
  // The Call audio has been redirect to the device 'd346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398'
} else {
  // The browser does not support the .setSinkId() API..
}

setVideoDevice

Change the video output device used for the Call.

Example

// within an async function ..
const success = await call.setVideoDevice('d346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398')
if (success) {
  // The Call video has been redirect to the device 'd346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398'
} else {
  // The browser does not support the .setSinkId() API..
}

toggleAudioMute

Toggle the audio output track.

Example

call.toggleAudioMute()

toggleHold

Toggles the hold state of the call.

Parameters

None

Returns

None

Examples

call.toggleHold()

toggleVideoMute

Toggle the video output track.

Example

call.toggleVideoMute()

undeaf

Turn on the audio input track.

Example

call.undeaf()

unhold

Un-holds the call.

Parameters

None

Returns

None

Examples

call.unhold()

unmuteAudio

Turn on the audio output track.

Example

call.unmuteAudio()

unmuteVideo

Turn on the video output track.

Example

call.unmuteVideo()

Notification

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

A notification is an event that SignalWire dispatches to notify the Client about different cases. A notification can refer to the JWT expiration, Call changes or Conference updates.

Types

Every notification has a property type that identify the case and the structure of the data.

The available type are:

Value	Description
`refreshToken`	The JWT is going to expire. Refresh it or your session will be disconnected.
`callUpdate`	A Call’s state has been changed. Update the UI accordingly.
`participantData`	New participant’s data (i.e. name, number) to update the UI.
`userMediaError`	The browser does not have permission to access media devices. Check the `audio` and `video` constraints you are using.

refreshToken

Your JWT is going to expire. Refresh it or your session will be disconnected.

Anatomy of a refreshToken notification.

{
  type: 'refreshToken',
  session: RelayInstance
}

callUpdate

A Call’s state has been changed. It is useful to update the UI of your application.s

Anatomy of a callUpdate notification.

{
  type: 'callUpdate',
  call: CallObject
}

participantData

This notification contains the participant data for the current Call. This is useful when updating the UI.

Anatomy of a participantData notification.

{
  type: 'participantData',
  call: CallObject,
  displayName: 'David Roe',
  displayNumber: '1777888800'
  displayDirection: 'inbound'
}

userMediaError

The browser lacks of permissions to access microphone or webcam. You should check which audio/video constraints you are using and make sure they are supported by the browser.

Anatomy of a userMediaError notification.

{
  type: 'userMediaError',
  error: error
}

RELAY Client

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Relay client is the basic connection to RELAY, allowing you send commands to RELAY and setup handlers for inbound events.

Constructor

Constructs a client object to interact with RELAY.

Parameters

Name	Type	Required	Description
`project`	`string`	required	Project ID from your SignalWire Space
`token`	`string`	required	Json Web Token retrieved using Rest API. See Generate a JWT for more information.

Examples

Create a Client to interact with the RELAY API.

const client = new Relay({
  project: 'my-project-id',
  token: 'my-jwt',
})

client.on('signalwire.ready', (client) => {
  // You are connected with Relay!
})

client.connect()

Properties

Name	Type	Description
`connected`	`boolean`	`true` if the client has connected to RELAY.
`expired`	`boolean`	`true` if the JWT has expired.

Devices and Media Constraints

You can configure the devices your client will use by default with these properties and methods:

Name	Type	Description
`devices`	`object`	All devices recognized by the client keyed by kind: `videoinput`, `audioinput` and `audiooutput`.
`videoDevices`	`object`	DEPRECATED: Video devices recognized by the client.
`audioInDevices`	`object`	DEPRECATED: Audio input devices recognized by the client.
`audioOutDevices`	`object`	DEPRECATED: Audio output devices recognized by the client.
`mediaConstraints`	`object`	Current audio/video constraints used by the client.
`speaker`	`string`	Audio output device used by the client.
`speaker`	`string`	Set the audio output device to use for the subsequent calls.

Examples

If present, use the first audio output device as default speaker.

const speakerList = client.audioOutDevices.toArray()
if (speakerList.length) {
  client.speaker = speakerList[0].deviceId
}

Local and Remote Elements

It is usual, in a WebRTC application, to display the local and remote videos in a video-call. In the case of an audio-only call you will need at least the audio element to play the media.

Name	Type	Description
`localElement`	`HTMLMediaElement`	Current element used by the client to display the local stream.
`localElement`	`HTMLMediaElement`, `string` or `Function`	It accepts an `HTMLMediaElement`, the `ID` of the element as a `string` or a `Function` that returns an `HTMLMediaElement`.
`remoteElement`	`HTMLMediaElement`	Current element used by the client to display the remote stream.
`remoteElement`	`HTMLMediaElement`, `string` or `Function`	It accepts an `HTMLMediaElement`, the `ID` of the element as a `string` or a `Function` that returns an `HTMLMediaElement`.

Note: the client will attach the streams to the proper element but will not change the style attribute. You can decide if you would like to display or hide the HTMLMediaElement following the application logic.
Use the callUpdate notification to detect call state changes and update the UI accordingly.

STUN/TURN Servers

Through the iceServers you can set/retrieve the default ICE server configuration for all subsequent calls.

Name	Type	Description
`iceServers`	`RTCIceServers`	Current ICE servers used by the client.
`iceServers`	`RTCIceServers[]` or `boolean`	`array` of ICE servers, `true` to use the default ones or `false` to not use STUN/TURN at all.

Examples

Use both STUN and TURN for the client.

client.iceServers = [\
  {\
    urls: 'stun:stun.example.domain.com'\
  },\
  {\
    urls: 'turn:turn.example.domain.com',\
    username: '<turn-username>',\
    credential: '<turn-password>'\
  }\
]

Methods

checkPermissions

The first time a user visits your page, before access his microphone or webcam, the browser display a notification to the user. Use this method if you want to check you already have the permission to access them.

Parameters

Name	Type	Required	Description
`audio`	`boolean`	optional	Whether to check permissions for the microphone.<br>Default to true
`video`	`boolean`	optional	Whether to check permissions for the webcam.<br>Default to true

Returns

Promise<boolean> - A Promise object resolved with a boolean value.

Examples

Check both audio and video permissions.

// within an async function ..
const success = await client.checkPermissions()
if (success) {
  // User gave the permission..
} else {
  // User didn't gave the permission..
}

connect

Activates the connection to RELAY. Make sure you have attached the listeners you need before connecting the client, or you might miss some events.

Returns

Promise<void>

Examples

await client.connect()

disconnect

Disconnect the client from RELAY.

Returns

void

Examples

client.disconnect()

disableMicrophone

Disable the use of the microphone for the subsequent calls.

disableWebcam

Disable the use of the webcam for the subsequent calls.

enableMicrophone

Enable the use of the microphone for the subsequent calls.

enableWebcam

Enable the use of the webcam for the subsequent calls.

getAudioInDevices

Return all audioinput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List microphones.

// within an async function ..
const devices = await client.getAudioInDevices()
devices.forEach(device => {
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
})

getAudioOutDevices

Return all audiooutput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List speakers.

// within an async function ..
const devices = await client.getAudioOutDevices()
devices.forEach(device => {
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
})

getDeviceResolutions

Return a list of supported resolutions for the given webcam (deviceId).

Parameters

Name	Type	Required	Description
`deviceId`	`string`	required	Device ID to be checked.

Returns

Promise<Array> - A Promise object resolved with a list of supported resolutions.

Examples

Check both audio and video permissions.

// within an async function ..
const resolutions = await client.getDeviceResolutions('d346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398')

[\
  {\
    "resolution": "320x240",\
    "width": 320,\
    "height": 240\
  },\
  {\
    "resolution": "640x360",\
    "width": 640,\
    "height": 360\
  },\
  {\
    "resolution": "640x480",\
    "width": 640,\
    "height": 480\
  },\
  {\
    "resolution": "1280x720",\
    "width": 1280,\
    "height": 720\
  }\
]

getDevices

Return all devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List all devices.

// within an async function ..
const devices = await client.getDevices()
devices.forEach(device => {
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
})

getVideoDevices

Return all videoinput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List webcams.

// within an async function ..
const devices = await client.getVideoDevices()
devices.forEach(device => {
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
})

newCall

Make a new outbound call.

Parameters

Name	Type	Required	Description
`options`	`object`	required	Object with the following properties:
`destinationNumber`	`string`	required	Extension to dial.
`callerNumber`	`string`	optional	Number to use as the caller ID when dialling out to a phone number.<br>Must be a SignalWire number that you own.
`id`	`string`	optional	The identifier of the Call.
`localStream`	`string`	optional	If set, the Call will use this stream instead of retrieving a new one. Useful if you already have a MediaStream from a `canvas.captureStream()` or a screen share extension.
`localElement`	`string`	optional	Overrides client’s default `localElement`.
`remoteElement`	`string`	optional	Overrides client’s default `remoteElement`.
`iceServers`	`RTCIceServers[]`	optional	Overrides client’s default `iceServers`.
`audio`	`MediaStreamConstraints`	optional	Overrides client’s default `audio` constraints.
`video`	`MediaStreamConstraints`	optional	Overrides client’s default `video` constraints.
`useStereo`	`boolean`	optional	Use stereo audio instead of mono.
`micId`	`string`	optional	`deviceId` to use as microphone. <br>Overrides the client’s default one.
`camId`	`string`	optional	`deviceId` to use as webcam. <br>Overrides the client’s default one.
`speakerId`	`string`	optional	`deviceId` to use as speaker. <br>Overrides the client’s default one.
`onNotification`	`string`	optional	Overrides client’s default `signalwire.notification` handler for this Call.

Returns

Promise<Call> - A Promise fulfilled with the new outbound Call object or rejected with the error.

Examples

Make an outbound call to +1 202-555-0122 using default values from the Client.

// within an async function ..
const options = { destinationNumber: '+12025550122' }
const call = await client.newCall(options).catch(console.error)

on

Attach an event handler for a specific type of event.

Parameters

Name	Type	Required	Description
`event`	`string`	required	Event name. Full list of events `Relay` Events
`handler`	`function`	required	Function to call when the event comes.

Returns

Relay - The client object itself.

Examples

Subscribe to the signalwire.ready and signalwire.error events.

client.on('signalwire.ready', (client) => {
  // Your client is ready!
}).on('signalwire.error', (error) => {
  // Got an error...
})

off

Remove an event handler that were attached with .on(). If no handler parameter is passed, all listeners for that event will be removed.

Parameters

Name	Type	Required	Description
`event`	`string`	required	Event name. Full list of events `Relay` Events
`handler`	`function`	optional	Function to remove. <br>Note: `handler` will be removed from the stack by reference so make sure to use the same reference in both `.on()` and `.off()` methods.

Returns

Relay - The client object itself.

Examples

Subscribe to the signalwire.error and then, remove the event handler.

const errorHandler = (error) => {
  // Log the error..
}

client.on('signalwire.error', errorHandler)

// .. later
client.off('signalwire.error', errorHandler)

refreshDevices

DEPRECATED: Use getDevices instead.

Refresh the devices and return a Promise fulfilled with the new devices.

Parameters

None

Returns

Promise<devices> - New devices object.

Examples

Refresh client’s devices with async/await syntax.

// within an async function
const devices = await client.refreshDevices()

refreshToken

When the JWT is going to expire, the Client dispatch a notification with type refreshToken that allows you to refresh the token and keep your session alive.

Parameters

Name	Type	Required	Description
`token`	`string`	required	New JWT to keep your session alive.

Returns

Promise<void>

Examples

Listen for all notifications and, on refreshToken, fetch a new JWT from your backend and update the token on the client.

client.on('signalwire.notification', function(notification) {
  switch (notification.type) {

    case 'refreshToken':
      // Take a new token from your server...
      xhrRequestToRefreshYourJWT().then(async (newToken) => {
        await client.refreshToken(newToken).catch(console.error)
      })
    break

  }
})

setAudioSettings

You can set the default audio constraints for your client. See here for further details.

Note: It’s a common behaviour, in WebRTC applications, to persist devices user’s selection to then reuse them across visits.
Due to a Webkit’s security protocols, Safari generates random deviceId on each page load.
To avoid this issue you can specify two additional properties (micId and micLabel) in the constraints input parameter.
The client will use these values to assure the microphone you want to use is available by matching both id and label with the device list retrieved from the browser.

Parameters

Name	Type	Required	Description
`constraints`	`MediaTrackConstraints`	required	`MediaTrackConstraints` object with the addition of `micId` and `micLabel`.

Returns

Promise<MediaTrackConstraints> - Audio constraints applied to the client.

Examples

Set microphone by id and label with the echoCancellation flag turned off.

// within an async function
const constraints = await client.setAudioSettings({
  micId: '229d4c8838a2781e3668eb173fea2622b34fbf6a9deec19ee5caeb0916839520',
  micLabel: 'Internal Microphone (Built-in)',
  echoCancellation: false
})

setVideoSettings

You can set the default video constraints for your client. See here for further details.

Note: It’s a common behaviour, in WebRTC applications, to persist devices user’s selection to then reuse them across visits.
Due to a Webkit’s security protocols, Safari generates random deviceId on each page load.
To avoid this issue you can specify two additional properties (camId and camLabel) in the constraints input parameter.
The client will use these values to assure the webcam you want to use is available by matching both id and label with the device list retrieved from the browser.

Parameters

Name	Type	Required	Description
`constraints`	`MediaTrackConstraints`	required	`MediaTrackConstraints` object with the addition of `camId` and `camLabel`.

Returns

Promise<MediaTrackConstraints> - Video constraints applied to the client.

Examples

Set webcam by id and label with 720p resolution.

// within an async function
const constraints = await client.setVideoSettings({
  camId: '229d4c8838a2781e3668eb173fea2622b34fbf6a9deec19ee5caeb0916839520',
  camLabel: 'Internal Webcam (Built-in)',
  width: 1080,
  height: 720
})

Events

All available events you can attach a listener on.

Name	Description
`signalwire.ready`	The session has been established and all other methods can now be used.
`signalwire.error`	There is an error dispatch at the session level.
`signalwire.notification`	A notification from SignalWire. Notifications can refer to calls or session updates.
`signalwire.socket.open`	The websocket is open. However, you have not yet been authenticated.
`signalwire.socket.error`	The websocket gave an error.
`signalwire.socket.message`	The client has received a message from the websocket.
`signalwire.socket.close`	The websocket is closing.

SignalWire Browser SDK ​

Install ​

Classes ​

Credential Providers ​

Errors ​

Functions ​

Variables ​

ready ​

version ​

Address ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

addressId ​

conversationManager ​

addressProvider ​

Properties ​

history$ ​

textMessages$ ​

Accessors ​

Methods ​

activity$ ​

Throws ​

activity ​

Throws ​

Examples ​

channels$ ​

channels ​

audio? ​

messaging? ​

video? ​

Examples ​

coverUrl$ ​

coverUrl ​

Examples ​

createdAt ​

Examples ​

defaultChannel ​

Examples ​

destroy ​

Returns ​

Inherited from ​

Examples ​

destroyed$ ​

Inherited from ​

Examples ​

displayName$ ​

displayName ​

Examples ​

history ​

See ​

Examples ​

id ​

Examples ​

locked$ ​

locked ​

Examples ​

name ​

Examples ​

previewUrl$ ​

previewUrl ​

Examples ​

resourceId$ ​

resourceId ​

Examples ​

sendText ​

Parameters ​

text ​

Returns ​

Examples ​

See ​

textMessage ​

See ​

Examples ​

type$ ​

type ​

Examples ​

ClientPreferences ​

Constructors ​

SignalWire Browser SDK

Install

Classes

Credential Providers

Errors

Functions

Variables

ready

version

Address

Extends

Constructors

Constructor

Parameters

addressId

conversationManager

addressProvider

Properties

history$

textMessages$

Accessors

Methods

activity$

Throws

activity

Throws

Examples

channels$

channels

audio?

messaging?

video?

Examples

coverUrl$

coverUrl

Examples

createdAt

Examples

defaultChannel

Examples

destroy

Returns

Inherited from

Examples

destroyed$

Inherited from

Examples

displayName$

displayName

Examples

history

See

Examples

id

Examples

locked$

locked

Examples

name

Examples

previewUrl$

previewUrl

Examples

resourceId$

resourceId

Examples

sendText

Parameters

text

Returns

Examples

See

textMessage

See

Examples

type$

type

Examples

ClientPreferences

Constructors