The Telnyx WebRTC Client provides all the functionality you need to start making voice & video calls from a browser.
Install the package with:
npm install @telnyx/webrtc --save
As long as you can import npm packages with a bundler like Webpack, you're ready to import TelnyxRTC and begin:
import { TelnyxRTC } from '@telnyx/webrtc';To initialize the WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our quickstart guide to create JWTs (JSON Web Tokens) to authenticate. You can also authenticate directly with the SIP Connection username and password.
// 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,
});
// 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');See ON Events
See TelnyxRTC#constructor for all options.
Important: You should treat Connection credentials as sensitive data and should not hardcode credentials into your frontend web application. Check out the app examples for sample code that handles username and password by prompting the user.
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" /> -->// Create a variable to track the current call
let activeCall;
// Attach event listeners
client
.on('telnyx.ready', () => console.log('ready to call'))
.on('telnyx.error', () => console.log('error'))
// Events are fired on both session and call updates
// ex: when the session has been established
// ex: when there's an incoming call
.on('telnyx.notification', (notification) => {
if (notification.type === 'callUpdate') {
activeCall = notification.call;
}
});See TelnyxRTC.on for all events.
To initiate an outgoing call:
const call = client.newCall({
// Destination is required and can be a phone number or SIP URI
destinationNumber: '18004377950',
callerNumber: '155531234567',
});To enable video when calling:
const videoCall = client.newCall({
destinationNumber: 'sip:example@sip.example.com',
video: true,
});
// And in your HTML, replace the audio element with video.
// <video id="remoteMedia" autoplay="true" playsinline="true" />See TelnyxRTC.newCall for all options.
To answer an incoming call:
client.on('telnyx.notification', (notification) => {
const call = notification.call;
if (notification.type === 'callUpdate' && call.state === 'ringing') {
call.answer();
}
});Both the outgoing and incoming Call instance has methods that can be hooked up to your UI:
// Hangup or reject an incoming call
call.hangup();
// Send digits and keypresses
call.dtmf('1234');
// Call states that can be toggled
call.hold();
call.muteAudio();See Call#methods for all methods.
In order to have a better idea on what is going on under the hood you can gather webrtc metrics for a call:
const call = client.newCall({
// Destination is required and can be a phone number or SIP URI
destinationNumber: '18004377950',
callerNumber: '155531234567',
debug: true // Default is false,
debugOutput: 'socket' // Possible values are 'socket' | 'file'
});
// The debug dump is set to be sent to telnyx by default, if you want to save the debug data to disk
// You can change the debugOutput option to 'file'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: '123',
preferred_codecs: [PCMACodec],
});To retrieve the registration state from the server gateway you can
use client.getIsRegistered method
client.getIsRegistered().then(isRegistered => {...})We've included a few examples in vanilla JavaScript (ES6) and React to help you get started.
Looking for more examples in React? Check out our React client packages:
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
To extend support to other browsers, install and import webrtc-adapter before importing TelnyxRTC. For example:
import 'webrtc-adapter';
import { TelnyxRTC } from '@telnyx/webrtc';To check whether your browser supports TelnyxRTC, use TelnyxRTC.webRTCInfo.
Requirement Node v11.15.0 or later
This library is written in TypeScript to define a clear API with optional typechecking benefits.
To contribute, clone this repo and install locally:
npm install
Afterwards, you're ready to make changes to files in src.
To run all tests:
npm test
TypeScript documentation is automatically generated from TSDoc-style comments on merge to main.
Only code symbols with a symbol-level TSDoc comment will appear in the docs. Use @category to group symbols. For example:
// `PublicUseModule` will appear in docs due to the class-level TSDoc comment.
/**
* A module for public consumption
* @category Public Modules
*/
class PublicUseModule {
// `getSomething` WILL appear in docs because
// there is a TSDoc comment
/**
* Gets something.
*/
getSomething() {}
// `getSomethingElse` will NOT appear in docs
// because of the `@ignore` tag
/**
* Adds another thing
* @ignore
*/
getSomethingElse() {}
// `addAnotherThing` will NOT appear in docs
// because there is no TSDoc comment
addAnotherThing() {}
// `updateSomething` will NOT appear in docs
// because of the `private` keyword
private updateSomething() {}
// `deleteSomething` will NOT appear in docs
// because of the `protected` keyword
protected deleteSomething() {}
}
// `InternalUseModule` will NOT appear in docs,
// even if its members are documented, because
// there is no class-level TSDoc comment.
class InternalUseModule {
doThis() {}
doThat() {}
}If you've added comments and still do not see documentation as expected, check the typedocOptions.exclude config in tsconfig.json.
In addition to the tags supported by Typedoc, we use apialias, example/examples and internalnote.
Note: @link is not supported in public-facing documentation at this time.
Use apialias to display a different name in public documentation.
/**
* @apialias PublicObject
*/
interface IPublicObject {}Precede code samples with examples.
/**
* @examples
* ```js
* new PublicUseModule(options);
* ```
*/Precede internal notes that should not be rendered with internalnote.
/**
* @internalnote {@see InternalUseModule} for implementation
*/