17.6. Integrating Asterisk with Other Software
While the extensions.conf file and the CLI are great places to command and control your Asterisk PBX, certain administrative applications may demand more capabilities than these tools offerlike integration with other applications or with a web server. For instance, if you were running a paid-use service using Asterisk to provide the dial-tone and call routing, then you might need a way to automatically set up and tear down extensions and voice mailboxes; this might even mean integrating with a billing application or self-service web application.
17.6.1. Asterisk CLI Wrapper
At such times, it's good to know that Asterisk's CLI functions are available to the outside world via two mechanisms: the Asterisk application in client mode, and the Asterisk Manager API. Running Asterisk in client mode lets you pass any Asterisk CLI command to the Asterisk executable in a shell as an argument. To pass an Asterisk command, run it with the x option. Have a look:
asterisk -r -x add extension 120,1,Dial,SIPemail@example.com:5060 into local
Using the shell command functions of scripting languages such as Perl and PHP, it is possible to integrate almost every CLI command into a custom-made application. For example, you could build a web-based administration tool for Asterisk (some have attempted this, but using the Manager API), or you could use a Perl script to automatically remove extensions when customers' bills are overdue in an external billing system.
Consider the following line of Perl:
system("asterisk -r -x add extension $newExt,$newPri,$appl,$args into $context");
This Perl command launches Asterisk in client mode and runs the add extension CLI command with an entirely dynamic extension definitionone that another part of the Perl script establishes according to the programmer's design.
17.6.2. The Asterisk Gateway Interface
One of the most compelling ingredients in the Asterisk recipe, AGI gives developers the ability to create custom interfaces between the dial-plan and outside systems. The AGI is to Asterisk what CGI is to a web server. In a nutshell , it allows you to use your favorite programming languagePerl, Python, Pascal, RealBASIC, whateverto affect or control interaction with a telephone user who's attached to the PBX. Here a few examples of things you can do with the AGI:
Though AGI bears some similarity to CGI, the output from an AGI program is completely different from that of a CGI program. Generally, a web CGI produces HTML or XML output, but AGI programs produce output in the form of AGI commands. These commands are sent to the Asterisk server for processing, and then Asterisk sends data back to the AGI program in response. A list of the commands can be found in Appendix C. A Perl library for writing AGI programs is available from http://asterisk.gnuinter.net/.
17.6.3. Asterisk Manager Socket API
Like the AGI, the Asterisk Manager socket API provides a way for external software to communicate with Asterisk. Unlike AGI, the purpose of the Manager API isn't building telephony applications. Instead, the Manager API is used for controlling administrative and process control functions of Asterisk from external software. Here are some things you could do with the API:
All API sessions, which are TCP connections to the Asterisk server on port 5038, are text-based exchanges. They must begin with a login exchange to authenticate the connecting party. The security permissions for each Manager API user are stored in /etc/asterisk/manager.conf , as discussed in "Monitoring Asterisk" in Chapter 3.
Sending a TCP packet with the following payload would log a user named Jake into the Asterisk server. Follow each line with a single Retrun and the entire section with two Returns:
Action: login Username: Jake Secret: monsterjam
You can telnet to port 5038 on your Asterisk server in order to try this. Just make sure your manager.conf is set up to allow somebody to log in.
Once you're authenticated, you can issue other text-based commands to the Manager API and parse the output as needed. Appendix D describes the Manager API syntax.