User ID
Password
CID
Domain

Sansay's Webphone is a WebRTC client that for Sansay's WebSBC. It is written as such that it can work right out of the box with very little coding, at the same time offer the flexibility such that developers can customerize it to their own needs.

At the high level Sansay Webphone provides a very easy to use JQuery plugin API. By using JQuery plugin, web developers can get a webphone running in no time with only a few lines of Javascript codes. While JQuery plugin is the easy way to implement a webphone, it just implements the basic functionalities and a plain UI that may not be suitable nor is it desirable for users of all levels. Sansay Webphone also exposes a lower level APIs that provide supports for all functions needed to implement a full-feature, real-time communication application.

The following sections should provide enough detail information for developing a WebRTC webphone at the two level mentioned above.



Out-Of-The-Box Quick Start

Sansay Webphone JQuery plugin provides a very easy to use API for web developers. The followings are required and must be included by the page that contains the Sansay Webphone.
  • JQuery (version 1.7.2 or later)
  • Bootstrap (version 3.0 or later)
  • Sansay WebSBC client engine: websbc-client.js. Delivered as part of the SDK under sansay/js directory
  • Sansay Webphone plugin: webphone-plugin.js. Delivered as part of the SDK under sansay/js direcotry
All one needs is a <div> as container where you want the webphone's keypad to be located on your page
<div id="my-example-container"></div>

Then initialize the plugin in the container when the document is ready.
$(document).ready(function() {
  $("#my-example-container").webphone("websbc.example.com");
  ...
});

where

websbc.example.com is the domain name of your WebSBC server


To activate webphone invoke login() with the valid credentials.
$("#my-example-container").webphone.login("5551000", "abcd1234", "Joe Blow", "common");

where

"5551000" is the SIP user

"abcd1234" is the SIP password

"Joe Blow" is the Caller ID

"common" is the domain that the user belongs to in the WebSBC server

The login() function also takes two optional callback functions for successful login and logout handling. Please consult the Plugin API tab above or the example in the SDK package for more detail usage.
It is recommended that SIP user and password information should not be hardcoded in the javascript code. Use AJAX or other mechanism to obtain this information at runtime before invoking login().

The example demo on the left obtain SIP user and password information from the user inputs.

Invoke logout() to deactivate webphone
$("#my-example-container").webphone.logout();



Installation


Begin by clicking “Download SDK” above. Extract the contents of the Zip and then copy all of the content in the 'sansay' directory to the 'Root' directory of your web server.


Dependencies


  • JQuery (version 1.7.2 or later)
  • Bootstrap (version 3.0 or later)

Create A Webphone-Enabled Web Page


Along with the CSS and JS files needed for JQuery and Bootstrap as mentioned above, the following JS files must also be included on your 'Webphone-Enabled' web page.
  • Sansay WebSBC client engine: sansay/js/websbc-client.js - Delivered as part of the SDK.
  • Sansay Webphone plugin: sansay/js/webphone-plugin.js - Delivered as part of the SDK.
On your web page, create a div with “class='container'”. This is the container where the webphone will live
<div id="my-phone" class="container"></div>

You will need to instantiate the webphone-plugin when the page is ready. A domain name with a legitimate SSL certificate is required for this step. Below is a code snippet that demonstrates how to instantiate the webphone-plugin:
$(document).ready(function() {
  $("#my-phone").webphone("websbc.example.com");
  ...
});

OR optionally, to customize the look-and-feel with more 'options':
$(document).ready(function() {
  $("#my-phone").webphone("websbc.example.com", options);
  ...
});

**The look-and-feel customization will be covered in a later section.**

For most applications where, by logging into the website, users are authorized to use the webphone, the parameters required to login the webphone to the WebSBC should also be available (We recommend using an AJAX call to acquire credentials at runtime instead of hard-coding them on the web page).
$("#my-phone").webphone.login(user_sip_id, user_sip_password, user_caller_id, user_domain);


Definitions


user_sip_id – User ID for SIP authentication.

user_sip_password – User Password for SIP authentication.

user_caller_id – Input for caller ID.

user_domain – Fully Qualified Domain Name(FQDN) of WebSBC User is bing registered to. Field is required as part of authentication for WebSBC if such is configured.


In addition to the parameters listed above, login() accepts two optional callback functions as follows:

$("#my-phone").webphone.login(user_sip_id, user_sip_password, user_caller_id, user_domain, service_active, service_inactive);

service_active and service_inactive are callbacks that will be invoked in the event of phone service becoming available or unavailable, respectively. Typically, these callbacks trigger UI change to further notify the users of their webphone's service availability.




Out-Of-The-Box Customization


The webphone-plugin can be further customized by the 'options' parameter. The following are the customizable options:


Definitions


theme – A 'dark' and 'light' theme are provided in the SDK. 'dark' is the default theme if none is specified.

position – The webphone can be positioned on the 'left' or 'right' side of the screen. 'right' is default position if none is specified.

ring_tone – Sansay's webphone comes with a default ringtone. This is the ringtone for incoming calls. Users can customize by pointing this to a different ringtone(.wav) file.

logo – The webphone shows a Sansay logo on its upper left hand corner. This option allows users to change the logo to their own by pointing this to a different logo file.


Example:
$("#my-phone").webphone.login("websbc.example.com", {theme: 'light', postition: 'left', ring_tone: 'my-file-path/my-ring-tone.wav', logo: 'my-logo-path/my-logo.png'});



Advanced UI Customization


Though the Sansay webphone already provides some level of customization, users are welcome to design their own 'skin' for the webphone. In the SDK, you may find the HTML and CSS files that can be modified.
The following shows their locations:

      sansay/
      |---- webphone-plugin.html
      |---- css/
        |---- webphone-dark.css
        |---- webphone-light.css
    

'webphone-plugin.html' contains the 'skin' and the CSS files define the other attributes such as colors, fonts and sizes(height and width). As long as the CSS class name and the DOM IDs used in those files are not modified, the webphone should work.

If you take a closer look at the 'webphone-plugin.html' file you may find that it has FOUR 'primary' sections:
  • webphone-icon
  • webphone-incoming-call
  • webphone-video
  • webphone-keypad


These sections are defined below:

Definitions


webphone-icon – This contains the status icon that will be shown or hidden based on the status of the phone, i.e. whether it's logged in and active, or not.

webphone-incoming-call – This is the panel that is shown when there is a incoming call to prompt the user to either 'Answer' or 'Reject' the call.

webphone-video – This panel is used for video calls.

webphone-keypad – This is the panel where the keypad is defined.


API