We propose to integrate a new component (proxy) into the Asterisk platform. The main functionality of the proxy is to translate telecommunication calls into HTTP requests to external web services. Telecommunication services are located separately from the PBX, while the information they receive from Asterisk is presented as a HTTP-request. Technically, HTTP GET/POST request is a request, in which external telecommunications service passed information about the subscriber's name - CallerIdName, caller’s number - CallerIdNumber and and called number - Extension. Upon receiving necessary parameters, such as (calling/called number) a web service produces and forwards its instructions to the proxy. The latter receives and translates them into Asterisk instructions. The development of such services under the architecture described above is similar to a conventional CGI-script, for which there is a plenty of programming tools. As a result a programmer doesn’t need to be familiar with the Asterisk API.
Let’s consider in a more detailed way the model for the development of telecommunication services. Its global framework is shown below.
As seen the AGI-proxy component is at the heart of the model. The AGI-proxy is a Java-based application implemented on the basis of FastAGI, an open source library. The AGI-proxy is installed directly on the PBX Asterisk side.
In fact, the Asterisk represents the same thing for the AGI-proxy, as the J2EE container does for a Java-servlet. All calling massages produced by the Asterisk come to the proxy within the method service with two parameters: interfaces AgiRequest and AgiChannel. Through the first parameter one can get the information about the calls (caller name / number, called number, context of the call, feed settings, etc.) and through the second one the interaction with the Asterisk is carried out (call termination, transfer mode and etc.). Subscriber’s name (CallerIdName), caller’s number (CallerIdNumber) and called number (Extension) are wrapped within a string-parameter by the AGI-proxy. Then the AGI-proxy executes an HTTP request on its behalf to an external web service, whose URL is set in the configuration. The response from the invoked service is seen as an indication to what to do with the call. The call may be terminated or redirected to a specified number; a media file may be played. The instructions returned by an external service must be presented in an xml-format. It has a very simple scheme:
An example of the typical response of a web service is shown below:
On receiving this xml-response, the proxy will play the media file "demo-nogo" (playMadiaFile).
Under this architecture the sequence of calls is reduced to a very simple diagram.
To demonstrate the functionality the proxy we need two files agiproxy.jar, AgiProxyScript.java and two configuration files - agiproxy.conf, fastagi-mapping.properties. The files should be copied to the directory /var/lib/asterisk/agi-bin/. Let’s make the following steps to configure the proxy:
1. Set the extensions (calls), to which the proxy will “react”. In the file /etc/asterisk/extensions.conf one may write, for example, the following instruction:
exten => _1XXX,1,Agi(agi://localhost/proxy.agi)
(To run the proxy when a four-digit number beginning with "1" is dialing up)
2. Set the URL of an external service (see below), with which the proxy will interact. For example:
(to perform an HTTP-request to the agi.jsp at the localhost)
3. Set parameters for the interaction of the proxy with the Asterisk:
hostname=localhost (Asterisk server name)
username=manager (user name indicated in manager.conf)
password=pa55w0rd (password from manager.conf)
4. Compile AgiProxyScript.java for your operating system as follows: to run the instruction written below from /var/lib/asterisk/agi-bin/-directory (for Java version 1.6):
javac -cp .:asterisk-java-0.3.1.jar:agiproxy.jar AgiProxyScript.java
5. Run the Asterisk, using, for example, the following instruction:
6. Launch the AgiServer by invoking the instruction below from /var/lib/asterisk/agi-bin/ -directory:
java -cp agiproxy.jar:asterisk-java-0.3.1.jar:. org.asteriskjava.fastagi.DefaultAgiServer
As the example of external services a trivial java server page (agi.jsp) has been written. It parses the string of parameters received from the AGI-proxy and determines a called number (Extension). Then it creates instructions for Asterisk depending of the called number: for the number “1200” a media file will be played, a call having the number “1300” will be redirected to the number “500”, any other numbers will be terminated.
In conclusion, let me remind you the advantages of using this model to develop telecommunication services as opposed to the traditional "programming" dialplan in configuration files:
1. The entry barrier for programmers of new telecommunication services becomes lower.
2. The possibility to develop services using various technologies, such as CGI, JSP, ASP.NET.
3. The possibility of integration of new external services without any changes on the PBX side.
This article does not claim to carry revolutionary ideas, neither the examples have a rich functionality. This is only an attempt to create some basis for the open source project aimed to develop further programming technology and tools for the Asterisk.
Source code and files necessary to install the demonstration examples are available here.
Article in Russia language.