Plivo Browser SDK

Introduction

The Plivo Browser SDK lets you make and receive calls using Plivo applications directly from any web browser. Using our SDK, you can create applications such as:

Call Center — Build efficient call center workflow by allowing your agents to make and receive calls via their browsers. Control call flow in your app using our API.
Click to Call — When adding click to call for your CRM app, Plivo runs seamlessly in the background to allow your users to interact via audio communication.
Web-Based Help Desk — Create great service experiences and workflows. Sales and support agents can access customer info while making calls directly from their web browsers.
Web Conferencing — Build rich conference experiences with Plivo’s out-of-the-box features, including unique call flows, recording calls, and branded conference greetings.

How does it work?

From a browser, a Plivo endpoint initiates an internet call to Plivo’s voice platform.
The platform notifies your application server about the call.
Plivo handles the call based on XML documents returned by the application server. In this case, a Dial XML element connects the call with the phone number specified in the XML document.
Plivo initiates a call to the phone number specified in the Dial XML element.
Once the call is answered, the two parties are connected and can talk to each other.

To learn more about managing the call flows and types of call flows, refer to our Voice Overview guide.

Supported browsers

This table shows the browsers supported by the Plivo Browser SDK. Chrome and Firefox: We support the most recent and previous 10 versions.
Safari: We support the most recent and previous five versions.

	Chrome	Firefox	Safari	Chromium
macOS
Windows			**
Linux			**	***
IOS	*	*		*
Android			**

* Unlike Safari for iOS, Chrome and Firefox for iOS do not have access to WebRTC APIs. ** Safari for Windows and Linux are not supported. *** Edge for Linux is not supported.

Note: On mobile browsers, Browser SDK functionality may be compromised due to limitations imposed by browsers. These limitations include inability to maintain call connectivity if the browser moves to the background, inability to receive incoming call notifications in case the browser was in background, and inability to handle GSM call interruptions. As a result, we highly recommend that you evaluate our mobile SDKs (iOS, Android) while creating mobile voice apps for better user experience.For mobile applications, we recommend using our native iOS and Android SDKs. See our SDK FAQ for more details on browser limitations.

The Browser SDK codebase is publicly available on GitHub.

Browser SDK supports TypeScript (version 4.0.3 and higher).

Try out the demo — get started with examples.

Installation

Download using NPM (recommended)

You can include the Plivo-Browser-SDK NPM package as a dependency in your project. Use the below command:

npm install plivo-browser-sdk --save

Also, you can include the latest Plivo-Browser-SDK Beta NPM package using the below command:

npm install plivo-browser-sdk@beta

After installation, import the SDK in your application:

// ES Module
import Plivo from 'plivo-browser-sdk'

// CommonJS
const Plivo = require('plivo-browser-sdk');

Include using CDN link (not recommended)

You can include the plivo javascript file as shown below directly on your webpage

<script type="text/javascript" src="https://cdn.plivo.com/sdk/browser/v2/plivo.min.js"/>

Note: We do not recommend this approach because any recent changes to our SDK will be applied to your production apps automatically without going through your build process and could lead to unexpected behavior for your customers.To mitigate this risk, every new release is first pushed to this beta CDN link before being merged to the master: <https://cdn.plivo.com/sdk/browser/v2/plivobeta.min.js>

Alternatively, you can include a specific release in your app by using it’s specific CDN link. We continue to make our past releases URI accessible and immutable, unless explicitly stated. You can find the latest links on the Changelog section.

Quick Start

Initializing the plivoBrowserSdk Object

The plivoBrowserSdk object needs to be initialized.

var options = {
"debug":"DEBUG",
"permOnClick":true,
"enableTracking":true,
"closeProtection":true,
"maxAverageBitrate":48000
};
var plivoBrowserSdk = new window.Plivo(options);

For more explanation on options see the Configuration Parameters section.

Event registration

Pass function references to the events produced from the SDK. This is where your UI manipulation should handle the call flows.

plivoBrowserSdk.client.on('onWebrtcNotSupported', onWebrtcNotSupported);
plivoBrowserSdk.client.on('onLogin', onLogin);
plivoBrowserSdk.client.on('onLogout', onLogout);
plivoBrowserSdk.client.on('onLoginFailed', onLoginFailed);
plivoBrowserSdk.client.on('onCallRemoteRinging', onCallRemoteRinging);
plivoBrowserSdk.client.on('onCallConnected', onCallConnected);
plivoBrowserSdk.client.on('onIncomingCallCanceled', onIncomingCallCanceled);
plivoBrowserSdk.client.on('onCallFailed', onCallFailed);
plivoBrowserSdk.client.on('onCallAnswered', onCallAnswered);
plivoBrowserSdk.client.on('onMediaConnected', onMediaConnected);
plivoBrowserSdk.client.on('onCallTerminated', onCallTerminated);
plivoBrowserSdk.client.on('onCalling', onCalling);
plivoBrowserSdk.client.on('onIncomingCall', onIncomingCall);
plivoBrowserSdk.client.on('onMediaPermission', onMediaPermission);
plivoBrowserSdk.client.on('mediaMetrics',mediaMetrics);
plivoBrowserSdk.client.on('onConnectionChange',onConnectionChange);
plivoBrowserSdk.client.on('onDtmfReceived',onDtmfReceived);
plivoBrowserSdk.client.on('remoteAudioStatus', remoteAudioStatus);
plivoBrowserSdk.client.on('onNoiseReductionReady', onNoiseReductionReady);
plivoBrowserSdk.client.on('onWebSocketConnected', onWebSocketConnected);

Registering using your Plivo endpoint

var username = 'johndoe12345';
var password = '<pswd>';
plivoBrowserSdk.client.login(username, password);

Making a call

Making a call to any number/SIP endpoint. The application attached to the registered endpoint should have an answer URL that will return the correct <Dial> element.

var dest = "[email protected]";
var extraHeaders = {'X-PH-Test1': 'test1', 'X-PH-Test2': 'test2'};
plivoBrowserSdk.client.call(dest, extraHeaders);

Accepting a call

This is how an incoming call should be answered when an onIncomingCall event is received.

plivoBrowserSdk.client.answer(callUUID)

callUUID is passed in the onIncomingCall event callback, as we describe in the Reference documentation.

Sending DTMF

This snippet sends a DTMF tone when in a phone call.

plivoBrowserSdk.client.sendDtmf("1");

Configuration Parameters

Attribute	Description	Allowed Values	Default Value
`debug`	Enable debug message in JS log	OFF, ERROR, WARN, INFO, DEBUG, ALL	INFO
`permOnClick`	Set to true if you want to ask for mic permission just before call connection. Otherwise it will be asked only on page load.	true/false	false
dtmfOptions	This parameter can be used to select between “inband” and/or “outband” DTMF.	{sendDtmfType: [“inband”] } / {sendDtmfType: [“outband”] } / {sendDtmfType: [“inband”,“outband”] }	{sendDtmfType: [“inband”,“outband”]}
`audioConstraints`	Audio constraints object that will be passed to webRTC getUserMedia().	Audio constraints values are browser specific. Refer: MediaTrackConstraints
`enableTracking`	Set to true if you want to get mediaMetrics events and enable call quality tracking.	true/false	true

Note: enableTracking will be deprecated as part of the next major update. Please use use enableQualityTracking instead.

Attribute	Description	Allowed Values	Default Value
`enableQualityTracking`	This parameter can be used to enable and disable two functionalities: mediaMetrics events enables the Client device to display local call issues such as broken audio to the user. Call quality tracking enables Plivo to capture and display call quality data in Call Insights. When set to `all` both MediaMetrics events and call quality tracking is enabled. When set to `remoteonly` only call quality tracking is enabled. When set to `localonly` only MediaMetrics events are enabled. When set to `none` both MediaMetrics events and call quality tracking are disabled.	all, remoteonly, localonly, none	all

Note: If enableQualityTracking is configured with a nondefault value, it overrides any configuration of enableTracking.

Attribute	Description	Allowed Values	Default Value
`closeProtection`	Set to `true` to get a dialog prompt while closing the app when the call is in progress (ringing state or answered state).	true, false	false
`dscp`	Set to true to enable QoS in voice traffic. Differentiated Services field in the packet headers for all WebRTC traffic. Note: dscp is supported only in Chrome.	true, false	true
`allowMultipleIncomingCalls`	When set to `true` there can be multiple calls ringing at the same time. 1. The onIncomingCall event will be fired for every incoming call. 2. When an incoming call is accepted, other ringing calls (if any) will be either rejected or ignored depending on the option passed to answer function automatically. 3. When an incoming call is rejected or ignored, other ringing calls (if any) will continue ringing. There can only be one active answered call at any given moment. 1. When an incoming call is accepted, the in-progress answered call will be disconnected automatically. 2. When an incoming call is rejected or ignored, the in-progress answered call will continue without any interruption. When set to `false` incoming calls are silently rejected if the endpoint is engaged in an active call or if another call is ringing.	true, false	false
`clientRegion`	Initialization options to set and route calls to specific MediaServer POPs	[“usa_west”, “usa_east”, “australia”, “europe”, “asia”, “south_america”, “south_asia”]	-

Note: If clientRegion is not defined, the nearest Plivo data center (PoP) will be picked based on the Browser SDK client registered IP address.

Attribute	Description	Allowed Values	Default Value
`enableNoiseReduction`	Reduces background noise during ongoing calls.	true, false	false
`usePlivoStunServers`	Indicates that Plivo will strive to establish the connection with two parallel STUN servers, and the connection will be established promptly upon receiving a response from either server.	true, false	false
`useDefaultAudioDevice`	Determines whether the system’s default input/output devices are utilized following the addition or removal of an audio device. If not, the recently added device will be utilized for both input and output.	true, false	false
`stopAutoRegisterOnConnect`	When set to true, the login() method will only establish a connection to the Plivo servers but will not register the SDK. To complete the registration process, you will need to manually invoke the register() method.	true, false	false
`captureSDKCrashOnly`	When set to true, the SDK will only capture and sync crashes related to the SDK code, avoiding App side errors being pushed to Plivo servers.	true, false	false
`maxAverageBitrate`	Used to control your application’s bandwidth consumption for calls. A higher maxAverageBitrate value may result in more bandwidth consumption, but also better audio quality. Lowering the maxAverageBitrate impacts call quality, as audio is compressed to a greater extent to reduce bandwidth consumption. This parameter only applies to calls using the Opus codec. See RFC-7587 section 7.1 for more info.	8000 - 48000	48000
`registrationRefreshTimer`	A parameter where we allow users to set the value for refreshing the registration of the SDK.	100 - 86400 seconds	120 seconds

Best Practices for Call Quality

VoIP call quality is influenced by several factors, including device software and hardware and the network a device is connected to. Here we explore the key factors that influence call quality on Browser SDK calls, and offers recommendations for improving call quality.

Network Characteristics

The network the device runs on has a big influence on call quality thanks to factors such as jitter and latency.

Jitter and Latency

VoIP calls involve the transmission of a continuous train of voice data packets. If the network is congested, some of the first packets sent may reach a recipient later than other packets. This out-of-order receipt of packets, known as jitter, can result in the audio sounding jumbled or robotic. Jitter is measured in milliseconds of delay, and jitter values higher than 30 milliseconds on WebRTC calls can lead to poor audio quality. High network congestion can also lead to packet loss, resulting in chunks of audio never reaching the intended recipient. Latency, in the context of VoIP calls, is the spoken-to-heard delay in the transmission of audio. The major contributing factor to VoIP latency is the delay incurred in the transmission of voice packets from origin to destination. When this network latency is more than 300 milliseconds of round-trip time, call participants can experience audio lag.

Recommendations

To minimize network and device issues and improve call quality, Plivo recommends:

Using a high-bandwidth fiber connection from a reputed internet provider. Dedicated business internet connections generally come with guaranteed SLAs on bandwidth and latency.
Using a physical Ethernet connection instead of Wi-Fi when possible.
If using Wi-Fi, limiting the number of devices connected on the same channel.
Using high-quality Wi-Fi routers built for enterprises or real-time gaming. Look for routers that come with advanced QoS features.
Auditing your network firewall and NAT settings to check for transmission delays due to improper configuration.
Avoiding large data transfers on the Wi-Fi network during calls.
Limiting bandwidth per connected device to ensure an even allocation of total available bandwidth.
Avoiding calls over cellular data connections (4G and older) as they are not optimized for low-latency traffic.
Setting the Differentiated Service Code Point (dscp) parameter of Plivo Browser SDK to “true.” DSCP for WebRTC is supported by Chrome only. It informs network routers to prioritize voice packets over other network packets. Corresponding QoS configurations in the router may be also required.
Setting Plivo Media Server region selection in auto mode of the Browser SDK. This ensures that calls get routed through the closest geographic PoP based on the device’s IP address.
Ensuring uplink and downlink bandwidth availability of at least 50Kbps for voice transmission.
If operating in a low-bandwidth environment, capping the bandwidth to be consumed on the call using the maxAverageBitrate configuration parameter of the Browser SDK.
Gracefully handling poor call quality experiences in real time by consuming MediaMetrics call quality events emitted by the Browser SDK during the call.
Submitting call quality feedback to Plivo programmatically from the Browser SDK or through the Feedback API. Your feedback lets Plivo optimize its network by identifying patterns across calls.

Network Firewalls

Voice data on VoIP calls is transferred over UDP. Ensure that your network firewall allows the transmission of UDP packets between client devices and the public internet. If your firewall requires whitelisting of external IP addresses, make sure to whitelist Plivo’s SIP Signaling and Media Server IP addresses.

Device Characteristics

Certain software and hardware device characteristics have a direct impact on VoIP call quality.

Browser and OS

The Plivo Browser SDK is tested and supported only for the browsers listed in the Supported browsers section. Browser SDK uses WebRTC for voice calls on these browsers:

Chrome on Windows, Linux, macOS, and Android
Firefox on Windows, Linux, macOS, and Android
Safari 11+ on iOS and macOS
New Microsoft Edge (based on Chromium) on Windows

Chrome for iOS and Firefox for iOS don’t support WebRTC. Plivo highly recommends using our native iOS and Android SDKs to build app-based calling functionality on mobile devices. Mobile browsers would be required to be in the foreground for the entire duration of a call and lack call interruption handling for cellular calls received while on a browser call. Both these features are supported through the Plivo iOS and Android SDKs.

Device Hardware

While most modern PC and smartphone devices are more than capable of handling VoIP calls, incompatibilities between hardware components such as network drivers, audio cards, and other firmware components can result in unexpected issues with media handling. Attempting to reproduce issues on other devices should be a key step in your debugging process.

The Audio Input and Output Device

Plivo recommends using quality headsets for browser-based calls. Headsets minimize echo by providing acoustic isolation between the speaker and the microphone. High-quality VoIP headsets with noise-canceling features can greatly enhance call quality in noisy environments by eliminating background sounds. Wired headsets generally offer more stable sound quality than wireless or Bluetooth headsets. Wireless headsets are more prone to adapter and driver configuration issues, which can lead to static or white noise on calls. We recommend testing with a different headset, or with a built-in mic and speaker, when troubleshooting audio quality issues.

Next steps

Now that you know the fundamentals, you can build a simple app. Get inspiration from our sample applications and learn implementation details from our Browser SDK Reference documentation.

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

Plivo Browser SDK

Introduction

How does it work?

Supported browsers

Installation

Download using NPM (recommended)

Include using CDN link (not recommended)

Quick Start

Initializing the plivoBrowserSdk Object

Event registration

Registering using your Plivo endpoint

Making a call

Accepting a call

Sending DTMF

Configuration Parameters

Best Practices for Call Quality

Network Characteristics

Jitter and Latency

Recommendations

Network Firewalls

Device Characteristics

Browser and OS

Device Hardware

The Audio Input and Output Device

Next steps

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

​Introduction

​How does it work?

​Supported browsers

​Installation

​Download using NPM (recommended)

​Include using CDN link (not recommended)

​Quick Start

​Initializing the plivoBrowserSdk Object

​Event registration

​Registering using your Plivo endpoint

​Making a call

​Accepting a call

​Sending DTMF

​Configuration Parameters

​Best Practices for Call Quality

​Network Characteristics

​Jitter and Latency

​Recommendations

​Network Firewalls

​Device Characteristics

​Browser and OS

​Device Hardware

​The Audio Input and Output Device

​Next steps

Introduction

How does it work?

Supported browsers

Installation

Download using NPM (recommended)

Include using CDN link (not recommended)

Quick Start

Initializing the plivoBrowserSdk Object

Event registration

Registering using your Plivo endpoint

Making a call

Accepting a call

Sending DTMF

Configuration Parameters

Best Practices for Call Quality

Network Characteristics

Jitter and Latency

Recommendations

Network Firewalls

Device Characteristics

Browser and OS

Device Hardware

The Audio Input and Output Device

Next steps