The TelServices library (TSLib) is a javascript library for adding telephony capabilities to web applications. TSLib connects with TelServer TelServices gateway and enables to control a desktop phone from an HTML page displayed in your web browser. It does not require any installation on the user's computer.
TSLib API is composed of two tiers:
Quick link: see also the full TSLib API documentation.
TSLib has been tested with Firefox 3, Microsoft Internet Explorer 6, 7and 8, Safari, Google Chrome.
TSLib is built on the Yahoo! User Interface Library (YUI). YUI versions 2.5.2 up to 2.8.1 are supported. YUI mandatory components are:
An adaptive layer is provided to make TSLib compatible with YUI v0.12.2 if needed.
NOTE: to process cross-domain requests with flash the YUI Connection Manager v2.8.1 is required.
To use TSLib in your pages you have to include some javascript files and set some properties.
Prerequisite : TelServer TelServices gateway must be enabled. See TelServices gateway configuration chapter.
You have to install TSLib into the javascript directory of your web server. Let's call this directory "javascriptdir". We assume it is located in the root directory of the web server.
TSLib packages are located in the "util\TelServices-YUILibrary" directory of TelServer.
Copy the directory that fits your needs into the "javascriptdir" directory of your web server. In the following we assume this directory is renamed "javascriptdir/TSLib".
Include TSLib only
<head> <!-- include YUI components here --> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib.js"></script> </head> |
Include TSLib+YUI
<head> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib.js"></script> </head> |
Include TSLib+YUI v0.12 adaptor
<head> <!-- include YUI v0.12 components here --> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSLib/TSLib.js"></script> </head> |
The default configuration of the TSLib library may have to be overriden to fit with your own configuration. User settings are properties of the object "unigone_config".
The javascript file "TSLib-config.js", included in TSLib directory, defines a skeleton of "unigone_config". This file must be included before including the TSLib library.
Mandatory settings are explained here. To set other TSLib optional settings please refer to TSLib API documentation.
Depending on your web server and TelServer locations you have to set the connector used to access TelServer from your web pages. Two connectors are available:
1) Cross-domain configuration - "xhr" connector
In this configuration TelServer and your web server are supposed to be located within the same parent domain but not within the same sub-domain. They may run on the same machine but they use different ports. Unfortunately this configuration is not enabled by the "same origin policy" implemented by web browsers. Security rules don't allow a page from one origin (a page delivered by the web application server) to access a page from another origin (delivered by TelServer). The term "origin" is defined using the protocol, the domain name and the port of the URL.
To allow the browser to connect both the web server and TelServer we have to set the domain property of "mypage.html" and the domain property of the iframe used by TelServer to a parent domain.
In the following, let's assume :
Here is the content of the configuration file "TSLib-config.js" to define the parent domain ("mycompany.local") and the TelServer URL.
try {
document.domain = "mycompany.local";
}
catch (ex) {
alert("TSLib-config - cannot change 'document.domain'");
}
unigone_config = {
TELSERVICES_CONNECTOR: "xhr",
TELSERVICES_TELSERVER_URL: "http://telserver.mycompany.local:8082"
};
|
WARNING : this forces to change the "document.domain" in other pages that are loaded in other frames and that call functions from the page where "TSLib.js" is included. For example, if a popup is created from "mypage.html", loading "popup.html", and makes use of "window.opener.myFunction()" where myFunction is declared in "mypage.html", then the security policy of the browser forces the "popup.html" to set "document.domain" to the value above. To make it easier, one can consider including "TSLib-config.js" within "popup.html".This may be inconvenient for some applications making a heavy use of popups, in which case, the proxy configuration will be more appropriate.
WARNING : TELSERVICES_TELSERVER_URL must be a complete URL (including 'http://').
2) Proxy configuration - "xhr" connector
In this configuration the user is supposed to connect with the web server through a proxy. Both TelServer and the web server could be located in the local network or somewhere in the internet. Note that the proxy may be the same server as the web server if it supports a reverse proxy mode (such as Apache); this can be an alternative to the cross domain configuration. However, it must be noticed that the proxy server will get one open connection by TSLib client.
In the following, let's assume:
The proxy has to define an URL rewrite rule to forward TelServices requests to TelServer. The URLs that target TelServer are identified by the string "telserver" which starts the path part of the URL.
In this example we use an Apache server as a proxy. Here is an excerpt of its configuration (note that for a secure configuration other directives must be used).
The "RewriteRule" is used to forward "http://www.thewebserver.com/telserver/foo" to "http://telserver.mycompany.local:8082/foo".
Listen 80 LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_connect_module modules/mod_proxy_connect.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule rewrite_module modules/mod_rewrite.so RewriteEngine on RewriteRule telserver/(.*) http://telserver.mycompany.local:8082/$1 [P] |
Here is the content of the configuration file "TSLib-config.js" to define the TelServer URL.
unigone_config = {
TELSERVICES_CONNECTOR: "xhr",
TELSERVICES_TELSERVER_URL: "/telserver"
};
|
3) Cross-domain configuration - "flash" connector
In this configuration TelServer and your web server are supposed to be located within two different domains. The "flash" connector uses the flash API of the browser flash plugin. To access the plugin TSLib must load a flash dependency file that is located within the TSLib librarie and then must be aware of its location.
NOTE: YUI Connection Manager v2.8.1 is required and the version of the browser flash plugin must be at least 9.0.124.
A cross-domain policy file ("crossdomain.xml") is deployed at TelServer.
The default file grants permissive access to TelServer
from requests originating from all sites. To allow access only from "www.thewebserver.com"
you can write:
<cross-domain-policy> <allow-access-from domain="www.thewebserver.com"/> </cross-domain-policy> |
In the following, let's assume "telserver.mycompany.local" the host name of the machine where TelServer is running.
Here is the content of the configuration file "TSLib-config.js" to define the TelServer URL. The path of TSLib directory must also be set.
unigone_config = {
TELSERVICES_CONNECTOR: "flash",
TELSERVICES_TELSERVER_URL: "http://telserver.mycompany.local:8082",
TELSERVICES_FOLDER: "/javascriptdir/TSLib"
};
|
Now you can add TelServices functionalities to your HTML elements or directly activate some TelServices services. See the "HTML control API" and "Context API" chapters.
This API enables you to build TelServices controls. A TelServices control is a TelServices functionality bound to an HTML element. TelServices functionalities can be set declaratively, using an attribute in HTML tags, or programmatically. Note that this API does not create nor delete HTML elements.
Three types of controls can be created :
This example demonstrates the declarative way to create some controls. The TelServices functionalities are set declaratively, using the "tel-control" attribute in HTML tags.
HTML part
<div id="containerId"> <input type="text" tel-control="dataId:login"/> <button tel-control="service:openSession,dataRef:login">open session</button> <button tel-control="service:closeSession">close session</button> <br/> <input type="text" tel-control="dataId:prim"/> <button tel-control="service:makeCall,dataRef:prim">make call</button> <button tel-control="service:answerCall">answer call</button> <button tel-control="service:dropCall">drop call</button> </div> |
Javascript part
<script>
var telController = unigone.TSLib.control.createControllerFromHTML("containerId");
</script>
|
This code instantiates a TelServices controller. This controller uses the HTML element which id is "containerId" as a starting point in the document to look for elements with the "tel-control" attribute and builds the TelServices controls.
Using TelServices controls
Display the page in your browser. The "close session" button is disabled and the "open session" button is enabled. The switching buttons are disabled.
Enter the login and press the "open session" button. If TelServer responds positively, the "close session" button is enabled and the "open session" button is disabled. The "make call" button is enabled.
The previous example could be written without adding the attribute "tel-control" in HTML tags. The controls are created programmatically from the HTML skeleton.
HTML part
<div> <input id="tel-login" type="text"/> <button id="tel-openSession">open session</button> <button id="tel-closeSession">close session</button> <br/> <input id="tel-number" type="text"/> <button id="tel-makeCall">make call</button> <button id="tel-answerCall">answer call</button> <button id="tel-dropCall">drop call</button> </div> |
Javascript part
<script>
var telController = unigone.TSLib.control.createController();
telController.addControl("tel-login", "dataId:login");
telController.addControl("tel-openSession", "service:openSession,dataRef:login");
telController.addControl("tel-closeSession", "service:closeSession");
telController.addControl("tel-number", "dataId:prim");
telController.addControl("tel-makeCall", "service:makeCall,dataRef:prim");
telController.addControl("tel-answerCall", "service:answerCall");
telController.addControl("tel-dropCall", "service:dropCall");
</script>
|
This code instanciates a TelServices controller with no controls. Controls
are added thanks to the "addControl" method. Its first parameter is
the id of the HTML element and the second one defines its properties. Properties
is a string matching the patterns "name:value" or "name1:value1,name2:value2".
HTML elements and controls can be both created programmatically. In this example a "make call" service control and its input data control are created from scratch.
<script>
var telController = unigone.TSLib.control.createController();
var loginElt=document.createElement("input");
loginElt.type="text";
document.body.appendChild(loginElt);
telController.addControl(loginElt, {dataId:"login"});
//telController.addControl(loginElt, "dataId:login");
var openSessionElt=document.createElement("input");
openSessionElt.type="button";
openSessionElt.value="open session";
document.body.appendChild(openSessionElt);
telController.addControl(openSessionElt, {service:"openSession",dataRef:"login"});
//telController.addControl(openSessionElt, "service:openSession,dataRef:login");
var closeSessionElt=document.createElement("input");
closeSessionElt.type="button";
closeSessionElt.value="close session";
document.body.appendChild(closeSessionElt);
telController.addControl(closeSessionElt, {service:"closeSession"});
//telController.addControl(closeSessionElt, "service:closeSession");
document.body.appendChild(document.createElement("br"));
var numberElt=document.createElement("input");
numberElt.type="text";
document.body.appendChild(numberElt);
telController.addControl(numberElt, {dataId:"prim"});
//telController.addControl(numberElt, "dataId:prim");
var makeCallElt=document.createElement("input");
makeCallElt.type="button";
makeCallElt.value="make call";
document.body.appendChild(makeCallElt);
telController.addControl(makeCallElt, {service:"makeCall",dataRef:"prim"});
//telController.addControl(makeCallElt, "service:makeCall,dataRef:prim");
var answerCallElt=document.createElement("input");
answerCallElt.type="button";
answerCallElt.value="answer call";
document.body.appendChild(answerCallElt);
telController.addControl(answerCallElt, {service:"answerCall"});
//telController.addControl(answerCallElt, "service:answerCall");
var dropCallElt=document.createElement("input");
dropCallElt.type="button";
dropCallElt.value="drop call";
document.body.appendChild(dropCallElt);
telController.addControl(dropCallElt, {service:"dropCall"});
//telController.addControl(dropCallElt, "service:dropCall");
</script>
|
This code instanciates a TelServices controller with no controls. Controls
are added thanks to the "addControl" method.
In this example the first parameter of the method is the HTML element itself
(but its id could also be used).
The second parameter is either a string or an object that defines the control.
Javascript frameworks such as the "Yahoo! User Interface Library" (YUI) or the "dojo toolkit" enable the creation of rich interface elements.
However when a button object is created with such frameworks TSLib is unable to handle the underlying HTML input element without further information. A button model must be specified that implements the methods TSLib needs to manage the framework button object.
By default the control module is supposed to work with raw HTML elements. A button is an HTML input element which type is button. Its HTML attribute "disabled" is used to enable or disable it.
The YUI button model is already defined in the library and identified with the string 'yui'. Before adding new controls the default button model must be set thanks to the "setDefaultButtonModel" function.
<html>
<head>
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.2/build/button/assets/skins/sam/button.css"/>
<script type="text/javascript" src="/javascriptdir/TSLib/unigoneYUI-2.5.2/unigoneYUI-TSLib.js"></script>
<script type="text/javascript" src="/javascriptdir/TSLib/TSLib-config.js"></script>
<script type="text/javascript" src="/javascriptdir/TSLib/TSLib.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/element/element-beta-min.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/button/button-min.js"></script>
</head>
<body>
<div class="yui-skin-sam">
<input id="tel-login" type="text"/>
<button id="tel-openSession">open session</button>
<button id="tel-closeSession">close session</button>
<br/>
<input id="tel-number" type="text"/>
<button id="tel-makeCall">make call</button>
<button id="tel-answerCall">answer call</button>
<button id="tel-dropCall">drop call</button>
</div>
<script>
openSessionButton = new YAHOO.widget.Button("tel-openSession");
closeSessionButton = new YAHOO.widget.Button("tel-closeSession");
makeCallButton = new YAHOO.widget.Button("tel-makeCall");
answerCallButton = new YAHOO.widget.Button("tel-answerCall");
dropCallButton = new YAHOO.widget.Button("tel-dropCall");
unigone.TSLib.control.setDefaultButtonModel('yui');
var telController = unigone.TSLib.control.createController();
telController.addControl("tel-login", "dataId:login");
telController.addControl(openSessionButton, "service:openSession,dataRef:login");
telController.addControl(closeSessionButton, "service:closeSession");
telController.addControl("tel-number", "dataId:prim");
telController.addControl(makeCallButton, "service:makeCall,dataRef:prim");
telController.addControl(answerCallButton, "service:answerCall");
telController.addControl(dropCallButton, "service:dropCall");
</script>
</body>
</html>
|
The dojo button model is not defined in the library but it is easy to add it.
First let's define the model (tested with dojo-release-1.1):
<script>
var dojoButtonModel = {
getElement: function(dojoButton) {
return dojoButton.domNode;
},
setEnable: function(dojoButton, enabled) {
dojoButton.setAttribute("disabled", !enabled);
}
}
</script>
|
Two methods must be implemented by the model. The "getElement" returns the HTML input element the dojo button wraps. The "setEnable" method defines the behavior of the button when it is enable or not. In this case we simply set the "disabled" attribute.
Before adding new controls the default button model must be set thanks to the "setDefaultButtonModel" function.
<html>
<head>
<link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/dojo/1.1/dijit/themes/tundra/tundra.css"/>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/dojo/1.1/dojo/dojo.xd.js"></script>
<script type="text/javascript" src="/javascriptdir/TSLib/unigoneYUI-2.5.2/unigoneYUI-TSLib.js"></script>
<script type="text/javascript" src="/javascriptdir/TSLib/TSLib-config.js"></script>
<script type="text/javascript" src="/javascriptdir/TSLib/TSLib.js"></script>
</head>
<body>
<div class="tundra">
<input id="tel-login" type="text"/>
<button id="tel-openSession" type="button">open session</button>
<button id="tel-closeSession">close session</button>
<br/>
<input id="tel-number" type="text"/>
<button id="tel-makeCall">make call</button>
<button id="tel-answerCall">answer call</button>
<button id="tel-dropCall">drop call</button>
</div>
<script type="text/javascript">
dojo.require("dijit.form.Button");
dojo.addOnLoad(function(){
openSessionButton = new dijit.form.Button({}, "tel-openSession");
closeSessionButton = new dijit.form.Button({}, "tel-closeSession");
makeCallButton = new dijit.form.Button({}, "tel-makeCall");
answerCallButton = new dijit.form.Button({}, "tel-answerCall");
dropCallButton = new dijit.form.Button({}, "tel-dropCall");
var dojoButtonModel = {
getElement: function(dojoButton) {
return dojoButton.domNode;
},
setEnable: function(dojoButton, enabled) {
dojoButton.setAttribute("disabled", !enabled);
}
}
unigone.TSLib.control.addButtonModel('dojo', dojoButtonModel);
unigone.TSLib.control.setDefaultButtonModel('dojo');
var telController = unigone.TSLib.control.createController();
telController.addControl("tel-login", "dataId:login");
telController.addControl(openSessionButton, "service:openSession,dataRef:login");
telController.addControl(closeSessionButton, "service:closeSession");
telController.addControl("tel-number", "dataId:prim");
telController.addControl(makeCallButton, "service:makeCall,dataRef:prim");
telController.addControl(answerCallButton, "service:answerCall");
telController.addControl(dropCallButton, "service:dropCall");
});
</script>
</body>
</html>
|
The TelServices controller can manage several calls at the same time. The set of all TelServices controls bound to a call is called a "call group". It is identified with a "call group handle".
HTML part
<div id="containerId"> <input type="text" tel-control="dataId:login"/> <button tel-control="service:openSession,dataRef:login">open session</button> <button tel-control="service:closeSession">close session</button> <div tel-control="callGroup"> <input type="text" tel-control="dataId:prim"/> <button tel-control="service:makeCall,dataRef:prim">makeCall</button> <button tel-control="service:answerCall">answerCall</button> <button tel-control="service:dropCall">dropCall</button> </div> <div tel-control="callGroup"> <input type="text" tel-control="dataId:prim"/> <button tel-control="service:makeCall,dataRef:prim">makeCall</button> <button tel-control="service:answerCall">answerCall</button> <button tel-control="service:dropCall">dropCall</button> </div> </div> |
Javascript part
<script>
var telController = unigone.TSLib.control.createControllerFromHTML("containerId");
</script>
|
This code instantiates a TelServices controller. It manages up to two calls. The "call group handle" of each call group is the HTML "div" element that bears the "tel-control" attribute (which value is "callGroup").
Create call groups programmatically
<script>
var containerElt = document.createElement("div");
document.body.appendChild(containerElt);
var telController = unigone.TSLib.control.createController();
function createCallGroup() {
var groupElt = document.createElement("div");
telController.addControl(groupElt, "callGroup");
var inputPrimElt = document.createElement("input");
inputPrimElt.type = "text";
groupElt.appendChild(inputPrimElt);
telController.addControl(inputPrimElt, "dataId:prim", groupElt);
var buttonMakeCallElt = document.createElement("input");
buttonMakeCallElt.type = "button";
buttonMakeCallElt.value = "makeCall";
groupElt.appendChild(buttonMakeCallElt);
telController.addControl(buttonMakeCallElt, {service: 'makeCall', dataRef:'prim'}, groupElt);
var buttonAnswerCallElt = document.createElement("input");
buttonAnswerCallElt.type = "button";
buttonAnswerCallElt.value = "answerCall";
groupElt.appendChild(buttonAnswerCallElt);
telController.addControl(buttonAnswerCallElt, {service: 'answerCall'}, groupElt);
var buttonDropCallElt = document.createElement("input");
buttonDropCallElt.type = "button";
buttonDropCallElt.value = "dropCall";
groupElt.appendChild(buttonDropCallElt);
telController.addControl(buttonDropCallElt, {service: 'dropCall'}, groupElt);
containerElt.appendChild(groupElt);
return groupElt;
};
var group1 = createCallGroup();
var group2 = createCallGroup();
</script>
|
This code instanciates a TelServices controller. It manages up to two calls.
In this example the "call group handle" is lazely set to the HTML
"div" element which contains the TelServices controls but it could
be any string or object that identifies the call group.
To build more sophisticated pages you must be aware of events in order to react when a call is incoming or is dropped for exemple. You can define javascript functions that are automatically called by the controller when TelServices events occur.
A controller handler is a callback object that implements some methods. In the following exemple we display a message when the TelServices session is open or closed and when a new call is received.
<script>
function sessionChange_callback(sessionInterface) {
var state = sessionInterface.state;
if (state == "open") {
alert("session is open");
}
else if (state == "closed") {
alert("session is closed");
}
}
function callGroupChange_callback(callGroupHandle, callInfoInterface) {
if (callInfoInterface.prim) {
if (callInfoInterface.prim.state == "alerting" && callInfoInterface.prim.cause != "droppedByOtherParty") {
var otherParty = callInfoInterface.prim.otherParty;
alert("New call is received : "+otherParty.number);
}
}
}
var my_handler = {
sessionChange: sessionChange_callback,
callGroupChange: callGroupChange_callback
}
var telController = new unigone.TSLib.control.Controller({handler: my_handler});
</script>
|
See the TSLib API documentation for more information about the other callback methods and about the "sessionInterface" and "callInfoInterface" interfaces. Note that you could also specified the scope in which the callback methods are executed.
The Context API gives you access to the TSLib component thats implements the TelServices protocol and is in charge of the connection with TelServer through the TelServer TelServices gateway.
You must first create an object called "context" used to connect with TelServer. A context object is used to monitor one phone device. Through this object you can send TelServices requests to TelServer and wait for responses. The context stores the data received from TelServer that you can retrieve later.
NOTE: if you need to bind HTML elements to TelServices functionalities you should not use the context module directly. You should use the HTML control module which manages the context in the background.
The prefered way to create a context is to call the "getContext" function because it can create a new one or retrieve an existing one.
<script> var context = unigone.TSLib.context.getContext(); </script> |
When called without parameter the function returns the default context identified by the "default" string. The following code is equivalent :
<script>
var context = unigone.TSLib.context.getContext("default");
</script>
|
You could also create another context :
<script>
var context = unigone.TSLib.context.getContext("identifier2");
</script>
|
Note that the context identifier is just a reference and must not be mixed
up with the phone number of the monitored device.
The general method to active a service is the "activateService" method. For example to open a session and associate the phone number "801" to this context you write :
<script>
context.activateService("openSession", "801");
</script>
|
To make a phone call from device "801" to device "802" you write :
<script>
context.activateService("makeCall", "802");
</script>
|
To close the session you write :
<script>
context.activateService("closeSession");
</script>
|
If the user of the monitored device is an agent you can change its state. To set the agent state to "logged on" you write:
<script>
context.activateService("agentState", "loggedOn");
</script>
|
If the user of the monitored device is an agent you can change its state. To set the agent state to "ready" you write:
<script>
context.activateService("agentState", "ready");
</script>
|
See the TSLib API documentation for more information about available services and agent states.
To answer a call you must first be aware that the call state is "alerting". You can define javascript functions that are automatically called by the context when TelServices events occur.
A context listener is a callback object that implements some methods. Some methods provide a basic monitoring and other ones provide more information about the session and the calls. The following script automatically answers a call.
<script>
var context = unigone.TSLib.context.getContext();
context.activateService("openSession", "801");
function incomingCall_callback(info) {
context.activateService("answerCall");
}
var my_listener = {
incomingCall: incomingCall_callback
}
context.addListener(my_listener);
</script>
|
See the TSLib API documentation for more information about the other callback methods and about the "info" interface. Note that you could also specified the scope in which the callback methods are executed.
See also the TSLib API documentation.
See also the TSLib API documentation.
If you encounter problems when installing TSLib library within your web application, here are some helpful hints: