@telnyx/webrtc

Summary

The Telnyx WebRTC Client provides all the functionality you need to start making voice & video calls from a browser.

• Installation
• Usage
• Examples
  • Vanilla JavaScript
  • React.js
• Browser support
• Development

Installation

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

Usage

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.

Client

// 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" /> -->

Events

// 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.

Calls

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:[email protected]',
  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.

Debugging

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'

Setting Preferred Codec

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

Getting the Registration State

To retrieve the registration state from the server gateway you can use client.getIsRegistered method

client.getIsRegistered().then(isRegistered => {...})

Examples

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:

• @telnyx/react-client

Browser support

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.

Development

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

Documentation

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.

Supported tags

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.

@apialias

Use apialias to display a different name in public documentation.

/**
 * @apialias PublicObject
 */
interface IPublicObject {}

@examples

Precede code samples with examples.

/**
 * @examples
 * ```js
 * new PublicUseModule(options);
 * ```
 */

@internalnote

Precede internal notes that should not be rendered with internalnote.

/**
 * @internalnote {@see InternalUseModule} for implementation
 */

Contributing

See Contribution Guide

License

MIT © Telnyx