WebRTC SDK Documentation

Voxbone’s WebRTC WebSDK allows you to make and receive calls using Voxbone’s DIDs directly from webRTC-enabled web browser. Using this SDK and documentations, you will be able to create applications like Click to Call, Conference bridges and web-based call centers. Read the documentation to get an idea of what can be done and check out some sample applications demo available here

The Voxbone WebRTC SDK uses a slightly modified JS SIP library. This means that you can also refer to the JSSIP documentation for additional feature implementation.

Including the Javascript

Include the Voxbone javascript files and its dependencies as shown below

<script src="//cdn.voxbone.com/voxbone/voxbone-2.1.min.js" type="text/javascript"/>

Authentication

You can decide whether to authenticate via basic auth or use token generators.

1. Authentication via basic auth

Basic authentication permits anyone with the code to call your DID within the security parameters defined by voxbone - this is the fastest way to get started and how most Voxbone SDK customers start.

Provide your username and webrtc key in the basicAuthInit() function.

voxbone.WebRTC.basicAuthInit(username, secret_key)

2. Authentication with token generator

In the advanced authentication mode, you run your own authentication server with our samples and can control who can and cannot make a call against your DID.

An authentication token needs to be provided for initializing the voxbone.WebRTC object.

var voxrtc_config{
    "key":"ABwxcFX6ayVxu/uNuZu3eBsjrFeg=",
    "expires":1426067127,
    "username":"a_username"
}

Then use it with the voxbone.WebRTC object.

voxbone.WebRTC.init(voxrtc_config)
  • username: This is your credentials username
  • expires: expiration date of the generated key (in seconds, epoch time)
  • key: this is a base64 representation of an HMAC SHA1 of expires:username, salted with your password.

Advanced Auth Token Generator Examples

Various example on how to generate the authentication token can be found on Github such like

Or download one of the WebRTC standalone applications here. For each SDK, add your credentials in the appropriate files and your WebRTC enabled phone number.


Making a call

Making a call to any Voxbone DID or SIP endpoint.

var dest = "+32000000000";
voxbone.WebRTC.call(dest);

Sending DTMF

The code below shows you how to send a DTMF tone when in a phone call.

var digit = "1";
voxbone.WebRTC.sendDTMF(digit);

Setting Custom Event Handlers

Event handlers will enable you to control what goes on in your application during call events (eg. Call failed, in progress, started, or ended).

// set custom event handlers
voxbone.WebRTC.customEventHandler = eventHandlers;

An example of this is to set a ringback tone to the event ‘progress’. Here are a few event handlers that change the “Status_message”’s text for each event.

// Register callbacks to desired call events
   voxbone.WebRTC.customEventHandler.progress = function(e) {
      document.getElementById("status_message").innerHTML="Calling " + document.getElementById('number').value;
    };
    voxbone.WebRTC.customEventHandler.getUserMediaFailed = function(e) {
      document.getElementById("status_message").innerHTML="<b><font color='red'>Failed to access mic: " + e.data.cause + "</font></b>";
    };
    voxbone.WebRTC.customEventHandler.failed = function(e) {
      document.getElementById("status_message").innerHTML="<b><font color='red'>Failed to connect: " + e.data.cause + "</font></b>";
    };
    voxbone.WebRTC.customEventHandler.accepted = function(e) {
      document.getElementById("status_message").innerHTML="<b><font color='green'>In Call</font></b>";
    };
    voxbone.WebRTC.customEventHandler.ended = function(e) {
      document.getElementById("status_message").innerHTML="<b><font color='red'>Call Ended</font></b>";
    };
    voxbone.WebRTC.customEventHandler.authExpired = function(e) {
      voxbone.WebRTC.basicAuthInit(username, key);
    };

Configurations

Config parameters

Attribute Description Allowed Values Default Values
voxbone.WebRTC.authServerURL Server URL that processes authentication String "https://webrtc.voxbone.com/rest/authentication/createToken"
voxbone.WebRTC.preferedPop Bypass Ping mechanism and enforce POP to be used String ('BE', 'LA', 'CN') null
voxbone.WebRTC.configuration.uri Set the caller-id, domain name gets automatically stripped off Valid SIP URI "voxrtc@voxbone.com"
voxbone.WebRTC.configuration.display_name Add Display Name to the call String null
voxbone.WebRTC.configuration.dialer_string Digits to dial after call is established. Example = '1,2,3,1200ms,4,5,900ms,6,# String null
voxbone.WebRTC.configuration.digit_duration Gap between digits in milliseconds. Integer 100
voxbone.WebRTC.configuration.digit_gap duration of digits sent by the web application in ms. Integer 500
voxbone.WebRTC.audioComponentName id of the audio html tag String "peer-audio"
voxbone.WebRTC.auth.TTL Time to live for the auth hash key Integer 300
voxbone.WebRTC.auth.varname Variable name for the auth hash key String voxrtc_config
voxbone.WebRTC.configuration.post_logs If enabled allows voxbone webrtc sdk to push all the call logs to a voxbone defined backend, where they can be used for troubleshooting. Boolean false
voxbone.WebRTC.configuration.register Specifies if the SDK should try to register a SIP user Boolean false
voxbone.WebRTC.configuration.log_level Sets the JavaScript console log level (allows suppression) voxbone.Logger.log_level.INFO
voxbone.Logger.log_level.ERROR
voxbone.Logger.log_level.NONE
voxbone.Logger.log_level.INFO

Methods

These are the methods exposed by the Voxbone WebRTC object and provided by JSSIP.

Method Description
voxbone.WebRTC.init(voxrtc_config) Initialize the VoxboneJS object using voxrtc_config token.
voxbone.WebRTC.basicAuthInit(username,key) Initialize the VoxboneJS object using basic auth.
voxbone.WebRTC.call() Make a call to a Voxbone DID
voxbone.WebRTC.sendDTMF() Send digits as dtmf. digit can be a one char string : "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#"
voxbone.WebRTC.hangup() Hangup an ongoing call
voxbone.WebRTC.mute() Mute the mic
voxbone.WebRTC.unmute() Unmute the mic
voxbone.WebRTC.isCallOpen() Checks the call status of the webrtc user. Returns a boolean
voxbone.WebRTC.isWebRTCSupported() Checks if client browser supports WebRTC or not. Returns a boolean
voxbone.WebRTC.rtcSession.terminate(); Similar to hangup, terminates the current session
voxbone.WebRTC.unloadHander() Takes care of terminating any ongoing call and pushes webrtc logs to Voxbone server. Sshould be tied to the page DOM unload event (onbeforeunload).

Events

Voxbone JS object’s events that can be listened to and used for event handling.

Event Description
progress Occurs when call initiated
failed Occurs when call failed due to connection, call rejected, or cancelled by caller
accepted Indicates that call is successfully established
ended Occurs when source or destination hangs up after call started.
getUserMediaFailed Indicates getUserMedia failed - browser not being able to access the mic.
localMediaVolume Indicates the volume of the speech at the calling party. Range of 0 to 1.
newDTMF Occurs when a new DTMF is sent.
authExpired It indicates that authentication token between the web application and Voxbone is about to expire. To avoid authentication errors, web application should call the API ‘basicAuthInit’ to regenerate a new authentication token.

Events related to inbound calling are:

Event Description
connected Websocket connection to the API is successful.
registered Registration to external SIP proxy is successful and the SIP user is ready to receive calls.
onCall Indicates there is an incoming call.

Extra Headers & Context

The VoxboneJS comes with two extra Voxbone SIP headers. Use this option to manually pick the Voxbone POP if you are targeting a specific geolocation or to define context. Voxbone The extraHeader param is in the form of a javascript object. The format is ‘header_name’: ‘header_value’.

Voxbone headers that can be set:

var headers = {
    'X-Voxbone-Pop': 'value',
    'X-Voxbone-Context': 'value'
}

Alternatively, context can also be set through the ‘context’ object within the SDK. It should be set before calling init or basicAuthInit functions.

//Context is a variable which will hold anything you want to be transparently carried to the call
//It is highly recommended to build the context data as a javascript object and send it as a JSON string.

var yourContext = new Object();

yourContext.username = 'customername';
yourContext.cacheExpire = '2017-01-30 12:23:33.21341';
yourContext.remainingCredits = 1234.56;
.
.
.


voxbone.WebRTC.context = JSON.stringify(yourContext);

Finally, you can parse the context data sent through our SDK on your SBC or SIP proxy by looking for the ‘X-Voxbone-Pop’ header.

SIP registration and answering calls

Our WebRTC to SIP gateway service can also be used to receive and answer incoming calls to SIP addresses in the browser. You can test the functionality on our SIP-to-WebRTC for free.

To use this service, you should POST your SIP users and SIP server information to our API first. If you want to get access to our SIP-to-WebRTC API, please contact us.

How does it work?

Basically, we forward the SIP REGISTER messages from any web application to your SIP servers through our WebRTC gateway service. You can configure and manage the information needed for successful registration via our API. Here’s the information you need to POST:

  • The SIP server address to route the REGISTER messages to
  • Allowed IP ranges for SIP registration from the browser
  • SIP usernames and passwords

Before calling init or basicAuthInit functions you should add the following to your configuration

voxbone.WebRTC.register = true;
voxbone.WebRTC.configuration.uri = 'sip:<Your-SIP-User-to-be-registered>@sip.2webr.tc';

When a call is received the onCall event is triggered. Listening to this event, you can modify your UI and answer/decline the incoming call like this :

//register a function to handle the call
var ringtone;

voxbone.WebRTC.onCall = function (data, handleCall) {
  console.log('recieved a call');
  //you can play a ringtone by creating an <audio> element
  ringtone = document.createElement('audio');
  ringtone.id = 'ringtone-audio';
  ringtone.preload = 'auto';
  ringtone.loop = 'loop';
  ringtone.src = 'https://upload.wikimedia.org/wikipedia/commons/c/cd/US_ringback_tone.ogg';
  ringtone.type = 'audio/ogg';
  document.getElementById('phone').appendChild(ringtone);
}

document.getElementById('answer').on('click',function(){
  document.getElementById('ringtone-audio').remove();
  handleCall(true);
});

document.getElementById('hangup').on('click',function(){
  handleCall(false);
  document.getElementById('ringtone-audio').remove();
});