Last month we released a new version of our SDK which includes a ton of new features and will make it ever so simple for you to build Web applications and bridge the gap between the browser and your SIP infrastructure. Let’s start the year right and discover together how we can quickly get up and running with the new SDK.

What you will need (pre-requisite):

Additional resources (in case you get lost):

Getting Started

Create an HTML file

That should be pretty easy for you, I hope. Ideally you should get an environment that runs Javascript in your browser (eg. LAMP, MAMP, NodeJS, anything you want)

Add the dependencies

Once you have your full HTML page created, we will add the required Javascript dependencies. Don’t forget these go in the <head> section of your file, but you already knew that!

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

<script src="http://webrtc.voxbone.com/js/voxbone-latest.js" type="text/javascript"></script>

<script src="http://webrtc.voxbone.com/js/jssip-latest.js" type="text/javascript"></script>

Build the init() Function

The init() function gathers a bunch of important parameters that will allow calls to get through and pass additional information. This is where most of the magic happens.

The init() function should be visible somewhere in your HTML page as it will be called by the body tag (or any other tag) when the page loads!

Here’s what goes into the init() function:

function init(){
  voxbone.WebRTC.authServerURL = "http://webrtc.voxbone.com/rest/authentication/createToken";
  voxbone.WebRTC.customEventHandler = eventHandlers;
  voxbone.WebRTC.basicAuthInit(username, key)
};

Many more things can go into it: some we’ll worry about later, some you can check out in the documentation.

For now, the most important items are the authServerURL (which you do not touch!), the customEventHandler (which we’ll worry about later), and the authentication method – let’s worry about that now!

No longer do you need the dreadful (but super useful) application token! Though you can use it to build white-label applications easily, if you are just looking to quickly build a click-to-call app you can instead use the new basic authentication method.

The way it works is that you replace the username and key part with your own – anyway you like! (declarative, non-declarative, public, private, unicorns, etc…)

If you are weary of getting your credentials public, then you should think about using NodeJS or PHP to store them privately and call them in your front end. Or use the token generators with the normal webrtc.init(#voxrtc_config) method! More about tokens here.

We are done with the init() function, for now, let’s move on. Don’t forget to build the init() function within a <script> tag after the dependencies, but you already knew that!

Initialize the configuration function on load

Now that init() exits and is ready to be used we can launch it (initialize) when the page loads. If you are familiar with Javascript, you know you have a lot of options. Here are a few:

//1) Within the body tag
<body onload="init()">

//2) With pure JavaScript
window.onload = init();

//3) With JQuery
$(document).on('ready', init());

Whatever you do, make sure init() is declared before calling it!

Place a call!

So now we are fully initialized and authenticated. If you open the browser’s developer console (hopefully you are using a supported browser) you will see some things going on. If you see error messages, check out our troubleshooting guide for authentication issues.

If everything is fine, we can now make a call. That’s the easiest part! You can place the voxbone.WebRTC.call() method anywhere you want. Here’s an example:

<button onclick="voxbone.WebRTC.call('+16170000000')">Call</button>;

Bells and Whistles

So now that we’ve swiftly gone through our minimum viable product, let’s play around with the interesting new features.

Detecting Call Status with isCallOpen()

isCallOpen() is a function that can be used anywhere to check the call status of the application. It returns true in following conditions: user is in middle of a call or a call attempt is already in progress. You can use this function to enable/disable the ‘call’ button on their web page. Here’s a simple example:

var callStatus = voxbone.WebRTC.isCallOpen();
if (callStatus == true){
   document.getElementById("your-call-button").style.disabled = true;
}else{
   document.getElementById("your-call-button").style.disabled = false;
}

Playing with the New Event Handlers

Remember voxbone.WebRTC.customEventHandler = eventHandlers; from the init() function? Here’s where we use it! Declare an eventHandlers object prior the init() function and set it like so:

var eventHandlers = {};

We already had a few events like ‘progress’, ‘failed’, or ‘ended’. Here are a few new ones. Remember, whenever you want to add functionality to them just add a line similar to this one in the eventHandlers object for each event:

'progress':   function(e){ //some functionality}

Accepted

This one just replaced “Started” in version 1. It tells you when the call has been accepted ont he receiving part, it will return true if you use isCallOpen().

localMediaVolume

This one indicates the loudness of the speech at the calling party. Here is how to use it:

'localMediaVolume' = function(e) { console.log(“Local volume is ”+e.localVolume);}

getUserMediaFailed

This event indicates that getUserMedia failed which can be a result of browser not being able to access the mic (usually a user not giving permission). Here is a sample implementation:

'getUserMediaFailed': function(e) {alert("Failed to access mic");}

Terminating ongoing calls with unloadHander

This method  will take care of terminating any ongoing call, making sure everything is cleaned when you launch or close your web app. You can use it just like the way we used init():

//1)Using HTML body tag
<body onbeforeunload="voxbone.WebRTC.unloadHandler();">

//2) Using pure JavaScript
window.onbeforeunload = voxbone.WebRTC.unloadHandler();

//3) Or with JQuery...

Playing with DTMF and IVR Traversal

We’ve added a lot of functionality to DTMF!

dialer_string

This is the most exciting features, it allows you to give the user some automation when reaching an IVR by sending a string of digits upfront with the call. It is ideal to place this within the init() function

In some cases,  it is desirable for web application to enabled automated IVR traversal. For automated IVR traversal, web application needs to configure the dialer_string, digits configured in the dialer string will be sent automatically to the remote party after the call is established. Dialer string is comma separated, to define a specific pause between digits, we add another entry like 1,700ms,2, this will add a 700ms of pause between digits 1 & 2. Example = ‘1,2,3,1200ms,4,5,900ms,6,#’

Here’s how to use it:

voxbone.WebRTC.configuration.dialer_string = "1,300ms,4,5,2000ms,6,#";  

digit_duration & digit gap

Digit duration it defines the duration of digits sent by the web application. By default, default digit duration is 100 ms.

voxbone.WebRTC.configuration.digit_duration = 1000;   

Digit gap defines the gap between digits sent by the web application. By default, this value is 500ms.

voxbone.WebRTC.configuration.digit_gap = 1400;

Use them both within the init() function.

Troubleshooting with Voxbone

We now enable the voxbone webrtc sdk to push all the call logs to a voxbone defined backend, where they can be used for troubleshooting. By default, this option is disabled. When enabling it, the logs will be pushed if you use the unloadHander function as this method actually takes care of pushing the logs (if post_logs is enabled).

You can set it to true in the init() function:

voxbone.WebRTC.configuration.post_logs = true;

That’s it! We’ve covered all the new and exciting features. I hope that 2016 will bring you a lot of creativity and productivity. Let us know what you think of the new SDK!