Introduction
This documentation will cover examples of how to make use of the Jabber Guest call link management REST API. Though our demos are done in Java, any modern framework with a REST client API should be able to integrate in the same way.
Note: Our examples assume we are a hosted webapp in a servlet container (e.g. Tomcat), that is external to our Jabber Guest server. Also, for demo purposes only, we use Basic HTTP Authentication for "logging in".
Our Example Scenario
For the purposes of our examples, let's assume we have a web end-user, Jonathan Smith, that has a computer problem and needs to call the IT Help Desk. By logging into his company's portal site and finding and clicking on a Jabber Guest call link to the IT Help Desk, Jonathan is able quickly and easily get the help he needs.
Basic Workflow
In all of our examples, the workflow is the same.
- We send an AJAX request when an end-user wants to make a call (or when he/she ends a call)
- A servlet accepts this request and in turn makes its own request to our Jabber Guest server via the call link REST API
- When our Jabber Guest server returns a response back to the servlet, the servlet then responds back to the web client with a JSON response
- Our Javascript then uses the JSON response to carry out further any UI actions or behavior
Client-side Discussion
Assuming we are logged in, we start with an AJAX POST to our servlet. For our purposes, let's say that our servlet is found at:
/jabberguest-demo/servlet
Assuming we have jQuery available to us, our POST then might look like this:
$.post('/jabberguest-demo/servlet', // request path to our servlet
{
... // our parameter data
},
function (data) { // success callback
...
},
'json'); // always expect a JSON response
As discussed below, our servlet will go and make the appropriate REST call to our
Jabber Guest server, and return with an appropriate JSON response with two
properties: restUrl
and callUrl
.
restUrl
can be used for further management of the existing call link (e.g. deletion)callUrl
is the URL to use for the end-user to make a call with Jabber Guest
Assuming that our Jabber Guest server is set up at jabberguest.example.com
,
we could expect JSON response data similar to the following:
{
"restUrl": "https://jabberguest.example.com/cjg-api/rest/links/532cda9ae4b09e16fdb78b96",
"callUrl": "https://jabberguest.example.com/call/402741cf-e502-4206-aa25-38d8c6b114b6"
}
...and so revisiting our POST snippet above, we can use this response data as appropriate. Let's say for example we had a hidden button that we want to make appear once a call link is available. We could accomplish this with something like the following:
$.post(...
// success callback
function (jsonData) {
var callUrl = jsonData.callUrl;
// click handler to redirect to the call url
var go = function () {
window.location = callUrl;
};
// bind the click handler, and show the button
$('button#callNow').click(go).show();
},
...);
Server-side Discussion
On the server-side we have a servlet running as if it were part of a company portal. It retrieves the username of the currently signed in user, and then uses the Jabber Guest REST API to create a call link for that user to call whatever number was passed in.
The reason we don't do this directly from the client is that the Jabber Guest REST APIs require admin credentials to use, which of course we would not want to embed in the Java Script of a web application.
Link attributes
Our example servlet is creating a link for the signed in user for a specific destination (extension), and what we do is generate a random request path to make a unique call url, and set an expiration on the link so that it can only be used for one call:
// Destination is set by "destination" parameter
String destination = request.getParameter("destination");
// Set displayName to the user's name
String displayName = request.getUserPrincipal().getName();
String requestPath = UUID.randomUUID().toString();
// Set link to be valid for 10 minutes
Date validBefore = new Date((new Date()).getTime() + (10 * 60 * 1000));
Date validAfter = null; // Valid now
Integer autoCallAfterSecs=null;
String autoCallAfterSecsStr = request.getParameter("autoCallAfterSecs");
if(autoCallAfterSecsStr!=null&&!autoCallAfterSecsStr.trim().equals("")){
try{
autoCallAfterSecs = Integer.valueOf(autoCallAfterSecsStr.trim());
} catch (Exception e){
System.out.println("autoCallAfterSecs parameter error, set as null");
}
}
String videoPolicy = request.getParameter("videoPolicy");
if(videoPolicy==null||videoPolicy.trim().equals("")){
videoPolicy=null;
}
Presumably the call is going to be made right away, so we provide a 10 minute window for the link to be active.
The link should also be deleted so we don't clutter up the system with expired links, but the expiration gives us a safeguard there just in case (and so we can show how to use expiration in our example.)
Calling the REST API
The next thing the servlet does is call the REST API on Jabber Guest to create the link we defined above. To do this we can use BASIC authentication and some admin credentials (the servlet reads those in from web.xml -- definitely not recommended for production!)
Step 1 - Create a JSON link object
The link API is very REST-ful, so we need to POST a JSON object to the links url to create a new link. JSON is fairly simple and you can easily build up a string of JSON by hand, but for this demo we're using a lightweight JSON library to keep things simple (https://github.com/ralfstx/minimal-json):
JsonObject linkObject = new JsonObject()
.add( "isEnabled", true )
.add( "destination", destination )
.add( "displayName", displayName )
.add( "callerName", callerName )
.add( "requestPath", requestPath );
if (validAfter != null)
linkObject.add( "validAfter", dateToJSON(validAfter));
if (validBefore != null)
linkObject.add( "validBefore", dateToJSON(validBefore));
if(autoCallAfterSecs!=null)
linkObject.add("autoCallAfterSecs", autoCallAfterSecs);
if(videoPolicy!=null)
linkObject.add("videoPolicy", videoPolicy);
The only real trick there is that we need to get the dates in a nice format - this particular JSON library doesn't do that automatically. So in case you run into this too, here's a snippet for doing that converstion:
private static String dateToJSON(Date d) {
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
df.setTimeZone(TimeZone.getTimeZone("UTC"));
return(df.format(d));
}
Anway, we now have an object that we can get as a JSON string by simple calling toString().
Step 2 - POST JSON to server
The next step is to POST our JSON to the server. Again to keep things simple we're using a library to help us out here, which helps to illustrate the ideas without having to write a bunch of boilerplate helper code. This time we went with the excelent http-request library that can be found here: https://github.com/kevinsawicki/http-request
Before showing the code snippet to create a link, here are a few things to keep in mind:
- Set the Content-Type header to "application/json" so the server knows we are sending it JSON
- Success is determined by a 201 code (HTTP code for CREATED)
- The URL of the created link is returned in the Location header
- Java doesn't like self-signed certificates by default, which is what Jabber Guest servers come with
That might sound like a lot, but fortunately in code it's really fairly straight forward:
HttpRequest r = HttpRequest
.post(this.linksUrl)
.contentType("application/json")
.accept("application/json")
.basic(this.accountName,this.accountPassword)
.trustAllCerts() // For self signed certs
.trustAllHosts() // For self signed certs
.send(linkObject.toString());
// Look for HTTP code 201 ("CREATED")
if (r.code() == 201)
// Link created, get link URL from Location header
return r.header("Location");
Note that for production you probably do not want to use "trustAllCerts()" because that will create a "man in the middle" attack vulnerability.
Also note that HTTP code 200 OK does not mean that the link was created, so be careful about that in your own application.