Web SDK V1

Plivo WebSDK allows you to make and receive calls using Plivo applications directly from any web browser. Using our SDK you can create applications like Click to Call, Conferencing Apps and even Webphones. Currently we support WebRTC on Google Chrome, and for all other browsers, your SDK falls back to Flash.

Try out the demo here:

Check out the Plivo WebSDK demo

Get started with examples

Including the javascript

Include the plivo javascript file as shown below

<script type="text/javascript" src="https://s3.amazonaws.com/plivosdk/web/plivo.min.js"/>

Initializing the Plivo JS Object

The Plivo JS object needs to be initialized. Two event listeners are mandatory for the initialization.

// These two listeners are required before init
Plivo.onWebrtcNotSupported = webrtcNotSupportedAlert;
Plivo.onReady = onReady;
Plivo.init();

Registering using your Plivo Endpoint

Register using your Plivo Endpoint credentials

var username = 'johndoe12345';
var pass = 'XXXXXXXX';
Plivo.conn.login(username, pass);

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";
Plivo.conn.call(dest);

Accepting a call

This is how an incoming call should be answered once the onIncomingCall event is received

Plivo.conn.answer()

Sending DTMF

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

var digit = "1";
Plivo.conn.send_dtmf(digit);

Registering Events

The Plivo JS objects receives many events. Take a look at how to add listeners for those events. In the following example the onLogin function is added as a listener for the onLogin event. To take a look at all the possible events, check the Events section

function onLogin() {
    console.log("I have received the onLogin event !");
}
Plivo.onLogin = onLogin;

Config

Config parameters

Attribute Description Allowed Values Default Value
fallback_to_flash If set to true uses flash in browsers which do not support WebRTC true/false true
debug Enable debug message in JS log true/false false
mask_page_on_perm Disable/masking page when webrtc/flash ask for permission to use microphone true/false false
perm_on_click Set to true, if you want to ask for mic permission before each call. Set to false, if you want to ask for mic permission on page load true/false false

Methods

These are the methods exposed by the PlivoJS object

Method Description
Plivo.init(config) Initialize the PlivoJS object
Plivo.conn.login(username, password) Register a Plivo endpoint
Plivo.conn.logout() Log out from a registered Plivo Endpoint
Plivo.conn.call(destination, extraHeaders)

Make a call

  • destination - string - number or sip address,
  • extraHeaders - Check here
Plivo.conn.answer() Answer an incoming call
Plivo.conn.hangup() Hangup an ongoing call
Plivo.conn.reject() Reject an incoming call
Plivo.conn.send_dtmf(digit)

Send digits as dtmf.

digit can be a one char string : "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#"

Plivo.conn.mute() Mute the mic
Plivo.conn.unmute() Unmute the mic
Plivo.setRingTone(url)

Set ringtone file.

url can be:

  • false or null = disable ringtone
  • true = use ringtone from Plivo
  • url string = use ringtone from specified url
Plivo.setRingToneBack(url)

Set ringbacktone file.

url can be:

  • false or null = disable ringbacktone
  • true = use ringbacktone from Plivo
  • url string = use ringbacktone from specified url
Plivo.setDtmfTone(digit, url)

Set dtmf tone for a digit.

digit can be a one char string : "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#"

url can be:

  • false or null = disable tone for the digit
  • true = use tone from Plivo for that digit
  • url string = use tone from specified url for that digit
Plivo.setDebug(debug)

This is used to enabled logging in the console.

debug : "true" or "false". If true, then logging is enabled.

Events

PlivoJS object receives events that can be listened to.

Event Description
onReady Occurs when PlivoJS is ready to be used
onLogin Occurs when a login is successful
onLoginFailed Occurs when login to the Plivo server fails
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 an outbound call is answered
onCallTerminated Occurs when an outbound call has ended
onIncomingCall(callerName, extraHeaders)

Occurs when there is an incoming call

  • callerName - string - is the callers phone number or caller name
  • extraHeaders - Check here
onIncomingCallCanceled Occurs when an incoming call is cancelled by the caller
onCallFailed(cause) Occurs when an outbound call fails
onWebrtcNotSupported Occurs when the browser does not support WebRTC
onMediaPermission Occurs when the user media access permissions are granted

Extra Headers

Sometimes, you may need to add extra sip headers. The extraHeader param serves that purpose. It is in the form of javascript object of key value pairs. Where the key is the header name and the value is the header value.

Example:

var extraHeaders = {
    'X-PH-Header1': 'value1',
    'X-PH-Header2': 'value2'
}

The following rules need to be followed for header names:

  • In the form of X-PH-Yourfield.
  • Yourfield must start with an uppercase letter. Other characters must be in lowercase.
  • Header name can only contain alphanumeric characters(A-Z, a-z, 0-9)
  • Header name can have a maximum length of 24 characters

The following rules need to be followed for header values:

  • Header value may comprise of alphabets(A..Z, a..z), numerals(0-9), and '%' .
  • Header value should have a maximum length of 48 characters

The header name value pairs that do not follow the above rules will not be sent by PlivoJS

Examples

Checkout our github repo for examples