The TelnyxRTC client connects your application to the Telnyx backend, enabling you to make outgoing calls and handle incoming calls.

Examples

// Initialize the client
const client = new TelnyxRTC({
  // Use a JWT to authenticate (recommended)
  login_token: login_token,
  // or use your Connection credentials
  //  login: username,
  //  password: password,
});

// Attach event listeners
client
  .on('telnyx.ready', () => console.log('ready to call'))
  .on('telnyx.notification', (notification) => {
    console.log('notification:', notification);
  });

// Connect and login
client.connect();

// You can call client.disconnect() when you're done.
// Note: When you call `client.disconnect()` you need to remove all ON event methods you've had attached before.

// Disconnecting and Removing listeners.
client.disconnect();
client.off('telnyx.ready');
client.off('telnyx.notification');

• default

  ↳ TelnyxRTC

• constructor

• connected
• localElement
• mediaConstraints
• remoteElement
• speaker

• checkPermissions
• connect
• disableMicrophone
• disconnect
• enableMicrophone
• getAudioInDevices
• getAudioOutDevices
• getDeviceResolutions
• getDevices
• getVideoDevices
• handleLoginError
• login
• logout
• newCall
• off
• on
• setAudioSettings
• webRTCInfo
• webRTCSupportedBrowserList

• new TelnyxRTC(options)

Creates a new TelnyxRTC instance with the provided options.

Name	Type	Description
options	IClientOptions	Options for initializing a client

Examples

Authenticating with a JSON Web Token:

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

Authenticating with username and password credentials:

const client = new TelnyxRTC({
  login: username,
  password: password,
});

Custom ringback and ringtone files can be a wav/mp3 in your local public folder or a file hosted on a CDN, ex: https://cdn.company.com/sounds/call.mp3.

To use the ringbackFile, make sure the "Generate Ringback Tone" option is disabled in your Telnyx Portal connection configuration (Inbound tab.)

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

client.remoteElement = 'remoteMedia';

The corresponding HTML:

<audio id="remoteMedia" autoplay="true" />
<!-- or for video: -->
<!-- <video id="remoteMedia" autoplay="true" playsinline="true" /> -->

TelnyxRTCClient.constructor

• get connected(): boolean

true if the client is connected to the Telnyx RTC server

boolean

Example

const client = new TelnyxRTC(options);
console.log(client.connected); // => false

TelnyxRTCClient.connected

---

• get localElement(): string | Function | HTMLMediaElement

Gets the local html element.

string | Function | HTMLMediaElement

Example

const client = new TelnyxRTC(options);

console.log(client.localElement);
// => HTMLMediaElement

TelnyxRTCClient.localElement

• set localElement(tag): void

Sets the local html element that will receive the local stream.

Name	Type
tag	string | Function | HTMLMediaElement

void

Example

const client = new TelnyxRTC(options);
client.localElement = 'localElementMediaId';

TelnyxRTCClient.localElement

---

• get mediaConstraints(): Object

Audio and video constraints currently used by the client.

Object

Name	Type
audio	boolean | MediaTrackConstraints
video	boolean | MediaTrackConstraints

Examples

const client = new TelnyxRTC(options);

console.log(client.mediaConstraints);
// => { audio: true, video: false }

TelnyxRTCClient.mediaConstraints

---

• get remoteElement(): string | Function | HTMLMediaElement

Gets the remote html element.

string | Function | HTMLMediaElement

Example

const client = new TelnyxRTC(options);

console.log(client.remoteElement);
// => HTMLMediaElement

TelnyxRTCClient.remoteElement

• set remoteElement(tag): void

Sets the remote html element that will receive the remote stream.

Name	Type
tag	string | Function | HTMLMediaElement

void

Example

const client = new TelnyxRTC(options);
client.remoteElement = 'remoteElementMediaId';

TelnyxRTCClient.remoteElement

---

• get speaker(): string

Default audio output device, if set by client.

string

Example

const client = new TelnyxRTC(options);

console.log(client.speaker);
// => "abc123xyz"

TelnyxRTCClient.speaker

• set speaker(deviceId): void

Sets the default audio output device for subsequent calls.

Name	Type
deviceId	string

void

Example

let result = await client.getAudioOutDevices();

if (result.length) {
  client.speaker = result[1].deviceId;
}

TelnyxRTCClient.speaker

▸ checkPermissions(audio?, video?): Promise<boolean>

Checks if the browser has the permission to access mic and/or webcam

Name	Type	Default value	Description
audio	boolean	true	Whether to check for microphone permissions.
video	boolean	true	Whether to check for webcam permissions.

Promise<boolean>

Examples

Checking for audio and video permissions:

const client = new TelnyxRTC(options);

client.checkPermissions();

Checking only for audio permissions:

const client = new TelnyxRTC(options);

client.checkPermissions(true, false);

Checking only for video permissions:

const client = new TelnyxRTC(options);

client.checkPermissions(false, true);

TelnyxRTCClient.checkPermissions

---

▸ connect(): Promise<void>

Creates a new connection for exchanging data with the WebRTC server

Promise<void>

Examples

const client = new TelnyxRTC(options);

client.connect();

TelnyxRTCClient.connect

---

▸ disableMicrophone(): void

Disables use of the microphone in subsequent calls.

Note: This setting will be ignored if audio: true is specified when creating a new call.

void

Examples

const client = new TelnyxRTC(options);

client.disableMicrophone();

Keep in mind that new calls will fail if both the microphone and webcam is disabled. Make sure that the webcam is manually enabled, or video: true is specified before disabling the microphone.

const client = new TelnyxRTC({
  ...options,
  video: true,
});

client.disableMicrophone();

TelnyxRTCClient.disableMicrophone

---

▸ disconnect(): Promise<void>

Disconnect all active calls

Promise<void>

Examples

const client = new TelnyxRTC(options);

client.disconnect();

TelnyxRTCClient.disconnect

---

▸ enableMicrophone(): void

Enables use of the microphone in subsequent calls.

Note: This setting will be ignored if audio: false is specified when creating a new call.

void

Examples

const client = new TelnyxRTC(options);

client.enableMicrophone();

TelnyxRTCClient.enableMicrophone

---

▸ getAudioInDevices(): Promise<MediaDeviceInfo[]>

Returns the audio input devices supported by the browser.

Promise<MediaDeviceInfo[]>

Promise with an array of MediaDeviceInfo

Examples

Using async/await:

async function() {
  const client = new TelnyxRTC(options);

  let result = await client.getAudioInDevices();

  console.log(result);
}

Using ES6 Promises:

client.getAudioInDevices().then((result) => {
  console.log(result);
});

TelnyxRTCClient.getAudioInDevices

---

▸ getAudioOutDevices(): Promise<MediaDeviceInfo[]>

Returns the audio output devices supported by the browser.

Browser Compatibility Note: Firefox has yet to fully implement audio output devices. As of v63, this feature is behind the user preference media.setsinkid.enabled. See: https://bugzilla.mozilla.org/show_bug.cgi?id=1152401#c98

Promise<MediaDeviceInfo[]>

Promise with an array of MediaDeviceInfo

Examples

Using async/await:

async function() {
  const client = new TelnyxRTC(options);

  let result = await client.getAudioOutDevices();

  console.log(result);
}

Using ES6 Promises:

client.getAudioOutDevices().then((result) => {
  console.log(result);
});

TelnyxRTCClient.getAudioOutDevices

---

▸ getDeviceResolutions(deviceId): Promise<any[]>

Returns supported resolution for the given webcam.

Name	Type	Description
deviceId	string	the deviceId from your webcam.

Promise<any[]>

Examples

If deviceId is null

1. if deviceId is null and you don't have a webcam connected to your computer, it will throw an error with the message "Requested device not found".

2. if deviceId is null and you have one or more webcam connected to your computer, it will return a list of resolutions from the default device set up in your operating system.

Using async/await:

async function() {
  const client = new TelnyxRTC(options);
  let result = await client.getDeviceResolutions();
  console.log(result);
}

Using ES6 Promises:

client.getDeviceResolutions().then((result) => {
  console.log(result);
});

If deviceId is not null

it will return a list of resolutions from the deviceId sent.

Using async/await:

async function() {
  const client = new TelnyxRTC(options);
  let result = await client.getDeviceResolutions(deviceId);
  console.log(result);
}

Using ES6 Promises:

client.getDeviceResolutions(deviceId).then((result) => {
  console.log(result);
});

Deprecated

TelnyxRTCClient.getDeviceResolutions

---

▸ getDevices(): Promise<MediaDeviceInfo[]>

Returns a list of devices supported by the browser

Promise<MediaDeviceInfo[]>

Examples

Using async/await:

async function() {
  const client = new TelnyxRTC(options);
  let result = await client.getDevices();
  console.log(result);
}

Using ES6 Promises:

client.getDevices().then((result) => {
  console.log(result);
});

TelnyxRTCClient.getDevices

---

▸ getVideoDevices(): Promise<MediaDeviceInfo[]>

Returns a list of video devices supported by the browser (i.e. webcam).

Promise<MediaDeviceInfo[]>

Promise with an array of MediaDeviceInfo

Examples

Using async/await:

async function() {
  const client = new TelnyxRTC(options);
  let result = await client.getVideoDevices();
  console.log(result);
}

Using ES6 Promises:

client.getVideoDevices().then((result) => {
  console.log(result);
});

Deprecated

TelnyxRTCClient.getVideoDevices

---

▸ handleLoginError(error): void

Handle login error

Name	Type
error	any

void

void

TelnyxRTCClient.handleLoginError

---

▸ login(options?): Promise<void>

Re-authenticate with the Telnyx RTC server using existing or new credentials within an active WebSocket connection.

This method allows updating session authentication credentials (login/password, JWT token, or anonymous login) and immediately re-authenticates without requiring a full socket reconnection. This is particularly useful for:

• Refreshing expired JWT tokens during an active session
• Switching to different user credentials
• Re-authenticating after token expiration errors

Name	Type	Description
options	Object	Configuration object for the login operation
options.creds?	ILoginParams	Optional credential parameters to update before authentication
options.onError?	(error: any) => void	Callback function invoked when authentication fails, receives the error object
options.onSuccess?	() => void	Callback function invoked when authentication succeeds

Promise<void>

Promise

Example

Re-authenticate with existing credentials:

// Uses the credentials already stored in session options
await client.login();

Example

Refresh an expired JWT token:

const newToken = await fetchNewJwtToken();
await client.login({
  creds: { login_token: newToken },
});

Example

Update login credentials with callbacks:

await client.login({
  creds: {
    login: 'newuser@example.com',
    password: 'newpassword',
  },
  onSuccess: () => {
    console.log('Successfully re-authenticated!');
  },
  onError: (error) => {
    console.error('Authentication failed:', error);
  },
});

Example

Switch to anonymous login:

await client.login({
  creds: {
    anonymous_login: {
      target_type: 'ai_assistant',
      target_id: 'asst_12345',
      target_version_id: 'v1',
    },
  },
});

TelnyxRTCClient.login

---

▸ logout(): void

Alias for .disconnect()

void

Deprecated

TelnyxRTCClient.logout

---

▸ newCall(options): Call

Makes a new outbound call.

Name	Type	Description
options	ICallOptions	Options object for a new call.

Call

The new outbound Call object.

Examples

Making an outbound call to +1 856-444-0362 using default values from the client:

const call = client.newCall({
  destinationNumber: '+18564440362',
  callerNumber: '+15551231234',
});

You can omit callerNumber when dialing a SIP address:

const call = client.newCall({
  destinationNumber: 'sip:example-sip-username@voip-provider.example.net',
});

If you are making calls from one Telnyx connection to another, you may specify just the SIP username:

const call = client.newCall({
  destinationNumber: 'telnyx-sip-username', // This is equivalent to 'sip:telnyx-sip-username@sip.telnyx.com'
});

An error will be thrown if destinationNumber is not specified.

const call = client.newCall().catch(console.error);
// => `destinationNumber is required`

client.newCall({
  destinationNumber: '18004377950',

  callerNumber: '155531234567',

  customHeaders: [{ name: 'X-Header', value: 'value' }],
});

You can pass preferred_codecs to the newCall method to set codec preference during the call.

preferred_codecs is a sub-array of the codecs returned by RTCRtpReceiver.getCapabilities('audio')

const allCodecs = RTCRtpReceiver.getCapabilities('audio').codecs;

const PCMACodec = allCodecs.find((c) =>
  c.mimeType.toLowerCase().includes('pcma')
);

client.newCall({
  destinationNumber: 'xxx',
  preferred_codecs: [PCMACodec],
});

ICE candidate prefetching is enabled by default. This pre-gathers ICE candidates when the RTCPeerConnection is created, before setLocalDescription is called, improving call setup performance and reducing DTLS handshake issues caused by late-arriving candidates.

To disable prefetching, pass prefetchIceCandidates: false to the newCall method:

client.newCall({
  destinationNumber: 'xxx',
  prefetchIceCandidates: false,
});

Trickle ICE can be enabled by passing trickleIce to the newCall method. example:

client.newCall({
  destinationNumber: 'xxx',
  trickleIce: true,
});

When a call is recovered after a network reconnection (reattach), the SDK creates a new call object and sets recoveredCallId to the ID of the ended call. Use this to correlate the new call with the old one and avoid duplicate UI elements:

client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate') {
    const call = notification.call;
    if (call.recoveredCallId) {
      // This call replaced a previous call after recovery.
      // Remove the old dialer/UI for call.recoveredCallId
      removeDialer(call.recoveredCallId);
    }
  }
});

Voice isolation options can be set by passing an audio object to the newCall method. This property controls the settings of a MediaStreamTrack object. For reference on available audio constraints, see MediaTrackConstraints. example:

client.newCall({
  destinationNumber: 'xxx',
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});

TelnyxRTCClient.newCall

---

▸ off(eventName, callback?): TelnyxRTC

Removes an event handler that were attached with .on(). If no handler parameter is passed, all listeners for that event will be removed.

Name	Type	Description
eventName	string	Event name.
callback?	Function	Function handler to be removed.

TelnyxRTC

The client object itself.

Note: a handler will be removed from the stack by reference so make sure to use the same reference in both .on() and .off() methods.

Examples

Subscribe to the telnyx.error and then, remove the event handler.

const errorHandler = (error) => {
  // Log the error..
};

const client = new TelnyxRTC(options);

client.on('telnyx.error', errorHandler);

// .. later
client.off('telnyx.error', errorHandler);

TelnyxRTCClient.off

---

▸ on(eventName, callback): TelnyxRTC

Attaches an event handler for a specific type of event.

telnyx.ready	The client is authenticated and available to use
telnyx.error	An error occurred at the session level
telnyx.notification	An update to the call or session
telnyx.socket.open	The WebSocket connection has been made
telnyx.socket.close	The WebSocket connection is set to close
telnyx.socket.error	An error occurred at the WebSocket level
telnyx.socket.message	The client has received a message through WebSockets

Name	Type	Description
eventName	string	Event name.
callback	Function	Function to call when the event comes.

TelnyxRTC

The client object itself.

Examples

Subscribe to the telnyx.ready and telnyx.error events.

const client = new TelnyxRTC(options);

client
  .on('telnyx.ready', (client) => {
    // Your client is ready!
  })
  .on('telnyx.error', (error) => {
    // Got an error...
  });

TelnyxRTCClient.on

---

▸ setAudioSettings(settings): Promise<MediaTrackConstraints>

Sets the default audio constraints for your client. See here for further details.

Note: It's a common behaviour, in WebRTC applications, to persist devices user's selection to then reuse them across visits. Due to a Webkit’s security protocols, Safari generates random deviceId on each page load. To avoid this issue you can specify two additional properties micId and micLabel in the constraints input parameter. The client will use these values to assure the microphone you want to use is available by matching both id and label with the device list retrieved from the browser.

Name	Type	Description
settings	IAudioSettings	MediaTrackConstraints object with the addition of micId and micLabel.

Promise<MediaTrackConstraints>

Promise<MediaTrackConstraints> Audio constraints applied to the client.

Examples

Set microphone by id and label with the echoCancellation flag turned off:

// within an async function
const constraints = await client.setAudioSettings({
  micId: '772e94959e12e589b1cc71133d32edf543d3315cfd1d0a4076a60601d4ff4df8',
  micLabel: 'Internal Microphone (Built-in)',
  echoCancellation: false,
});

TelnyxRTCClient.setAudioSettings

---

▸ Static webRTCInfo(): string | IWebRTCInfo

Checks if the running browser has support for TelnyRTC

string | IWebRTCInfo

An object with WebRTC browser support information or a string error message.

Examples

Check if your browser supports TelnyxRTC

const info = TelnyxRTC.webRTCInfo();
const isWebRTCSupported = info.supportWebRTC;
console.log(isWebRTCSupported); // => true

An error message will be returned if your browser doesn't support TelnyxRTC

const info = TelnyxRTC.webRTCInfo();
if (!info.supportWebRTC) {
  console.error(info); // => 'This browser does not support @telnyx/webrtc. To see browser support list: `TelnyxRTC.webRTCSupportedBrowserList()'
}

---

▸ Static webRTCSupportedBrowserList(): IWebRTCSupportedBrowser[]

Returns the WebRTC supported browser list.

The following table indicates the browsers supported by TelnyxRTC. We support the most recent (N) versions of these browsers unless otherwise indicated.

	Chrome	Firefox	Safari	Edge
Android	[-]	[-]	[ ]	[ ]
iOS	[ ]	[ ]	[x]	[ ]
Linux	[x]	[-]	[ ]	[ ]
MacOS	[x]	[-]	[x]	[-]
Windows	[x]	[-]	[ ]	[-]

[x] supports audio and video [-] supports only audio [ ] not supported

IWebRTCSupportedBrowser[]

An array with supported operational systems and browsers.

Examples

const browserList = TelnyxRTC.webRTCSupportedBrowserList();
console.log(browserList); // => [{"operationSystem": "Android", "supported": [{"browserName": "Chrome", "features": ["video", "audio"], "supported": "full"},{...}]