Interface IClientOptions

anonymous_login login options

Endpoint path (relative to the SDK connection host) where recording payloads are POSTed. Defaults to /call_recording, which voice-sdk-proxy forwards to voice-sdk-debug. Override only if pointing at a custom recording endpoint.

Default

'/call_recording'
Copy

Interval in milliseconds between intermediate call-recording flushes. Every interval the recorder POSTs its buffered RTP packets to the /call_recording endpoint and clears the buffer. A final flush at end of call submits the tail. Set to a value small enough that one interval of audio (at the configured sample rate) stays below callRecordingMaxBufferBytes.

Default

240000 (4 minutes)
Copy

Hard cap in bytes on the in-memory call-recording packet buffer. On overflow the recorder drops the oldest packets and emits a RECORDING_BUFFER_OVERFLOW warning (once per flush window) so memory stays bounded regardless of call length.

Default

8000000 (8 MB)
Copy

Sample rate (Hz) advertised in the recording envelope sent to voice-sdk-debug. The captured Float32 PCM frames carry the track's actual sample rate; this value is what the server uses to interpret the payload. 48 kHz is the typical WebRTC audio track rate.

Default

48000
Copy

Which audio tracks to record. local is the outbound (microphone) track, remote is the inbound (remote party) track. By default both are recorded so a single .pcap captures both directions for full audio-quality diagnosis.

Default

['local', 'remote']
Copy

Interval in milliseconds for submitting intermediate call reports while a call is active. Set to 0 to disable time-based intermediate reports.

Default

180000 (3 minutes)
Copy

Interval in milliseconds for collecting call statistics after the initial high-resolution startup window. Stats are aggregated over each interval and submitted as intermediate reports while the call is active.

Default

5000 (5 seconds)
Copy

Enable debug mode for this client. This will gather WebRTC debugging information.

Debug output option

Enable client-side call recording of the raw audio payload (depacketized PCM) flowing through the active WebRTC audio tracks. When enabled, the SDK captures PCM via MediaStreamTrackProcessor (Chromium-only), synthesizes RTP packets, buffers them with a bounded in-memory ring buffer, and submits intermediate flushes every callRecordingFlushIntervalMs plus a final flush at end of call. Recordings are stored as .pcap files by voice-sdk-debug for Wireshark-based audio-quality diagnosis.

Browser support: Requires MediaStreamTrackProcessor (Chrome 94+, Edge 94+). Firefox and Safari are NOT supported — on those browsers the recorder logs a single RECORDING_UNAVAILABLE warning and no-ops for the rest of the call; the call itself is never affected.

Privacy / consent: Recording audio on the client requires user consent by law in most jurisdictions. The SDK does NOT request consent — applications that enable recording are responsible for the consent flow.

CPU cost: Two MediaStreamTrackProcessor instances per call add measurable CPU on lower-end devices. Recording is off by default; set enableCallRecording: true to opt in for deployments that need diagnostic recordings.

Default

false
Copy

Enable automatic call quality reporting to voice-sdk-proxy. When enabled, WebRTC stats are collected periodically during calls and posted to the voice-sdk-proxy /call_report endpoint when the call ends.

Default

true
Copy

Environment to use for the connection. So far this property is only for internal purposes.

Force the use of a relay ICE candidate.

Controls whether the SDK attempts to send BYE for active calls during browser page unload. Enabled by default to preserve graceful call cleanup, but applications that handle page lifecycle themselves can disable it to avoid best-effort unload BYE races.

Default

true
Copy

ICE Servers to use for all calls within the client connection. Overrides the default ones.

By passing keepConnectionAliveOnSocketClose as true, the SDK will attempt to keep Peer connection alive when the WebSocket connection is closed unexpectedly (e.g. network interruption, device sleep, etc).

The username to authenticate with your SIP Connection. login and password will take precedence over login_token for authentication.

The JSON Web Token (JWT) to authenticate with your SIP Connection. This is the recommended authentication strategy. See how to create one.

Maximum number of automatic socket reconnection attempts after an unexpected disconnect. When the limit is reached, no further automatic reconnects are scheduled and a telnyx.error event with code RECONNECTION_EXHAUSTED (45003) is emitted. A manual connect() call resets the counter and starts a fresh retry sequence.

Set to 0 to allow unlimited automatic reconnect attempts. When omitted, defaults to 10.

Default

10
Copy

Configuration for media permissions recovery on inbound calls. When enabled and the initial getUserMedia call fails while answering, the SDK emits a recoverable telnyx.error event with resume() and reject() callbacks so the app can prompt the user to fix permissions before the call fails.

Recovery is attempted only for inbound calls. If the app calls resume(), the SDK retries getUserMedia. If the app calls reject() or does not respond before timeout, recovery fails and the call is terminated with the usual media error flow.

In the recovery flow the emitted error carries event.recoverable === true (top-level) plus the resume/reject/retryDeadline helpers, and event.error.fatal === false (the SDK is actively handling recovery via the app's cooperation). Outside the recovery flow, media failures are terminal (event.error.fatal === true, no top-level recoverable).

Example

import {isMediaRecoveryErrorEvent} from "@telnyx/webrtc"

const client = new TelnyxRTC({
  login_token: '...',
  mediaPermissionsRecovery: {
    enabled: true,
    timeout: 20000,
    onSuccess: () => console.log('Media recovered'),
    onError: (err) => console.error('Recovery failed', err),
  },
});

client.on('telnyx.error', (event) => {
  if (isMediaRecoveryErrorEvent(event)) {
    // event.recoverable === true, event.error.fatal === false
    showPermissionDialog({
      onContinue: () => event.resume(),
      onCancel: () => event.reject?.(),
    });
  } else if (event.error.fatal) {
    // Terminal error — give up on this call/session
  }
});
Copy

Disabled microphone by default when the call starts or adding a new audio source.

The password to authenticate with your SIP Connection.

Enable or disable prefetching ICE candidates. Defaults to true.

When true, the backend sends mobile push notifications for incoming calls even while this browser has an active registration for the same credential, allowing browser and mobile clients to ring simultaneously.

Default

false
Copy

Region to use for the connection.

A URL to a wav/mp3 ringback file that will be used when you disable "Generate Ringback Tone" in your SIP Connection.

A URL to a wav/mp3 ringtone file.

RTC connection IP address to use instead of the default one. Useful when using a custom signaling server.

RTC connection port to use instead of the default one. Useful when using a custom signaling server.

When reconnecting with a stored voice_sdk_id, append ?skip_last_voice_sdk_id=true to the WebSocket URL so VSP routes the connection to a different b2bua-rtc instance instead of sticky- reconnecting to the same one. Useful when retrying after errors caused by stale state on a specific b2bua-rtc node.

Default

false
Copy

When set to true, appends skip_trailing=true to the VSP WebSocket URL so VSP skips pre-routing identity resolution (telephony-tokens validation and UsersClass trailing checks) for this connection.

This is intended for internal/test-infra usage (e.g. BBT-generated credentials) where the connection should not participate in trailing release routing. The actual login still goes to the upstream RTC service for normal authentication — this only skips VSP's pre-routing lookup used for trailing target selection.

Default

false
Copy

Enable or disable Trickle ICE.

Use Telnyx's Canary RTC server