Creates a new TelnyxRTC instance with the provided options.
Options for initializing a client
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" /> -->
voice_sdk_id used when posting call report payloads for this session.
true if the client is connected to the Telnyx RTC server
const client = new TelnyxRTC(options);
console.log(client.connected); // => false
Gets the local html element.
const client = new TelnyxRTC(options);
console.log(client.localElement);
// => HTMLMediaElement
Sets the local html element that will receive the local stream.
const client = new TelnyxRTC(options);
client.localElement = 'localElementMediaId';
The original string id supplied via the session-level localElement
setter (e.g. client.localElement = 'localMediaId'), or null when the
caller supplied a DOM element, a Function resolver, or nothing. Exposed
so the active-calls recovery marker can persist the session-level
element id for calls that rely on the session-level default (VSDK-408).
Audio and video constraints currently used by the client.
const client = new TelnyxRTC(options);
console.log(client.mediaConstraints);
// => { audio: true, video: false }
Reconnect delay with exponential backoff and jitter.
Uses the current _reconnectAttempts counter to compute the delay:
The backoff is reset only on confirmed healthy registration (REGED), not merely on socket open.
Gets the remote html element.
const client = new TelnyxRTC(options);
console.log(client.remoteElement);
// => HTMLMediaElement
Sets the remote html element that will receive the remote stream.
This is the session-level default: any call that does not specify its own
remoteElement falls back to this element. Note that the session-level
element is shared across calls (last-writer-wins), so for concurrent calls
in one client session you should assign a distinct remoteElement per call
via client.newCall({ remoteElement }) (outbound) or
call.answer({ remoteElement }) (inbound). See the README "Per-call
remoteElement" section.
const client = new TelnyxRTC(options);
client.remoteElement = 'remoteElementMediaId';
The original string id supplied via the session-level remoteElement
setter (e.g. client.remoteElement = 'remoteMediaId'), or null when
the caller supplied a DOM element, a Function resolver, or nothing.
Mirrors localElementId: exposed for the recovery marker so a
call relying on the session-level default can be restored by id after a
page reload (VSDK-408).
Default audio output device, if set by client.
const client = new TelnyxRTC(options);
console.log(client.speaker);
// => "abc123xyz"
Sets the default audio output device for subsequent calls.
let result = await client.getAudioOutDevices();
if (result.length) {
client.speaker = result[1].deviceId;
}
Tear down every active call LOCALLY without sending BYE on the wire.
Used before emitting RECONNECTION_EXHAUSTED (and any other path where
the signaling socket is already dead). Sending BYE over a dead socket
would only generate BYE_SEND_FAILED noise, so each call is finalized
via hangup({}, false) — which closes the RTCPeerConnection, stops
media, fires the local hangup notification, and removes the call from
session.calls, but skips the outbound BYE. (VSDK-318 Step 4.d)
Checks if the browser has the permission to access mic and/or webcam
Whether to check for microphone permissions.
Whether to check for webcam permissions.
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);
Disables use of the microphone in subsequent calls.
Note: This setting will be ignored if audio: true is
specified when creating a new call.
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();
Returns the audio input devices supported by the browser.
Promise with an array of MediaDeviceInfo
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);
});
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 with an array of MediaDeviceInfo
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);
});
Returns supported resolution for the given webcam.
the deviceId from your webcam.
If deviceId is null
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".
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);
});
Returns a list of devices supported by the browser
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);
});
Returns a list of video devices supported by the browser (i.e. webcam).
Promise with an array of MediaDeviceInfo
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);
});
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:
Configuration object for the login operation
Optional creds?: ILoginParamsOptional credential parameters to update before authentication
Optional onCallback function invoked when authentication fails, receives the error object
Optional onCallback function invoked when authentication succeeds
Promise
Re-authenticate with existing credentials:
// Uses the credentials already stored in session options
await client.login();
Refresh an expired JWT token:
const newToken = await fetchNewJwtToken();
await client.login({
creds: { login_token: newToken }
});
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);
}
});
Switch to anonymous login:
await client.login({
creds: {
anonymous_login: {
target_type: 'ai_assistant',
target_id: 'asst_12345',
target_version_id: 'v1'
}
}
});
Makes a new outbound call.
Options object for a new call.
The new outbound Call object.
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,
});
recoveredCallIdWhen 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
},
});
Removes an event handler that were attached with .on(). If no handler parameter is passed, all listeners for that event will be removed.
Event name.
Optional callback: ((event) => void)Function handler to be removed.
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.
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)
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 |
Event name.
Function to call when the event comes.
The client object itself.
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...
})
Called when a signaling request times out (via Connection.RequestTimeoutError). Delegates to the signaling health monitor for recovery. Only critical methods (Modify, Bye, Ping) trigger force-reconnect; non-critical timeouts are just logged.
Report that an ICE restart attempt failed for the given call. Called by BaseCall when the ICE restart Modify request could not be sent or the server returned an error.
The health monitor owns the recovery decision (whether to reconnect the socket, when, etc.). BaseCall does NOT trigger recovery itself — this handoff keeps recovery logic in one place.
Report no-RTP condition to the health monitor. Called by CallReportCollector when RTP bytes stop flowing while media should be active.
The health monitor decides whether to trigger ICE restart (if signaling is healthy) or socket reconnect (if signaling is also unhealthy).
Report a peer/ICE failure to the health monitor. Called by Peer when iceConnectionState or connectionState transitions to 'failed'.
The health monitor decides whether to trigger ICE restart (if signaling is healthy) or socket reconnect (if signaling is also unhealthy).
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.
MediaTrackConstraints object with the addition of micId and micLabel.
Promise<MediaTrackConstraints> Audio constraints applied to the client.
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
})
Static webRTCInfoChecks if the running browser has support for TelnyRTC
An object with WebRTC browser support information or a string error message.
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 webRTCSupportedReturns 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
An array with supported operational systems and browsers.
const browserList = TelnyxRTC.webRTCSupportedBrowserList();
console.log(browserList) // => [{"operationSystem": "Android", "supported": [{"browserName": "Chrome", "features": ["video", "audio"], "supported": "full"},{...}]
The
TelnyxRTCclient connects your application to the Telnyx backend, enabling you to make outgoing calls and handle incoming calls.Examples