Linking an HTTP Server to an IVR Node

Today most application server expose some kind of http-based API. The PBX can take advantage of that by sending HTTP requests to the server and make routing decisions based on the response from the server.

Settings

The PBX uses "Action URL" tab settings when the list of actions contains the word "action:url". In that case the settings in the tab have the following meaning:

Username and password: Like with all HTTP requests, the system can identify itself with a username and a password. The PBX uses Basic authentication.

Method: The PBX supports the usual methods: GET, POST, PUT and DELETE

Connection/read timeout: These settings defines how long the system will wait until the request connects to the server and how long it will wait for more data once that the connection has been established.

URL: This settings tells the PBX where to send the request. The URL may include parameters (see below).

Additional headers: Sometimes the application server needs additional headers, which can be put into the settings for additional headers.

Encoding: The PBX supports the most popular formats for encoding the message body: JSON (mostly used in REST API), XML, URL (url-encoded data) and ASCII (no specific encoding).

Message body: The information that should be sent to the application server is usually contained in the body. Exceptions are GET requests that usually carry additional information in the URL. Like the URL, the body may contain additional parameters, see below. Apart from that, you should put the static information in the request into the message body, for example to generate a XML request:

<?xml version="1.0"?>
<my-data>
  <type>something</type>
  <caller-id>{from}</caller-id>
</my-data>

Destination RegEx: When the PBX received from the server, it needs to determine where to send the call to. This is usually another IVR node or a ACD queue. Because there are so many different ways of returning the destination, the PBX uses a simple way to fish for the destination in the response rest: It uses a regular expression that must match the number and surrounding characters. The format is similar to the regular extensions in the dial plan. It starts with a seperation character, then the regular expression, the seperator again, and then the replacement text. Matches in the regular expressions can be refererenced with the \\x syntax, list like in the dial plan matching.

Variables

The URL and the message body may contain dynamic content that are represented in the form {variable}. The following variables are available:

VariableContent
{cnam}The display name of the caller (usually the CNAM).
{from}The number of the caller.
{to}The called number.
{account}The name of the called IVR node.
{input}The user DTMF input.

Example

The following example sends all input that was received an external server. The response of the server determines what number to call next.

The DTMF match list just matches all input and returnes the matched string in the input to the action URL. There it can be referenced with the {input} macro. Other input like the {from} and {to} are also being used there.

Then when a user calls the account and presses 5 the log message looks like this:

[6] 16:53:07.186 APP: IVR Node: Received DTMF 5
[5] 16:53:07.187 WEBC: Action URL request http://google.com
{"from":"6173998147","to":"42","input":5}
[9] 16:53:13.305 WEBC: http:google.com:80: Send request
POST / HTTP/1.1
Host: google.com
Content-Length: 36
X-Vodia: Test
Authorization: Basic dXNlcjo=
Content-Type: application/json
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; PBX)

{"from":"6173998147","to":"42","input":5}

The web server then can return a pattern that tells the PBX where to redirect the call. In our example, google.com would not return anything useful.