Browser SDK V2

Plivo BrowserSDK allows you to make and receive calls using Plivo applications directly from any web browser that supports webRTC. Using our SDK you can create applications like Click to Call, Conferencing Apps and even Webphones. Currently we support Google Chrome 55 and above and Firefox 51 and above.

Try out the demo here:

Get started with examples

Including the javascript

Include the plivo javascript file as shown below

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

Initializing the plivoBrowserSdk Object

The plivoBrowserSdk object needs to be initialized.

var options = {
    "debug":"DEBUG",
    "permOnClick":true,
    "audioConstraints":{"optional":[{"googAutoGainControl":false},{"googEchoCancellation":false}]},
    "enableTracking":true
};
var plivoBrowserSdk = new window.Plivo(options);

Event registration

Pass function references to the events produced from the sdk. This is where your UI manipulation should handle all the different 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('onIncomingCallCanceled', onIncomingCallCanceled);
plivoBrowserSdk.client.on('onCallFailed', onCallFailed);
plivoBrowserSdk.client.on('onCallAnswered', onCallAnswered);
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);
plivoWebSdk.client.on('onConnectionChange',onConnectionChange);

Registering using your Plivo Endpoint

var username = 'johndoe12345';
var pass = 'XXXXXXXX';
plivoBrowserSdk.client.login(username, password);

Making a call

Making a call to any number/sip endpoint. Do remember that the application attached to the registered endpoint should have an answer url that will ensure that the correct <Dial> element is returned

var dest = “jane1234@phone.plivo.com”;
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 once the onIncomingCall event is received

plivoBrowserSdk.client.answer();

Sending DTMF

The snippet below shows how you can send a DTMF tone when in a phone call

plivoBrowserSdk.client.sendDtmf("1");

Configuration

The following are the 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 before call. Otherwise it will be asked on page load.	true/false	false
`audioConstraints`	Audio constraints object that will be passed to webRTC getUserMedia().	Audio constraints values are browser specific. The following values can be set to true or false: googEchoCancellation, googAutoGainControl, googNoiseSuppression, googHighpassFilter	{}
`enableTracking`	Set to true if you want to get mediaMetrics events and enable call quality tracking.	true/false	true
`dscp`	Set to true if you want to enable QoS in voice traffic. Differentiated Services field in the packet headers for all WebRTC traffic.	true/false	true
`preDetectOwa`	Detect one way audio before answering/sending the call.	true/false	false
`clientRegion`	Initialisation options to set and route calls to specific MediaServer POPs	["usa_west","usa_east","australia","europe","asia","south_america"]

Methods

These are the methods supported on plivoBrowserSdk.client

</table>

These are the methods supported on plivoBrowserSdk.client.audio (Supported only on Chrome)

Method	Description
`login(username, password)`	Registering a Plivo endpoint
`logout()`	Logging out from the registered endpoint
`call(number, extraHeaders)`	Call a number or sip address. 'number' takes a String value and 'extraHeaders' takes a JSON object. Example of 'extraHeaders': {'X-PH-Test1': 'test1', 'X-PH-Test2': 'test2'}
`answer()`	Answer an incoming call
`hangup()`	Hangup an ongoing call
`reject()`	Reject an incoming call
`sendDtmf(digit)`	Send the digits as dtmf 'digit' can be any of the following one character strings: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#"
`mute()`	Mute the mic
`unmute()`	Unmute the mic
`setRingTone(url)`	Set the ringtone that plays when calling. The default tone here will be used in case the URL is not specified. </tr>
`setRingToneBack(url)`	Set the ringtone that plays when being called. The default tone here will be used in case the URL is not specified.
`setConnectTone(boolean)`	Dial beep will play till we get alert response from network. Setting false will not play beep tone. DEFAULT is True , connect tone is enabled . </tr>
`setDebug(debug)`	Set the log level of the sdk. Allowed values are OFF, ERROR, WARN, INFO, DEBUG, ALL
`getPeerConnection()`	Returns an RTCPeerConnection object
`sendQualityFeedback(score, comment)`	Send call quality feedback at the end of a call. 'score' can take an integer value between 1 to 5. Comment must be one of the following values: ['bad-audio', 'call-dropped', 'wrong-callerid', 'post-dial-delay', 'dtmf-not-captured', 'audio-latency', 'unsolicited-call', 'one-way-audio', 'no-audio', 'never-connected']. This feedback would be sent only if 'enableTracking' flag is set to true.
`getCallUUID()`	Returns a String call UUID if a call is active, else returns null
`getLastCallUUID()`	Returns last call UUID, Useful in the cases if you want to send feedback for last call
`webRTC()`	Returns true if webRTC is supported and false if there is no webrtc support
`version`	It is a variable that returns current version of the Plivo SDK
`isLoggedIn`	It is a variable that returns 'true' if the user is logged in and 'false' otherwise

Method	Description
`availableDevices(filter)`	This is a promise based callback that returns all available devices. The filter parameter is optional and takes a String value. Pass 'input' as filter by Input audio devices,'output' as filter by Output audio devices, null to get all audio devices
`revealAudioDevices(arg)`	This is a promise based callback that will force and ask for allowing permission before returning all available devices. arg parameter is optional and takes a string. Passing 'returnStream' as arg will return local stream as well in Promise success

Objects in Audio Device API plivoBrowserSdk.client.audio are as follows:

Object	Methods and Parameters	Description
`microphoneDevices`	`set(deviceID)` `get()` `reset()`	`set` method will set the audioDevice ID as default Microphone device. The deviceID parameter is mandatory and takes a String value. `get` method will return the Microphone device ID which is set already. `reset` method will remove any Microphone device ID which is already set.
`speakerDevices`	`set(deviceId)` `get()` `reset()` `media(source)`	`set` method will set the audioDevice ID as default Speaker device for DTMF and remote audio. The deviceID parameter is mandatory and takes a String value. `get` method will return the Speaker device ID which is set already. `reset` method will remove any Speaker device ID which is already set. `media`will take 'dtmf' or 'ringback' as source parameter and will return the corresponding HTML audio element. This parameter is mandatory.
`ringtoneDevices`	`set(deviceId)` `get()` `reset()` `media()`	`set` method will set the audioDevice ID as default Ringtone device for DTMF and remote audio. The deviceID parameter is mandatory and takes a String value. `get` method will return the Ringtone device ID which is set already. `reset` method will remove any Ringtone device ID which is already set. `media` method will return Ringtone HTML audio element.

Events

plivoBrowserSdk object receives events that can be listened to.

Event	Description
`onLogin`	Occurs when a login is successful
`onLoginFailed(cause)`	Occurs when a login has failed.cause returns the login failure reason
`onLogout`	Occurs when a logout is successful
`onCalling`	Occurs when a call is initiated
`onCallRemoteRinging`	Occurs when the remote end starts ringing during an outbound call
`onCallAnswered`	Occurs when the an outbound or an inbound call is answered
`onCallTerminated`	Occurs when the an outbound or an inbound call has ended
`onIncomingCall(callerID, extraHeaders)`	Occurs when there is an incoming call. callerID provides the callerID and extraHeaders return the X-Headers from Plivo
`onIncomingCallCanceled`	Occurs when an incoming call is cancelled by the caller
`onCallFailed(cause)`	Occurs when an outbound or an inbound call fails. cause returns the reason for call failing
`onMediaPermission(event)`	Occurs when media permission has been granted. event returns the stream access status. The success event returns `{'status':'success','stream':true}`. On failure the event returns `{'status':'failure','error':errorName}`
`onWebrtcNotSupported`	Occurs when browser does not support web rtc
`mediaMetrics`	Works only for Chrome. Raises the following events: high_jitter: when the jitter is higher than 30 ms for 3 out of last 5 samples. high_rtt: When the RTT is higher than 400 ms for 3 out of last 5 samples. high_packetloss: When the packet loss is > 10% for OPUS and loss > 20% PCMU. low_mos: When sampled mos is < 3 for 3 out of last 5 samples, no_microphone_access When we detect one way audio (<80 bytes sent in 3 seconds). no_audio_received : When the user is not able to hear the callee or When audio level is stable for last 3 samples. ice_timeout : Alert if ICE gathering takes more than 2 sec either for outgoing call invite or incoming call answer. All the above will have `level`:`warning`, its `group` : `network/audio`, related params will have its own `value` and state `active`:`true/false`. Example: `{active : true, desc : "local_audio", group : "audio", level : "warning", type : "no_audio_received", value : 0}`
`onAudioDeviceChange(deviceObj)`	Occurs when there is a change in USB audio device, Device added or removed. This event will emit an object with two properties "change" and "device". change will have values "added" or "removed". Device provides device specific properties
`onConnectionChange`	This event is generated when the state of Plivo's WebSocket connection changes. For example, when the WebSocket is disconnected due to internet issues. On WebSocket disconnect `{ 'state': 'disconnected', 'eventCode': <code>, 'eventReason': <reason> }` On WebSocket reconnect `{ 'state': 'connected' }` Common WebSocket event codes ( RFC 6455 ) `1006: indicates that the connection was closed abnormally, e.g., without sending or receiving a Close control frame. For example, internet disconnection. 1009: indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process. 1011: indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.`

Examples

Checkout our github repo for examples

Rate this page

🥳 Thank you! It means a lot to us!