<

Browser SDK

Introduction

Browser SDK 2.0 allows you to integrate voice calling to your webapp. This guide will help you build a web application that can make and receive calls to regular telephone numbers (PSTN numbers).

Make an outgoing call from a browser

Making an outgoing call consists of the following steps before the call is established.

  1. An endpoint is used to make a call from the web application. This endpoint is attached to a Plivo application.
  2. The application invokes the answer_url. The answer_url is provided when the application is configured.
  3. The answer_url returns a valid Plivo XML which contains instructions on which number the call should be connected to.
  4. The call from the browser is then connected to the PSTN number.

Now that we understand the overall call flow, let’s dive into each of the steps in detail. But before we begin here are some pre-requisites that we will make use of in this tutorial.

Pre-requisites for this tutorial:

  1. Create a Plivo account: You can sign up for a free Plivo account here
  2. You need an Endpoint created in Plivo dashboard. You can follow this tutorial to create an endpoint.
  3. You need to create an application and attach it to the endpoint. You can read more on using a Plivo application here.
  4. You can host a public HTTP server to serve an XML. You can refer to this guide for setting up the server.

Step 1: Create a web UI & configure an endpoint

Lets first create a simple UI which will take a number as an input. You can copy paste the following code to an HTML file (Let’s call this outbound.html). When you host it in your web server you should see a simple UI that has a text box where you can enter a phone number.

1
2
3
4
5
6
7
8
9
10
11
12
13
<html>
<head>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script type="text/javascript" src="https://cdn.plivo.com/sdk/browser/v2/plivo.min.js"></script>
</head>
<body>
<img src="https://s3.amazonaws.com/plivo_blog_uploads/static_assets/images/press/logo-on-white.png" height="100px" />
<form>
  <h2>Enter the phone number to call </h2><input type="text" id="number"/>
  <input type="submit" value="Call" />
</form>
</body>
</html>

To use Plivo BrowserSDK 2.0 with this UI, we need to include plivo.min.js in the <script> tag.

For this UI to initiate the call, we need to create an Plivo endpoint and configure it with few settings. More specifically we need to: Create an object (‘plivoClient’) and configure it with default settings.
Use this object to login to the endpoint (credentials are created during the pre-requisite)

We have created a function named configure() to accomplish these steps. We will invoke this configure() function when all the page elements in the DOM are ready using Jquery. The following snippet shows the updated code with configure() function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<html>
<head>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script type="text/javascript" src="https://cdn.plivo.com/sdk/browser/v2/plivo.min.js"></script>
  <script type="text/javascript">
    var plivoClient;
    function configure(){
      var options = {
      "debug":"DEBUG",
      "permOnClick":true,
      "audioConstraints":{"optional":[{"googAutoGainControl":false},{"googEchoCancellation":false}]},
      "enableTracking":true
      };
      plivoClient = new window.Plivo(options);
      plivoClient.client.login("<endpoint_username","<endpoint_password")
    }
    $( document ).ready(function(){
      configure();
      console.log('configure completed')
    });
  </script>
</head>
<body>
<img src="https://s3.amazonaws.com/plivo_blog_uploads/static_assets/images/press/logo-on-white.png" height="100px" />
<form>
  <h2>Enter the phone number to call </h2><input type="text" id="number"/>
  <input type="submit" value="Call" />
</form>
</body>
</html>

Step 2: Initiate the call from the UI

The next step is to initiate the call when the user clicks on the call button. To initiate the call we will implement a function called “makeCall()” and initiate the call using “plivoClient.client.call” API. The following code demonstrates how to initiate the call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<html>
<head>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script type="text/javascript" src="https://cdn.plivo.com/sdk/browser/v2/plivo.min.js"></script>
  <script type="text/javascript">
    var plivoClient;
    function configure(){
      var options = {
      "debug":"DEBUG",
      "permOnClick":true,
      "audioConstraints":{"optional":[{"googAutoGainControl":false},{"googEchoCancellation":false}]},
      "enableTracking":true
      };
      plivoClient = new window.Plivo(options);
      plivoClient.client.login("<endpoint_username","<endpoint_password")
    }
    function makeCall(){
      var dest = document.getElementById('number').value
      console.log(dest)
      var extraHeaders = {'X-PH-Test1': 'test1', 'X-PH-Test2': 'test2'};
      plivoClient.client.call(dest, extraHeaders);
    }
    $( document ).ready(function(){
      configure();
      console.log('configure completed')
    });
  </script>
</head>
<body>
<img src="https://s3.amazonaws.com/plivo_blog_uploads/static_assets/images/press/logo-on-white.png" height="100px" />
<form action="javascript:makeCall()">
  <h2>Enter the phone number to call </h2><input type="text" id="number"/>
  <input type="submit" value="Call" />
</form>
</body>
</html>

Step 3: Fetch a valid Plivo XML file to connect the call to desired number

When the “plivoClient.client.call” method is invoked, the XML to control the call flow is fetched as below: First the application attached to the endpoint using which the call is made is located. The answer_url specified in that application is invoked to fetch a valid XML to continue the call.

You can create an application and attach it to an endpoint as given in this tutorial. The answer_url of this application needs to return an XML file.

You can learn more about how to set up a server to return an XML in this guide. Here we present a sample code snippet using Flask.

1
2
3
4
5
@app.route('/answer/', methods = ['GET','POST'])
def answer_url():
    number = request.form.get('To')
    resp = '<Response><Dial callerId="141512345"><Number>{number}</Number></Dial></Response>'.format(number=number)
    return Response(resp,mimetype='text/xml')

This code returns an XML as follows.

1
2
3
4
5
<Response>
  <Dial callerId="141512345">
    <Number>141500000</Number>
  </Dial>
</Response>

The XML connects the outgoing call from the endpoint to the destination using the and element. Here we have assumed that “141500000” is the destination number and “141512345” is a valid callerId that we would like to use.

Once the XML is fetched the destination number gets called. Once the receiver picks up the call, both the participants can speak on the call.

Next steps

  • You can refer to the full fledged BrowserSDK sample application for providing more controls such as hanging up and muting the call.