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 by Connection.send() when a request we sent comes back answered. Feeds the monitor's outbound-liveness clock, which is what distinguishes a working socket from one that only still receives.
Public because Connection calls it; not part of the app-facing API.
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).
Runs a microphone check using the PreCallDiagnostic framework.
This method performs an active microphone check: it calls
getUserMedia({ audio: true }) to verify capture works, measures
the audio level using Web Audio APIs, enumerates all available
audio input devices, and optionally records the audio so the user
can listen to it afterwards.
This method does not dial (client.newCall() is not called) —
it calls getUserMedia({ audio: true }) for permission + device
check, then runs a Web Audio AnalyserNode for level measurement.
No SIP signaling or destinationNumber is required.
Options for the microphone check. All fields are optional.
A promise that resolves with the PreCallDiagnosticReport.
Zero-arg form — run with defaults (active capture enabled):
const report = await client.runMicrophoneCheck();
console.log(report.microphone?.isPermissionGrantedCurrently);
console.log(report.microphone?.devices);
console.log(report.microphone?.audioLevelStats);
With recording enabled (user can listen to it afterwards):
const report = await client.runMicrophoneCheck({
durationMs: 5000,
record: true,
warnOnRecording: (notice) => {
showRecordingWarning(notice);
},
});
Runs a network/ICE check using the PreCallDiagnostic framework.
This method tests each configured ICE server URL independently using a real, short diagnostic call. Each call stays active for three seconds and all calls run concurrently to keep the total check duration bounded. TURN URLs force relay policy to verify that the relay is actually usable.
Results from every call are combined under serverTests so a
failed server does not hide successful servers (and vice versa).
Options for the network check. All fields are optional.
A promise that resolves with the PreCallDiagnosticReport.
Zero-arg form — run with the client's default ICE servers:
const report = await client.runNetworkCheck();
console.log(report.serverTests);
With custom ICE servers:
const report = await client.runNetworkCheck({
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
});
Runs a pre-call diagnostic using the new PreCallDiagnostic framework.
This method creates a temporary diagnostic call to probe network, ICE,
audio flow, and microphone conditions before placing a real call. The
diagnostic call is automatically cleaned up (hung up) on completion
unless autoHangup is set to false.
The client's existing ICE servers and audio constraints are reused
unless explicitly overridden via options.
destinationNumber is optional — when omitted, the diagnostic call
dials a sensible default ('+1-872-231-5806').
durationMs controls the post-establishment sampling window and starts
only after the diagnostic call is established. Call setup is bounded by
an internal SDK deadline.
Options for the pre-call diagnostic. All fields are
optional; destinationNumber defaults to '+1-872-231-5806'.
A promise that resolves with the PreCallDiagnosticReport.
Zero-arg form — run with all defaults:
const report = await client.runPreCall();
console.log(report.verdict); // => 'ready' | 'degraded' | 'blocked' | 'inconclusive'
With an explicit destination:
const report = await client.runPreCall({
destinationNumber: '+155****4567',
});
Override the sampling duration:
const report = await client.runPreCall({
durationMs: 3000,
});
Custom ICE servers (diagnostic-only, does not mutate client config):
const report = await client.runPreCall({
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
});
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