@telnyx/webrtc

@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
• Error Handling
• 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:[e-mail]',
  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'

In-Call Quality Metrics

To be able to get the in-call quality metrics you have to first enable debugging for the call and then listen for the telnyx.stats.frame event.

const call = client.newCall({
  // Destination is required and can be a phone number or SIP URI
  destinationNumber: '18004377950',
  debug: true, // it is required to enable debugging for the call,
});

client.on('telnyx.stats.frame', (stats) => {
  console.log(stats);
});

Pre-Call Diagnosis

To be able to run pre-call diagnosis you can use the PreCallDiagnosis.run method.

import { PreCallDiagnosis } from '@telnyx/webrtc';

PreCallDiagnosis.run({
  credentials: {
    login: clientOptions.login,
    password: clientOptions.password,
    loginToken: clientOptions.login_token,
  },
  texMLApplicationNumber: '[phone]',
})
  .then((report) => {
    console.log(report);
  })
  .catch((error) => {
    console.error(error);
  });

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

Anonymous Login for AI assistant

The TelnyxRTC client can be used with an AI assistant by using the anonymous_login method. This allows you to authenticate without a SIP connection, making it easier to integrate with AI assistants.

Note: In order for anonymous login to work, you have to set telephony_settings.supports_unauthenticated_web_calls to true via the API or in the assistant's telephony settings tab in the portal.

const client = new TelnyxRTC({
  anonymous_login: {
    /** Your AI assistant's ID */
    target_id: 'assistant-UUID',
    target_type: 'ai_assistant',
  },
});

client.connect();

Making Calls to AI Assistants

Making calls to the AI assistant is similar to making calls with a SIP connection. You can use the newCall method to initiate a call, the destination number can be left blank.

const call = client.newCall({
  destinationNumber: '',
  remoteElement: 'remoteElement',
  /** other call options. */
});

Its recommended that you set the preferred codec to opus by passing the preferred_codecs option to the newCall method when calling AI assistants.

const allCodecs = RTCRtpReceiver.getCapabilities('audio').codecs;
const opusCodec = allCodecs.find((c) =>
  c.mimeType.toLowerCase().includes('opus')
);

client.newCall({
  destinationNumber: '',
  preferred_codecs: [opusCodec],
});

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