IClientOptions

Options passed to the TelnyxRTC constructor to configure the client.

Quick Reference

import { TelnyxRTC } from '@telnyx/webrtc';

const client = new TelnyxRTC({
 login_token: 'YOUR_JWT_TOKEN', // Authentication (required)
 enableCallReports: true, // Call quality monitoring (default: true)
 debug: false, // Debug output
});

Authentication

Choose one authentication method. See Authentication for the full guide.

Property	Type	Required	Description
`login_token`	`string`	(if using JWT)	JWT token for authentication. Recommended for production. Generate from your backend via `POST /v2/telephony_credentials/{id}/token`. Valid for 24 hours.
`login`	`string`	(if using credentials)	SIP username (from Telephony Credential). Development only.
`password`	`string`	(if using credentials)	SIP password. Development only.
`anonymous_login`	`object`	(if anonymous)	Connect to an AI assistant without credentials. See Anonymous Login.

Use login_token (JWT) for production applications. Credentials (login + password) are long-lived with no automatic rotation. JWTs expire after 24 hours and support refresh. See Authenticating Your App.

JWT (production):

const client = new TelnyxRTC({
 login_token: jwt,
});

Credential (development only):

const client = new TelnyxRTC({
 login: 'gencred...',
 password: 'your-password',
});

Connect to an AI assistant without requiring a credential. The anonymous_login option accepts an object with the target configuration:

const client = new TelnyxRTC({
 anonymous_login: {
 target_type: 'ai_assistant', // Currently the only supported type
 target_id: 'YOUR_AI_ASSISTANT_ID', // The AI assistant to connect to
 },
});

Property	Type	Required	Description
`target_type`	`string`		The target type. Currently only `'ai_assistant'` is supported.
`target_id`	`string`		The ID of the AI assistant to connect to.
`target_version_id`	`string`	—	A specific version of the AI assistant.
`target_params`	`object`	—	Optional parameters forwarded to the assistant. Known key: `conversation_id` (string) to join an existing conversation. Additional keys are passed through as-is.

Example — Continue a conversation:

const client = new TelnyxRTC({
 anonymous_login: {
 target_type: 'ai_assistant',
 target_id: 'asst_abc123',
 target_params: {
 conversation_id: 'conv_xyz789', // Resume existing conversation
 },
 },
});

Connection

Control WebSocket, reconnection, and region behavior.

Property	Type	Default	Description
`env`	`string`	—	Custom signaling server URL. Override `rtc.telnyx.com`. Only use for testing.
`region`	`Region` \| `string`	—	Region to use for the connection. Pass one of the exported `Region` values, or omit for automatic routing. Arbitrary strings remain supported for backwards compatibility.
`keepConnectionAliveOnSocketClose`	`boolean`	`false`	Keep PeerConnection alive during WebSocket reconnection. Call media continues flowing while signaling reconnects.
`skipLastVoiceSdkId`	`boolean`	`false`	When reconnecting with a stored `voice_sdk_id`, route 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 node.
`rtcIp`	`string`	—	Custom RTC connection IP address. Useful when using a custom signaling server.
`rtcPort`	`number`	—	Custom RTC connection port. Useful when using a custom signaling server.
`useCanaryRtcServer`	`boolean`	`false`	Use Telnyx’s canary RTC server.

The SDK automatically reconnects when the WebSocket drops. There is no reconnect option — reconnection is always automatic.

Select a region:

import { TelnyxRTC, Region } from '@telnyx/webrtc';

const client = new TelnyxRTC({
  login_token: jwt,
  region: Region.US_EAST, // or EU, US_CENTRAL, US_WEST, CA_CENTRAL, APAC, SOUTH_ASIA
});

// Omit `region` to use automatic routing (default)
const autoClient = new TelnyxRTC({
  login_token: jwt,
});

Enable call recovery:

const client = new TelnyxRTC({
 login_token: jwt,
 keepConnectionAliveOnSocketClose: true,
});

Supported regions

The SDK exports a Region constant with the seven supported signaling regions. Pass one of these values to region, or omit the option to use automatic routing.

`Region` value	Region
`Region.EU`	Europe
`Region.US_CENTRAL`	US Central
`Region.US_EAST`	US East
`Region.US_WEST`	US West
`Region.CA_CENTRAL`	Canada Central
`Region.APAC`	Asia-Pacific
`Region.SOUTH_ASIA`	South Asia

import { TelnyxRTC, Region } from '@telnyx/webrtc';

const client = new TelnyxRTC({
  login_token: jwt,
  region: Region.US_EAST,
});

Arbitrary strings remain supported for backwards compatibility, but using the exported Region values ensures you target a valid signaling region.

ICE & Network

Configure STUN/TURN and ICE behavior.

Property	Type	Default	Description
`iceServers`	`RTCIceServer[]`	Auto-provisioned	Custom ICE servers. Overrides SDK defaults. Only use if you have custom TURN infrastructure.
`prefetchIceCandidates`	`boolean`	`true`	Pre-gather ICE candidates before the call is placed. Reduces call setup time.
`forceRelayCandidate`	`boolean`	`false`	Force all media through TURN relay servers. Hides the client’s public IP but adds latency.
`trickleIce`	`boolean`	—	Enable Trickle ICE. Sends candidates incrementally instead of waiting for full gathering. Faster call setup.
`mutedMicOnStart`	`boolean`	—	Start with microphone muted by default.

The SDK automatically provisions STUN/TURN servers. You don’t need to configure iceServers in most cases. See Network Requirements.

Force TURN for privacy:

const client = new TelnyxRTC({
 login_token: jwt,
 forceRelayCandidate: true, // All media through TURN
});

Custom ICE servers:

const client = new TelnyxRTC({
 login_token: jwt,
 iceServers: [
 { urls: 'stun:stun.custom.com:3478' },
 {
 urls: 'turn:turn.custom.com:443?transport=udp',
 username: 'myuser',
 credential: 'mypass',
 },
 ],
});

Audio

Property	Type	Default	Description
`ringtoneFile`	`string`	—	URL of a wav/mp3 file to play as the incoming call ringtone.
`ringbackFile`	`string`	—	URL of a wav/mp3 file to play as ringback tone. Use when you’ve disabled “Generate Ringback Tone” in your SIP Connection configuration.

Custom ringtone and ringback:

const client = new TelnyxRTC({
 login_token: jwt,
 ringtoneFile: './sounds/incoming_call.mp3',
 ringbackFile: './sounds/ringback_tone.mp3',
});

Call Reports

Enable post-call quality monitoring and real-time stats.

Property	Type	Default	Description
`enableCallReports`	`boolean`	`true`	Enable call reports with WebRTC stats (RTT, jitter, packet loss, ICE data).
`callReportInterval`	`number`	`5000`	Interval in milliseconds between `telnyx.stats.frame` events during calls.

Call reports are enabled by default. You can customize the interval:

const client = new TelnyxRTC({
 login_token: jwt,
 callReportInterval: 3000, // Stats every 3 seconds
});

Listen for stats:

client.on('telnyx.stats.frame', (stats) => {
 console.log('RTT:', stats.rtt, 'Jitter:', stats.jitter);
});

client.on('telnyx.stats.report', (report) => {
 console.log('Call ended. Final report:', report);
});

See Monitor Call Quality for the full data schema.

Debugging

Configure debug output for troubleshooting.

Property	Type	Default	Description
`debug`	`boolean`	`false`	Enable debug logging. Outputs SDK internal logs to the browser console.
`debugOutput`	`'socket' \| 'file'`	—	Where to send debug output. `'socket'` sends to the debug visualizer at `https://webrtc-debug.telnyx.com/`. `'file'` writes debug data to a file.

Enable console debug logging:

const client = new TelnyxRTC({
 login_token: jwt,
 debug: true,
});

Send to debug visualizer:

const client = new TelnyxRTC({
 login_token: jwt,
 debug: true,
 debugOutput: 'socket', // View at https://webrtc-debug.telnyx.com/
});

Write debug data to a file:

const client = new TelnyxRTC({
 login_token: jwt,
 debug: true,
 debugOutput: 'file',
});

See Debug Call Issues for interpreting debug output.

Media Permissions Recovery

Handle microphone permission failures for inbound calls with a recoverable error pattern.

Property	Type	Default	Description
`mediaPermissionsRecovery.enabled`	`boolean`	`false`	Enable the recovery flow.
`mediaPermissionsRecovery.timeout`	`number`	—	Maximum time in ms to wait for the app to call `resume()` or `reject()`. Recommended max: 25000.
`mediaPermissionsRecovery.onSuccess`	`() => void`	—	Called when retry `getUserMedia` succeeds after `resume()`.
`mediaPermissionsRecovery.onError`	`(error: Error) => void`	—	Called when retry fails, timeout expires, or app calls `reject()`.

When enabled and getUserMedia fails while answering an inbound call, the SDK emits a recoverable telnyx.error event with resume() and reject() callbacks. Your app can prompt the user to fix permissions before the call fails:

import { TelnyxRTC, isMediaRecoveryErrorEvent } from '@telnyx/webrtc';

const client = new TelnyxRTC({
 login_token: jwt,
 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)) {
 showPermissionDialog({
 onContinue: () => event.resume(),
 onCancel: () => event.reject?.(),
 });
 }
});

Full Example

import { TelnyxRTC } from '@telnyx/webrtc';

const client = new TelnyxRTC({
 // Authentication
 login_token: 'YOUR_JWT_TOKEN',

 // Connection recovery
 keepConnectionAliveOnSocketClose: true,

 // Media recovery for inbound calls
 mediaPermissionsRecovery: {
 enabled: true,
 timeout: 20000,
 },

 // Call reports (enabled by default)
 callReportInterval: 5000,

 // ICE optimization
 prefetchIceCandidates: true,
 trickleIce: true,
});

client.on('telnyx.ready', () => {
 console.log('Connected');
});

client.on('telnyx.error', (error) => {
 console.error('Error:', error.code, error.message);
});

client.connect();

Getting Started

Authentication

Push Notifications

Tutorials

Use Cases

Troubleshooting

SDKs

API Reference

For AI Agents

IClientOptions

IClientOptions

Quick Reference

Authentication

Connection

Supported regions

ICE & Network

Audio

Call Reports

Debugging

Media Permissions Recovery

Full Example

See Also

​IClientOptions

​Quick Reference

​Authentication

​Anonymous Login

​Connection

​Supported regions

​ICE & Network

​Audio

​Call Reports

​Debugging

​Media Permissions Recovery

​Full Example

​See Also

IClientOptions

Quick Reference

Authentication

Anonymous Login

Connection

Supported regions

ICE & Network

Audio

Call Reports

Debugging

Media Permissions Recovery

Full Example

See Also