TelnyxRTC Class

Main entry point for the Telnyx WebRTC JS SDK. Connect, disconnect, and manage calls.

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:

Parameter	Type	Required	Description
options	IClientOptions	Yes	Client 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: '[phone]',
  audio: true,
});

Parameters:

Parameter	Type	Required	Description
options	ICallOptions	Yes	Call 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

Property	Type	Description
connecting	boolean	True during WebSocket handshake
connected	boolean	True when authenticated and ready
closed	boolean	True when disconnected
isAlive	boolean	True 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

Event	Payload	Description
telnyx.ready	—	Client connected and authenticated. Wait for this before making calls.
telnyx.error	ClientErrorEvent	Connection or authentication error. See Error Handling.
telnyx.warning	ClientWarningEvent	Non-fatal warning (e.g., token expiring, quality degradation). See Warning Codes.
telnyx.socket.close	CloseEvent	WebSocket closed. SDK will attempt reconnection automatically.
telnyx.socket.error	Event	WebSocket error.

Call Events

Event	Payload	Description
telnyx.notification	INotification	Call state updates, media events, and SDK notifications. This is the primary event for handling call lifecycle.

Stats Events

Event	Payload	Description
telnyx.stats.frame	StatsFrame	Periodic WebRTC stats (RTT, jitter, packet loss). Emitted every callReportInterval ms.
telnyx.stats.report	StatsReport	End-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:

Option	Default	Description
keepConnectionAliveOnSocketClose	false	Keep PeerConnection alive during reconnect
mediaPermissionsRecovery	—	Auto-recover media permissions for inbound calls

---

See Also

• IClientOptions — Full configuration reference
• Call Class — Call control methods
• Error Handling — Error and warning codes
• Best Practices — Production deployment guide
• Authentication — JWT generation and token refresh