The TelServices widget (TSWidget) is a javascript widget that provides telephony capabilities to web pages through a graphical user interface. TSWidget connects with TelServer TelServices gateway and provides the user the ability to control his desktop phone. The user can make calls and answer calls. It does not require any installation on the user's computer.
The widget API allows the web page and the widget to interact. Thanks to javascript callback functions the web application can be aware of call events (for exemple when a call is received the other party number can be provided to the web application to display information relative to the call). The web application can make calls or answer calls on behalf of the user. When the widget user is an agent the web application can change its state.
Quick link : see also the full TSWidget API documentation.
TSWidget has been tested with Firefox 3, Microsoft Internet Explorer 6, 7 and 8, Safari, Google Chrome.
TSWidget is built on uniGone TelServices library (TSLib) and uses some components of the Yahoo! UI 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 TSWidget compatible with YUI v0.12.2 if needed.
To process cross-domain requests with flash the YUI Connection Manager v2.8.1 is required.
Prerequisite : TelServer TelServices gateway must be enabled. See TelServices gateway configuration chapter.
To have a first glance on the widget you can connect to TelServer TelServices gateway with your browser. You can also customize the pages delivered by your web server.
The default page delivered by the TelServer TelServices gateway includes the TelServices widget.
Let's assume:
Enter the following URL in your browser: "http://telserver.mycompany.local:8082".
Now open the menu "Options" and select the "Login" sub-menu. Enter your phone number and press the "Open" button.
Quick link : see also the TSWidget GUI Guide.
To use the widget in your pages you have to include some javascript files and set some properties.
Let's call "mypage.html" the HTML page to customize.
You have to install TSWidget 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.
TSWidget packages are located in the "util\TelServices-javascript" 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/TSWidget".
NOTE: TSLib javascript files are included in TSWidget packages.
Include TSWidget only
<head> <!-- include YUI components here --> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget.css" /> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget-skin.css" /> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget.js"></script> </head> |
Include TSWidget+YUI
<head> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget.css" /> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget-skin.css" /> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget.js"></script> </head> |
Include TSWidget+YUI v0.12 adaptor
<head> <!-- include YUI v0.12 components here --> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget.css" /> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget-skin.css" /> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget.js"></script> </head> |
The default confguration of the TSWidget library may have to be overriden to fit with your own configuration. User settings are properties of the object "unigone_config". Some mandatory settings are relative to TSLib (TelServer URL, connectors, cross-domain/proxy configurations). Please refer first to the configuration chapter of TSLib.
The javascript file "TSWidget-config.js", included in TSWidget directory, defines a skeleton of "unigone_config". This file must be included before including the TSWidget library.
The mandatory setting for TSWidget is the TSWidget directory location. It defines the path to HTML help files and to the detached widget HTML page.
Here is the content of the configuration file "TSWidget-config.js" for a cross-domain configuration using the "xhr" connector.
try {
document.domain = "mycompany.local";
}
catch (ex) {
alert("TSWidget-config - cannot change 'document.domain'");
}
unigone_config = {
TELSERVICES_CONNECTOR: "xhr",
TELSERVICES_TELSERVER_URL: "http://telserver.mycompany.local:8082",
TELSERVICES_FOLDER: "/javascriptdir/TSWidget"
};
|
Here is the content of the configuration file "TSWidget-config.js" for a cross-domain configuration using the "flash" connector.
unigone_config = {
TELSERVICES_CONNECTOR: "flash",
TELSERVICES_TELSERVER_URL: "http://telserver.mycompany.local:8082",
TELSERVICES_FOLDER: "/javascriptdir/TSWidget"
};
|
To set other TSWidget optional settings please refer to TSWidget API documentation.
The file "TSWidget.html" is used when the widget is detached from "mypage.html" page and run in its own window. Open this file and update the paths to YUI components. Note that it includes "TSWidget-config.js" file that defines the configuration object "unigone_config".
In this exemple, the TelServices widget is started when page is loaded and stopped when the page is unloaded. These actions can be done at your convenience however.
<body onload="unigone.TSWidget.start();"> |
In this example we assume :
<html> <head> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget.css" /> <link rel="stylesheet" type="text/css" href="/javascriptdir/TSWidget/css/TSWidget-skin.css" /> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget-config.js"></script> <script type="text/javascript" src="/javascriptdir/TSWidget/TSWidget.js"></script> </head> <body onload="unigone.TSWidget.start();"> <p>Welcome</p> </body> </html> |
The content of the configuration file "TSWidget-config.js" is the one described at "step 3".
TSWidget provides a javascript API that enables the widget and the web page to interact. The widget can be hidden and shown. The page (the web application indeed) can make a call or answer a call or display in the dedicated panel of the widget some information relative to a phone number (a customer card for exemple). When the widget user is an agent the web application can change its state.
NOTE: user javascript functions should be added to the configuration file "TSWidget-config.js" mentioned above in order to be automatically embedded when the widget is detached.
See the TSWidget API documentation to have a complete information about the widget API. Note that you could also specified the scope in which callback methods are executed.
Example 1
In the following example we want simply display a message in the page when a call is received and when the call is cleared. For these purposes we define two callback functions.
<html>
<head>
<!-- include TSWidget files and configuration settings here -->
<script>
function init() {
var my_handler = {
incomingCall: incomingCall_callback,
clearedCall: clearedCall_callback
}
unigone.TSWidget.start({phoneNumber: '811', handler: my_handler});
}
function incomingCall_callback(info) {
alert("Incoming call, other party phone number is : "+info.otherPartyNumber);
}
function clearedCall_callback(info) {
alert("Call is cleared, other party phone number is : "+info.otherPartyNumber+", call duration is :"+info.duration);
}
</script>
</head>
<body onload="init();">
</body>
</html>
|
Example 2
In the following example we want an incoming call to be answered immediately. For this purpose the "incoming call" callback function calls the "answer call" function of the TSWidget API.
<html>
<head>
<!-- include TSWidget files and configuration settings here -->
<script>
function init() {
var my_handler = {
incomingCall: incomingCall_callback
}
unigone.TSWidget.start({phoneNumber: '811', handler: my_handler});
}
function incomingCall_callback(info) {
unigone.TSWidget.answerCall(info.otherPartyNumber);
}
</script>
</head>
<body onload="init();">
</body>
</html>
|
The "incoming call" callback may also the opportunity to the application to make a "self.focus()" in order to make the window get on top of the others if any.
Example 3
In the following exemple we want the widget to display an information relative to the other party phone number (for exemple a customer information). We define the "refresh information" callback function that is automatically called when the other party phone number changes (incoming call, transfer call). In this callback we call the useful TSWidget API function "setInformation". This function requests the web server the information to display, waits for the response and displays the information in the dedicated panel of TSWidget.
<html>
<head>
<!-- include TSWidget files and configuration settings here -->
<script>
function init() {
var my_handler = {
refreshInformation: refreshInformation_callback
}
unigone.TSWidget.start({phoneNumber: '811', handler: my_handler});
}
function refreshInformation_callback(info) {
unigone.TSWidget.setInformation(null, "calling.php?callingNumber="+info.otherPartyNumber, null, info.otherPartyNumber);
}
</script>
</head>
<body onload="init();">
</body>
</html>
|
The php script returns an HTML link to the customer card.
<?php (isset( $_POST["callingNumber"] ) ? $callingNumber = $_POST["callingNumber"] : $callingNumber = $_GET["callingNumber"]); echo "<a href='#' onclick='unigone.TSWidget.loadPage(\"http://webserver.mycompany.local/customer-card.html\");'>customer card</a>"; ?> |
When the user clicks on the link the customer card is displayed by default in the window in which the widget is embedded. Note that the "loadPage" function supports another parameter to point out a target frame if needed.
Example 4
In the following exemple we create a button to make a call to a device which phone number is '812'.
<html>
<head>
<!-- include TSWidget files and configuration settings here -->
<script>
function init() {
unigone.TSWidget.start({phoneNumber: '811'});
}
</script>
</head>
<body onload="init();">
<button onClick="unigone.TSWidget.makeCall('812');">call 812</button>
</body>
</html>
|
Example 5
When the widget user is an agent its state can be changed. The following function makes an agent logged on.
<script> unigone.TSWidget.setAgentLoggedOn(); </script> |
In the same way the agent state can be set to logged off.
<script> unigone.TSWidget.setAgentLoggedOff(); </script> |
Other functions are available to handle the "ready", "not ready" and "working after call" states.
See also the TSWidget API documentation.
See also the TSWidget API documentation.
See also the TSWidget API documentation.
If you encounter problems when installing the TSWidget library within your web application, here are some helpful hints :