Skip to main content

WebRTC JS Client

Overview - JS Client​

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

The SDK can be added to your application in the following ways:

// Include the Telnyx WEBRTC JS SDK
<script
    type="text/javascript"
    src="https://unpkg.com/@telnyx/[email protected]/lib/bundle.js">
</script>

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');

constructor(options)​

Creates a new TelnyxRTC instance with the provided options.

Parameters​

NAMETYPEREQUIREDDESCRIPTION
loginstringoptionalThe username to authenticate with your SIP Connection. login and password will take precedence over login_token for authentication.
login_tokenstringrequiredThe JSON Web Token (JWT) to authenticate with your SIP Connection. This is the recommended authentication strategy. See how to create one.
passwordstringoptionalThe password to authenticate with your SIP Connection.
ringbackFilestringoptionalA URL to a wav/mp3 ringback file that will be used when you disable "Generate Ringback Tone" in your SIP Connection.
ringtoneFilestringoptionalA URL to a wav/mp3 ringtone file.

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 ringtone and ringback​

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',
});

To hear/view calls in the browser, you'll need to specify an HTML media element:​

client.remoteElement = 'remoteMedia';

The corresponding HTML:

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

.connected​

true if the client is connected to the Telnyx RTC server

Examples​

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

.localElement​

Gets the local html element.

Examples​

const client = new TelnyxRTC(options);

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

.mediaConstraints​

Audio and video constraints currently used by the client.

Examples​

const client = new TelnyxRTC(options);

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

.remoteElement​

Gets the remote html element.

Examples​

const client = new TelnyxRTC(options);

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

.speaker​

Default audio output device, if set by client.

Examples​

const client = new TelnyxRTC(options);

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

.checkPermissions(audio, video)​

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

Parameters​

NAMETYPEDEFAULTREQUIREDDESCRIPTION
audiobooleantruerequiredWhether to check for microphone permissions.
videobooleantruerequiredWhether to check for webcam permissions.

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);

.connect()​

Creates a new connection for exchanging data with the WebRTC server

Examples​

const client = new TelnyxRTC(options);

client.connect();

.disableMicrophone()​

Disables use of the microphone in subsequent calls.

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

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();

.disableWebcam()​

Disables use of the webcam in subsequent calls.

Note: This method will disable the video even if video: true is specified.

Examples​

const client = new TelnyxRTC(options);

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

client.disableWebcam();

.disconnect()​

Disconnect all active calls

Examples​

const client = new TelnyxRTC(options);

client.disconnect();

.enableMicrophone()​

Enables use of the microphone in subsequent calls.

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

Examples​

const client = new TelnyxRTC(options);

client.enableMicrophone();

.enableWebcam()​

Enables use of the webcam in subsequent calls.

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

Examples​

const client = new TelnyxRTC(options);

client.enableWebcam();

.getAudioInDevices()​

Returns the audio input devices supported by the browser.

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);
});

.getAudioOutDevices()​

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

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);
});

.getDeviceResolutions(deviceId)​

Returns supported resolution for the given webcam.

Parameters​

NAMETYPEREQUIREDDESCRIPTION
deviceIdstringrequiredthe deviceId from your webcam.

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);
});

.getDevices()​

Returns a list of devices supported by the browser

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);
});

.getVideoDevices()​

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

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);
});

.logout()​

Alias for .disconnect()

.newCall(options)​

Makes a new outbound call.

Parameters​

NAMETYPEREQUIREDDESCRIPTION
audiobooleanoptionalOverrides client's default audio constraints. Defaults to true
callerNamestringoptionalName to use as the caller ID name when dialing out to a destination.
callerNumberstringoptionalNumber to use as the caller ID when dialing out to a destination. A valid phone number is required for dials out to PSTN numbers.
camIdstringoptionaldeviceId to use as webcam. Overrides the client's default one.
clientStatestringoptionalTelnyx's Call Control client_state. Can be used with Connections with Advanced Events enabled. clientState string should be base64 encoded.
destinationNumberstringrequiredPhone number or SIP URI to dial.
iceServersRTCIceServer[]optionalOverrides client's default iceServers.
idstringoptionalCustom ID to identify the call. This will be used as the callID in place of the UUID generated by the client.
localElementstring | HTMLMediaElementoptionalOverrides client's default localElement.
localStreamMediaStreamoptionalIf set, the call will use this stream instead of retrieving a new one.
mediaSettingsundefinedrequiredConfigures media (audio/video) in a call.
micIdstringoptionaldeviceId to use as microphone. Overrides the client's default one.
onNotificationFunctionoptionalOverrides client's default telnyx.notification handler for this call.
remoteElementstring | HTMLMediaElementoptionalOverrides client's default remoteElement.
remoteStreamMediaStreamoptionalIf set, the call will use this stream instead of retrieving a new one.
speakerIdstringoptionaldeviceId to use as speaker. Overrides the client's default one.
telnyxCallControlIdstringoptionalTelnyx Call Control ID, if using Call Control services.
telnyxLegIdstringoptionalTelnyx call leg ID, if using Call Control services.
telnyxSessionIdstringoptionalTelnyx call session ID, if using Call Control services.
useStereobooleanoptionalUses stereo audio instead of mono.
videobooleanoptionalOverrides client's default video constraints. Defaults to false
deviceIdstringoptional

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:[email protected]'
});

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:[email protected]'
});

Error handling​

An error will be thrown if destinationNumber is not specified.

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

.off(eventName, callback)​

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

Parameters​

NAMETYPEREQUIREDDESCRIPTION
eventNamestringrequiredEvent name.
callbackFunctionoptionalFunction handler to be removed.

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)

.on(eventName, callback)​

Attaches an event handler for a specific type of event.

Events​

telnyx.readyThe client is authenticated and available to use
telnyx.errorAn error occurred at the session level
telnyx.notificationAn update to the call or session
telnyx.socket.openThe WebSocket connection has been made
telnyx.socket.closeThe WebSocket connection is set to close
telnyx.socket.errorAn error occurred at the WebSocket level
telnyx.socket.messageThe client has received a message through WebSockets

Parameters​

NAMETYPEREQUIREDDESCRIPTION
eventNamestringrequiredEvent name.
callbackFunctionrequiredFunction to call when the event comes.

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...
})

.setAudioSettings(settings)​

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.

Parameters​

NAMETYPEREQUIREDDESCRIPTION
settingsIAudioSettingsrequired(https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints) object with the addition of micId and micLabel.

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
})

.setVideoSettings(settings)​

Sets the default video 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 camId and camLabel in the constraints input parameter. The client will use these values to assure the webcam you want to use is available by matching both id and label with the device list retrieved from the browser.

Parameters​

NAMETYPEREQUIREDDESCRIPTION
settingsIVideoSettingsrequired(https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints) object with the addition of camId and camLabel.

Examples​

Set webcam by id and label with 720p resolution.

// within an async function
const constraints = await client.setVideoSettings({
 camId: '882e94959e12e589b1cc71133d32edf543d3315cfd1d0a4076a60601d4ff4df8',
 camLabel: 'Default WebCam (Built-in)',
 width: 1080,
 height: 720
})

.webRTCInfo()​

Checks if the running browser has support for TelnyRTC

Examples​

Check if your browser supports TelnyxRTC

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

Error handling​

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()'
}

.webRTCSupportedBrowserList()​

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.

CHROMEFIREFOXSAFARIEDGE
Android--
iOSx
Linuxx-
MacOSx-x-
Windowsx--

Legend​

x supports audio and video - supports only audio not supported

Examples​

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

On this page​