Examples

In the following live demo examples, we use a mock website and Basic HTTP Authentication to simulate logging in to a company portal. When prompted, simply login using the sample credentials:

  login:    jsmith
  password: 12345

The only required parameter for our servlet is a destination (ie. directory number to call). Let's say in our case, the IT Help Desk's extension is: 5555.

Assuming we have jQuery available to us, our POST might look like this:

var helpDeskNumber = '5555';
var paramData = {
    destination: helpDeskNumber
};

$.post('/jabberguest-demo/servlet',  // request path to our servlet
    paramData,                       // parameter data
    function (jsonData) {},          // success callback
    'json');                         // set to explictly expect JSON data back

Now that we have the logic for actually creating a call link, let's put this to use. We could of course use this whenever the page loads, but that is unnecessarily wasteful. Instead, let's allocate the call link only when Jonathan actually clicks on the link.

To do that, we can wrap all of this logic in a click handler for the a element in question. Furthermore, we can redirect immediately once we have the call link URL, making our link behavior almost indistinguishable from any other normal link.

var helpDeskNumber = '5555';
var paramData = {
    destination: helpDeskNumber
};

var createLinkAndGo = function () {
    $.post('/jabberguest-demo/servlet',
        paramData,

        // success callback
        function (jsonData) {
            // redirect once we have our call link url
            var callUrl = jsonData.callUrl;
            window.location = callUrl;
        },

        'json');
};

// bind our click handler to the element in question
$('#callHelpDesk').on('click', createLinkAndGo);

↱ Open the live demo.

The call link management REST API allows for various properties to be set when creating a call link. It is at your discretion as to which parameters should be allowed to be passed in by the client-side.

That being said, for demo purposes here are some examples of parameters that can be set on the client-side in order to customize the names use in the Jabber Guest call.

var helpDeskNumber = '5555';
var paramData = {
    destination: helpDeskNumber,

    // call recipient-side will see that 'Jon S.' is calling
    callerName: 'Jon S.',

    // Jonathan will see that he is about to call 'IT Help Desk'
    displayName: 'IT Help Desk',

    // 'Jon S.' will not automatically call 'IT Help Desk'
    autoCallAfterSecs: -1,

    // both 'Jon S.' and 'IT Help Desk' can start/stop sending video during call
    videoPolicy: 'sendrecv'
};

Please refer to the Call Link JSON Attributes for a list of these parameters available to set before making the REST call to the Jabber Guest server.

↱ Open the live demo.

Embedding the Widget

Use VideoWidget.js

In many cases, the easiest way to embed the widget is to use our provided wrapper VideoWidget.js, which takes care of dynamically creating and attaching an iframe element to a DOM node that you specify. There are performance benefits from this approach, since it defers the loading and initialization logic until you absolutely need it.

To make use of it, copy it into your web project, and in the source of your containing web page:

  1. Add a DOM container with id="videowidget" (or customize your own in VideoWidget.js)

     <!-- The <iframe> will be inserted in this tag -->
     <div id="videowidget"></div>
    
  2. Set a global videowidgetParams object (or customize your own in VideoWidget.js)

     window.videowidgetParams = {
    
         // a valid call link
         callUrl: callUrl,
    
         // Event will be 'CALLSTARTED' or 'CALLENDED'
         onEvent: function (e) { ... }
     };
    
  3. Attach VideoWidget as a script element as needed via Javascript.

     var script, parentElem;
    
     // create a script element for VideoWidget.js
     script = document.createElement('script');
     script.type = 'text/javascript';
     script.async = true;
     script.src = "js/VideoWidget.js";
    
     // attach to DOM to trigger
     parentElem = (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]);
     parentElem.appendChild(script);
    

Important: as this demo uses a host with a self-signed SSL certificate, please click through https://jabberguestsandbox.cisco.com and accept the security warning in your browser first before opening the demo.

↱ Open the live demo.

...Or roll your own

The VideoWidget.js is a fully-functional sample that can be dropped into an existing codebase with minimal changes required. However, for those that prefer to roll their own solution, here are the basic details of how to do that.

Use an iframe

To embed the widget, use an iframe element whose src is a valid call link, but with the additional parameter of widget=true in the querystring.

For example, a valid call link this:

  https://www.example.com/call/webmaster

...would become this:

  https://www.example.com/call/webmaster?widget=true

And so, the HTML of a page embedding the widget might look like this:

  <div id="widget-container">
      <iframe id="my-widget" src="https://www.example.com/call/webmaster?widget=true" />
  </div>

Again, it is advisable to mention that as this widget is meant to be used for dynamic calling, it is likely that you will only want to attach the iframe element to the DOM only as needed via Javascript.

Querystring parameters

Name Value Required
widget true Y
uselang ex. en, fr, zh, en-US, ... N (defaults to browser language setting)

Javascript Events

There are only two events emitted by the iframe once it has been initialized:

Event Name Description
CALLSTARTED Fired when the 'Call' button is clicked.
CALLENDED Fired when an established call has ended, or a server error has occurred.

These events can be handled by listening to the message event in the containing page. For example:

// simple handler
var myHandler = function (e) {
    console.log('e.event: ', e.event);
    console.log('e.data: ', e.data);
}

// listen for the 'message' event
if (window.attachEvent) {
    window.attachEvent('onmessage', myHandler);
} else {
    window.addEventListener('message', myHandler, false);
}

Cleaning up

To tear down the widget, simply remove it from the DOM:

var elem = document.getElementById('my-widget');
if (elem) {
    elem.parentNode.removeChild(elem);
}

For our demo purposes, deleting a call link once it is no longer needed can be done simply via an AJAX call of type DELETE.

$.ajax({
    type: 'DELETE',
    url: '/jabberguest-demo/servlet',
    success: function () {
        console.log('Call link deleted.');
    }
});

Note: in our demo app, for security reasons, we do not allow the web client to specify the restUrl to be deleted. Instead we track this value in a session attribute, that the servlet itself uses when making the REST call.

Imagine if Jonathan called the IT Help Desk with a question, and then decided to call the HR Help Line with another question (or vice versa). This might be an appropriate time to delete the call link just created, right before generating another.

One simple way to ensure the order of this is to use an AJAX request in synchronous mode.

// delete the previous call link
$.ajax({
    type: 'DELETE',
    url: '/jabberguest-demo/servlet',

    // use synchronous mode to ensure link is deleted first
    async: false,

    success: function () {
        console.log('Call link deleted.');
    }
})

// and then create the new link
$.post('/jabberguest-demo/servlet',
    paramData,
    function (jsonData) { ... },
    'json');

However you will likely want to leave everything as asynchronous as possible and simply chain them together using a Promise-compatible library. jQuery for example supports this Promise-style interface:

// delete the previous call link
$.ajax({
    type: 'DELETE',
    url: '/jabberguest-demo/servlet',
    success: function () {
        console.log('Call link deleted.');
    }
})
// and then create a new one
.then(function () {
    $.post('/jabberguest-demo/servlet',
        paramData,
        function (jsonData) { ... },
        'json');
});

Note: for demo simplicity and readibility purposes, we demonstrate the method using synchronous AJAX.

↱ Open the live demo.