Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
PropertyTypeRequiredDescription
login_tokenstring(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.
loginstring(if using credentials)SIP username (from Telephony Credential). Development only.
passwordstring(if using credentials)SIP password. Development only.
anonymous_loginobject(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',
});

Anonymous Login

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
 },
});
PropertyTypeRequiredDescription
target_typestringThe target type. Currently only 'ai_assistant' is supported.
target_idstringThe ID of the AI assistant to connect to.
target_version_idstringA specific version of the AI assistant.
target_paramsobjectOptional 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.
PropertyTypeDefaultDescription
envstringCustom signaling server URL. Override rtc.telnyx.com. Only use for testing.
regionstringRegion to use for the connection.
keepConnectionAliveOnSocketClosebooleanfalseKeep PeerConnection alive during WebSocket reconnection. Call media continues flowing while signaling reconnects.
skipLastVoiceSdkIdbooleanfalseWhen 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.
rtcIpstringCustom RTC connection IP address. Useful when using a custom signaling server.
rtcPortnumberCustom RTC connection port. Useful when using a custom signaling server.
useCanaryRtcServerbooleanfalseUse Telnyx’s canary RTC server.
The SDK automatically reconnects when the WebSocket drops. There is no reconnect option — reconnection is always automatic.
Enable call recovery:
const client = new TelnyxRTC({
 login_token: jwt,
 keepConnectionAliveOnSocketClose: true,
});

ICE & Network

Configure STUN/TURN and ICE behavior.
PropertyTypeDefaultDescription
iceServersRTCIceServer[]Auto-provisionedCustom ICE servers. Overrides SDK defaults. Only use if you have custom TURN infrastructure.
prefetchIceCandidatesbooleantruePre-gather ICE candidates before the call is placed. Reduces call setup time.
forceRelayCandidatebooleanfalseForce all media through TURN relay servers. Hides the client’s public IP but adds latency.
trickleIcebooleanEnable Trickle ICE. Sends candidates incrementally instead of waiting for full gathering. Faster call setup.
mutedMicOnStartbooleanStart 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

PropertyTypeDefaultDescription
ringtoneFilestringURL of a wav/mp3 file to play as the incoming call ringtone.
ringbackFilestringURL 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.
PropertyTypeDefaultDescription
enableCallReportsbooleantrueEnable call reports with WebRTC stats (RTT, jitter, packet loss, ICE data).
callReportIntervalnumber5000Interval 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.
PropertyTypeDefaultDescription
debugbooleanfalseEnable 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.
PropertyTypeDefaultDescription
mediaPermissionsRecovery.enabledbooleanfalseEnable the recovery flow.
mediaPermissionsRecovery.timeoutnumberMaximum time in ms to wait for the app to call resume() or reject(). Recommended max: 25000.
mediaPermissionsRecovery.onSuccess() => voidCalled when retry getUserMedia succeeds after resume().
mediaPermissionsRecovery.onError(error: Error) => voidCalled 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();

See Also