Skip to main content
Natterbox

HTTP Query

  • Available in Call Policies
  • Available in Non-Call Policies

Within this component is the capability to HTTP query a CRM for data and place the query results in a result set for use later on in the call.

PortalPolicyFCDataHTTPQuery1.png

HTTP Query Details

When creating a new HTTP query or editing an existing one, the following pop-up box (opened by double-clicking the component) contains the details that are available to apply to the HTTP query.

PortalPolicyFCDataHTTPQuery2.png

Property Example Description
Secure HTTP On Enabling this establishes an encrypted session with the destination web server
HTTP Host Name http://hostname.com Here is where the hostname (URL) for the destination web server is specified - please note that the URL must be entered without the http(s):// prefix.
Authentication User Name Username If the server requires credentials to access it then enter the username here
Authentication Password ******** If the server requires credentials to access it then enter the password here
Maximum wait time 10 How long to wait in seconds for a response from the web server
HTTP Parameters Telno = $(E164CallerNumber) Here, the parameters of the query are defined. In the example given the URL would lead to a database, it would look through the field Telno and if the pre-defined macro matches one of those entries, then the policy can act accordingly.
Result set name Current The component generates a default macro name that can be edited, for example $(SForce_Current), with which to access this data set across the policy

Working Examples

To use the HTTP Connector, you will need to be able to write Web based applications using any language of your choice, and secondly be able to host the Web application on your infrastructure. More details on configuring the HTTP Data Connector can be found here. The remainder of this page, is aimed at detailing how you should write your applications to work with the connector.

There are many examples of how the HTTP Connector can be used to facilitate call flow or provide the ability to create interactive applications using your own data sources. Some of these include:

  • Database query: Query your mySQL database to lookup a caller id and then route the call based how important they are to you, or maybe block a caller based on a custom black list.

  • Reporting: Report statistics back to your local application on call flow

  • Message of the Day: Read a message of the day to certain callers based on who they are trying to call

  • Read RSS Feed: Read an RSS Feed back to a caller

Considerations

When you decide to use the HTTP Connector to query a data source, you should be mindful of a number of considerations:

  • Timely responses: When the HTTP Connector makes a call to your data source, the call routing is temporarily paused, therefore you must ensure that your responses to any queries from the HTTP Connector are as fast as possible, providing the minimal amount of data required for the task in hand.
  • Redundancy: If using the HTTP Connector, your call flow may become highly reliant on being able to access your application. Although you can configure the policy to route around the inability to access your web application, your call flow will be affected. Make sure that your application is hosted on redundant hardware to minimise this risk.
  • Licensing & Privacy: If you are using the HTTP Connector to query other data sources, make sure you are abiding by any license restrictions on use of the data. If accessing data that is covered by other regulatory requirements, ensure that you understand and have permission to use that data.

The Basics of Integration

When a call flow activates an HTTP Connector, an HTTP request is made to the configured URL that hosts a Web application you have written. The HTTP request will pass any parameters that you have specified; this includes the ability to expand any CallMacros so that you can pass dynamic information associated with the call, e.g. Caller Number. The HTTP request can pass the data as either a GET or a POST. If using a POST, the data is mapped into an XML chunk and submitted as the payload.

Your Web application can then perform any business logic required, and on completion will return a well structured XML document that contains any matching records. Finally you can use the results in the onward call flow by accessing the returned values as macros.

Request Format

The Non Call Version of the HTTP Connector will allow you to use the GET & POST format, where as the Call Version currently only supports GET.

GET Format

If you choose to use a GET method for submission of your data, then the HTTP Connector will take the parameters you provide and map them into a well formed URL request. For example, if you chose to send the properties Name=Joe Smith, Number=1234567, Location=London, then the URL string that will be presented to your application will url encoded and look as follows:

http://myapp.com?Name%3DJoe%20Smith%26Number%3D1234567%26Location%3DLondon

POST Format

If you choose to use a POST method for submission of your data, then the HTTP Connector will take the parameters you provide and map them into an XML payload. For example, if you chose to send the properties Name=Joe Smith, Number=1234567, Location=London, then the payload that will be presented to your application will look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<records>
  <record>
    <Name>Joe Smith</Name> 
    <Number>1234567</Number> 
    <Location>London</Location> 
  </record> 
  </records>

Request Response

Your application must respond back with an XML structure which is a list of records that match the corresponding query. The XML must be structured as follows: a records element that contains zero, one or more record elements. Within each record element you may place any number of elements of your own naming scheme that you wish. You should however try to ensure that each record element follows the same format. The minimum response, which will indicate that there were no matching records, is:

<?xml version="1.0" encoding="UTF-8"?>
<records/>

To return some data from your data source, you need to include the record elements. For example, if you had queried your data source and wished to return records containing a name, telephone number and location, you might respond with something like:

<?xml version="1.0" encoding="UTF-8"?>
<records>
  <record>
    <Name>Joe Smith</Name> 
    <Number>+441582123456</Number> 
    <Location>London Office</Location> 
  </record> 
  <record> 
    <Name>Harry Jones</Name>
    <Number>+447740111111</Number>
    <Location>Mobile</Location>
  </record> 
</records>

Accessing the Returned Records

When a set of one or more records is returned, you can access the values using the complex macro language. Each set of returned records is placed into a results set. The language is fully described here. Some reference examples are provided below.

  • To access the Name field in the first record, use $(HTTP_Current.Name[1]) - in our example this would be Joe Smith

  • To access all the numbers, use $(HTTP_Current.Number) - this will return the numbers as a comma separated list (in our example this would be +441582123456,+447740111111), which in this form can be used in a Number Component to ring multiple numbers.

  • You can access the count of all records returned using $(HTTP_Current.@Count) – in our example this would return 2

Putting it all Together

Now we have described the component parts, let’s put it all together in a simple policy. Here we are going to look up the Caller Number in a customer’s database to determine which extension is best suited to take the call. We will write a simple application in PHP that access a mySQL database. The HTTP Connector will access this application and then route the call as appropriate based on the XML response.

Configure the Policy

Firstly we need to set up a policy. The example policy below shows that inbound numbers from the outside world will be routed to this policy if the number 0845123456 is dialled. This policy then routes the call to the HTTP Query. If a match is found, then the Dial Extension component is used, otherwise if no match is found then the Dial Reception component is used.

PortalPolicyFCDataHTTPQuery3.png

Configure the HTTP Connector

If we open up the HTTP Query Component, it is configured as follows. The HTTP Host Name is set to the host name and extended path name of the hosted script. We have defined one query parameter that will be passed to the script called callernumber. We are setting the value of this parameter with a simple macro called $(CallerNumber), which will be expanded prior to making the call to your application.

The settings page below will actually end up constructing a URL that looks like the following, when it talks to the application:

http://demo.neilb.redmatter.com/queryDB.php?callernumber=1234

This URL can be entered into any any browser, and the results can be checked directly.

PortalPolicyFCDataHTTPQuery4.png

When entering a URL, http:// or https:// does not need to be included

Configure the Number Component to use the Result

If the HTTP Query successfully finds a record result then it needs to be actioned. Below is the Dial Extension settings page which shows the macro $(HTTP_Current.Extension) being used to dial the number. If we were returning more than one record we would need to be explicit about which record to use, so may wish to use the $(HTTP_Current.Extension[1]) style notation to select the Extension field from record 1.

PortalPolicyFCDataHTTPQuery5.png

Write and Deploy the Script

So with the above configured policy, all that needs to be provided is the script that accepts the request from the HTTP Connector and returns a result. Below is an example provided in PHP that operates under an Apache Server. It accepts the Web request, extracts the parameter callernumber from the GET string and then uses it as a variable to query a database. If it finds a match, the returned XML will look something like:

<records>
  <record>
    <Extension>5678</Extension>
  </record>
</records>

Following is the code segment which you would need to deploy on your Web Server.

<?php
$callerNumber = $_GET['callernumber'];

$query = "SELECT `Extension` FROM `CallerMap` WHERE `CallerNumber`='$callerNumber' LIMIT 1;";

$dbCon = odbc_connect("MyDatabase", "DBUser", "DBPass");

header("HTTP/1.1 200 OK");
header("content-type: application/xml; charset=UTF-8");
echo "<records>\n";

if ($dbCon) {

  $dbRes = odbc_exec($dbCon, $query);
  if ($dbRes) {

    while (odbc_fetch_row($dbRes)) {
      echo "<record>\n";
      echo "  <Extension>" . odbc_result($dbRes, "Extension") . "</Extension>\n";
      echo "</record>\n";
    }
  }
  odbc_close($dbCon);
}

echo "</records>\n";

?>
  • Was this article helpful?