WAS v8.5 > End-to-end paths > Communications enabled applications

Access telephony services with REST APIs

We can integrate web telephony into new and existing applications using a REST API. Telephony features include making phone calls, receiving phone calls, and receiving call notifications within the web application.

The communications enabled applications (CEA) capability requires an IP private branch exchange (PBX) as part of your infrastructure. An IP PBX is a business telephone system designed to deliver voice over a data network and interoperate with the Public Switched Telephone Network (PSTN). A sample IP PBX application is included in the Samples section of the information center. The sample IP PBX is in the form of an application EAR file and is for test purposes only. It can be used to test out the REST interface in the absence of an actual IP PBX that would be used in production. Installation of the sample IP PBX application only requires installing the sample EAR on a dedicated application server. The details of installing and configuring the vendor-specific IP PBX are not provided. Along with the sample IP PBX, two soft phones are needed to test the application.

An understanding of the REST interface requests and responses is needed to perform this task. See the information on REST APIs in CEA for a complete reference to the REST API.

This task uses JavaScript within an application, which calls the REST interface to manage phone calls over an IP network. Formerly, this capability required building SIP servlets and a detailed understanding of the SIP specification.

For another way to accomplish this task using time-saving widgets, see the information center topics on making phone calls and call notifications in web applications.

This task lists the steps needed to develop and deploy an application that can manage phone calls, including how to configure the application server.

  1. Enable the system application.
  2. Install and configure the IP PBX.
  3. Configure the IP PBX location.
  4. Restart the application server.
  5. Develop a new application that calls the REST interface.
  6. Install and start the new application.
  7. Test the new application.


Procedure


  1. Enable the system application.

    The system application owns the REST interface. Update the configuration for each server running CEA.

    1. Access the CEA settings panel in the dmgr console.

      • In a single-server environment, click Servers > Server Types > WebSphere application servers > server_name > CEA.

      • In a clustered environment, click Servers > Clusters > WebSphere application server clusters > server_cluster > CEA.

        Because servers in a cluster are clones of each other, you only need to make configuration changes from the main cluster panel for the cluster, not for each individual server in the cluster.

    2. Ensure the check box labeled Enable communications service is checked.


  2. Install and configure the IP PBX.

    Restriction: The IP PBX must support the ECMA TR/87 protocol. Complete the following actions to set up a sample PBX application that we can use for unit testing in the absence of an official PBX.

    1. Start the application server. Start the application server where you deploy the sample PBX application.
    2. Install the SIP IP PBX sample application. This sample application is located in the installableApps directory of the CEA samples package.

      Notes:

      We can use the Fast Path option when installing the application using the dmgr console, and no changes to the default (Fast Path) settings are required.

      In an initial demonstration or test environment, it is acceptable to install the sample IP PBX application to the instance of WebSphere Application Server that hosts one or more communications enabled applications. When this approach is taken, the default CEA settings can be used in cases where the application server is configured to utilize the default SIP_DEFAULTHOST port (5060); it is unnecessary to make any changes to the CEA settings using the dmgr console or wsadmin.

    3. Start the application.


  3. Configure the IP PBX location.

    The following information must be configured on the server where the CEA system application is running.

    1. In the dmgr console, click Servers > Server Types > WebSphere application servers > server_name > CEA.

    2. Use the CEA settings page to select the Use SIP CTI (ECMA TR/87) gateway for telephony access option and configure the following fields:

      Set the following fields based on the server that is running the PBX application.

      • Host name or IP address
      • Port - For the TCP Protocol, select the port SIP_DEFAULTHOST for the server that is running the PBX application.
      • Protocol (TCP)
      • Superuser name

      We can specify a Superuser name on the CEA settings panel. The superuser corresponds to a user, who is configured on the PBX, and has the ability to control any phone that is configured on the PBX. Also, the superuser has the ability to control multiple phones concurrently. This functionality, however, is not supported on every PBX. The Cisco PBX requires set a user name for each phone to control. The Superuser name field on the CEA settings panel can only pass a single user name; therefore, it can only control a single device. To control multiple phones concurrently using the Cisco PBX, you must derive the user name from the user credentials for this PBX. To accomplish this task, ensure the Extract user name from request check box is selected on the CEA settings panel.


  4. Restart the application server.


  5. Develop a new application that calls the REST interface.

    We can copy the following example code into an HTML file and preview it as part of a sample application. The code renders as a simple form where the user can enter two SIP URIs that represent two phones. When the Send XML button is pressed, the request is sent in XML format to the REST interface and a call is established. If the Send JSON button is pressed, the only difference is the format of the request is JSON. The response is of the associated format and printed to a popup window. This example shows only one of the available REST interfaces. 

    <!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Call Tester</title> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 
<script type="text/javascript" language="javascript"> 
function setupXmlHttpRequest() {
 if( typeof XMLHttpRequest == "undefined" ) XMLHttpRequest = function() {
  try { return new ActiveXObject("Msxml2.XMLHTTP.6.0") } catch(e) {}
  try { return new ActiveXObject("Msxml2.XMLHTTP.3.0") } catch(e) {}
  try { return new ActiveXObject("Msxml2.XMLHTTP") } catch(e) {}
  try { return new ActiveXObject("Microsoft.XMLHTTP") } catch(e) {}
  throw new Error("This browser does not support XMLHttpRequest.")
        };}

function createXML(addressOfRecord, peerAddressOfRecord) {
 var xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
 xml += "<CommRestRequest xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ";
 xml += "xsi:noNamespaceSchemaLocation=\"CommServletSchema.xsd\">";
 xml += "<enableCollaboration>false</enableCollaboration>";
 if (addressOfRecord.length > 0) {
  xml += "<addressOfRecord>" + addressOfRecord + "</addressOfRecord>";
 }
 if (peerAddressOfRecord.length > 0) {
  xml += "<peerAddressOfRecord>" + peerAddressOfRecord + "</peerAddressOfRecord>";
 }
 xml += "</CommRestRequest>";
 return xml;}

function createJSON(addressOfRecord, peerAddressOfRecord) {
 var json = "{";
 json += "enableCollaboration:false";
 if (addressOfRecord.length > 0) {
  json += ",addressOfRecord:" + addressOfRecord;
 }
 if (peerAddressOfRecord.length > 0) {
  json += ",peerAddressOfRecord:" + peerAddressOfRecord;
 }
 json += "}";
 return json;}

function sendRequest(method, uri, caller, callee, json) {
 try {
  setupXmlHttpRequest();
  var request = new XMLHttpRequest();
  if (json == 1) {
   // Determine if there are parameters in the uri yet
   var paramChar = "&";
   if (-1 == uri.indexOf('?')) {
    // No parameters.
    paramChar = "?";
   }
   request.open(method, uri+paramChar+"JSON=true", false);
   request.send(createJSON(caller, callee));
  } else {
   request.open(method, uri, false);
   request.send(createXML(caller, callee));
  }
  alert(request.responseText);
 } catch (err) {
  alert(err.description);
 }}

</script> </head> 
<body> <form name="myform">  <h2>Make Calls</h2>  <p><hr>  Caller Uri: <input type="text" name="caller_uri" value=""></input>  Callee Uri: <input type="text" name="callee_uri" value=""></input>  <input type="submit" 
        onclick="sendRequest("PUT", "CommServlet/call", 
 document.myform.caller_uri.value,document.myform.callee_uri.value,0)" 
        value="Send XML">  <input type="submit" 
        onclick="sendRequest("PUT", "CommServlet/call", 
 document.myform.caller_uri.value,document.myform.callee_uri.value,1)" 
        value="Send JSON"> </form> </body> </html>


  6. Install and start the new application.


  7. Test the new application.

    The following details are specific to an application that would trigger a phone call between two phones.

    1. Send a REST request, providing the source and destination SIP URIs in the body of the message.
    2. Answer the source phone when it rings.
    3. Answer the destination phone when it rings.


Results

An application has been developed and deployed leveraging the REST interface to make and receive phone calls and call notifications.

If problems are encountered, use the following check list for troubleshooting the problem:


+

Search Tips   |   Advanced Search