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.

​
TelnyxRTC

The TelnyxRTC class is the main entry point for the Telnyx WebRTC JS SDK. It manages the WebSocket connection to Telnyx’s signaling server and provides methods to create calls, handle events, and control the client lifecycle.

​
Constructor

new TelnyxRTC(options: IClientOptions)
Creates a new client instance. Does not connect automatically — call connect() to establish the WebSocket connection. Parameters:
ParameterTypeRequiredDescription
optionsIClientOptionsYesClient configuration
Example: 
import { TelnyxRTC } from '@telnyx/webrtc';

const client = new TelnyxRTC({
  login_token: 'YOUR_JWT_TOKEN',
  // Optional: see IClientOptions for all options
  debug: false,
  enableCallReports: true,
});

​
Methods

​
connect()

Opens a WebSocket connection to rtc.telnyx.com and authenticates using the configured credentials. 
client.connect();
Fires telnyx.ready on success or telnyx.error on failure.

​
disconnect()

Closes the WebSocket connection and cleans up all active calls. 
client.disconnect();
Always call disconnect() when the user leaves your app to avoid zombie WebSocket connections. See Best Practices → Connection Lifecycle.

​
newCall(options)

Creates and places a new outbound call. 
const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});
Parameters:
ParameterTypeRequiredDescription
optionsICallOptionsYesCall configuration
Returns: Call See ICallOptions for all available options including custom headers, ICE configuration, and media settings.

​
off(event, handler)

Removes an event listener. 
const onReady = () => { /* ... */ };
client.on('telnyx.ready', onReady);
// Later:
client.off('telnyx.ready', onReady);

​
removeAllListeners()

Removes all event listeners from the client. 
client.removeAllListeners();

​
Properties

​
connection

Provides helpers to check the current connection state. 
client.connection.connecting  // true during WebSocket handshake
client.connection.connected   // true when WebSocket is open and authenticated
client.connection.closed      // true when WebSocket is closed
client.connection.isAlive     // true if connection is active
PropertyTypeDescription
connectingbooleanTrue during WebSocket handshake
connectedbooleanTrue when authenticated and ready
closedbooleanTrue when disconnected
isAlivebooleanTrue if connection is active

​
calls

An array of all active Call objects. 
// Check if any calls are active
if (client.calls.length > 0) {
  console.log(`Active calls: ${client.calls.length}`);
}

// Hang up all calls
client.calls.forEach(call => call.hangup());

​
Events

Register event listeners using client.on(eventName, handler): 
client.on('telnyx.ready', () => { /* ... */ });
client.on('telnyx.error', (error) => { /* ... */ });

​
Connection Events

EventPayloadDescription
telnyx.ready—Client connected and authenticated. Wait for this before making calls.
telnyx.errorClientErrorEventConnection or authentication error. See Error Handling.
telnyx.warningClientWarningEventNon-fatal warning (e.g., token expiring, quality degradation). See Warning Codes.
telnyx.socket.closeCloseEventWebSocket closed. SDK will attempt reconnection automatically.
telnyx.socket.errorEventWebSocket error.

​
Call Events

EventPayloadDescription
telnyx.notificationINotificationCall state updates, media events, and SDK notifications. This is the primary event for handling call lifecycle.

​
Stats Events

EventPayloadDescription
telnyx.stats.frameStatsFramePeriodic WebRTC stats (RTT, jitter, packet loss). Emitted every callReportInterval ms.
telnyx.stats.reportStatsReportEnd-of-call summary report. Emitted when a call ends.

​
Typical Usage

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

// 1. Create client with JWT
const client = new TelnyxRTC({
  login_token: 'YOUR_JWT_TOKEN',
  enableCallReports: true,
});

// 2. Register event handlers BEFORE connecting
client.on('telnyx.ready', () => {
  console.log('Connected! Ready to make calls.');
});

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

client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate') {
    const call = notification.call;
    switch (call.state) {
      case 'ringing':
        // Incoming call — show UI
        break;
      case 'active':
        // Call connected
        break;
      case 'hangup':
        // Call ended
        break;
    }
  }
});

client.on('telnyx.warning', (warning) => {
  console.warn('Warning:', warning.code, warning.message);
});

// 3. Connect
client.connect();

// 4. Make a call (after ready)
function makeCall(destination) {
  if (!client.connection.connected) {
    console.error('Not connected yet!');
    return;
  }
  const call = client.newCall({
    destinationNumber: destination,
    audio: true,
  });
}

// 5. Disconnect on cleanup
window.addEventListener('beforeunload', () => {
  client.disconnect();
});

​
Reconnection

The SDK automatically reconnects when the WebSocket drops. You don’t need to handle this manually in most cases. For advanced reconnection handling, see Reconnection & Recovery. Key configuration:
OptionDefaultDescription
keepConnectionAliveOnSocketClosefalseKeep PeerConnection alive during reconnect
mediaPermissionsRecovery—Auto-recover media permissions for inbound calls

​
See Also