The Aynchronous Javascript Asterisk Manager (AJAM)

The Aynchronous Javascript Asterisk Manager (AJAM)
	Chapter 6. External control of Asterisk

As of version 1.4, Asterisk comes packaged with a small web server called AJAM, which may be used to access the Asterisk Manager Interface (AMI) via HTTP. The name "AJAM" is derived from "AJAX"^[41] (Asynchronous JavaScript and XML).

Set-up assumes the steps from the section called “The Asterisk Manager Interface (AMI)” have been carried out, plus some additional parameters. You must set webenabled to yes in the [general] section of manager.conf. Pay attention to httptimeout, which defines the inactivity timeout after which the user is automatically logged out of the web interface. To activate the web server, set these parameters in http.conf:

[general]
enabled=yes
enablestatic=yes
bindaddr=127.0.0.1
bindport=8088
prefix=asterisk

enablestatic need only be activated if the AJAM will be serving static files from /var/lib/asterisk/static-http/. Normally you would set this to no, but it is needed for the purposes of the Asterisk-AJAM demo (the section called “AJAM Demo”).

Don't forget to restart!


Our assessment is that it almost never makes sense to serve other web applications (that is, those intended strictly for administrator access) through the AJAM interface. It is also doubtful that it was intended to, because the rights assignments through `read` and `write` (see the section called “The Asterisk Manager Interface (AMI)”) simply don't offer sufficient granularity. Always assume that a user can initiate actions other than those you have made available on the web page. It is far better to let your application use a PHP script containing only the specific AMI commands it needs to do its job, and to restrict the AMI rights for the accessing user as extra insurance.

Our assessment is that it almost never makes sense to serve other web applications (that is, those intended strictly for administrator access) through the AJAM interface. It is also doubtful that it was intended to, because the rights assignments through read and write (see the section called “The Asterisk Manager Interface (AMI)”) simply don't offer sufficient granularity. Always assume that a user can initiate actions other than those you have made available on the web page. It is far better to let your application use a PHP script containing only the specific AMI commands it needs to do its job, and to restrict the AMI rights for the accessing user as extra insurance.

Example: Getting the number of voicemail messages with AJAM

Again, we are solving the problem addressed in the section called “Example: Getting the number of voicemail messages with expect” and the section called “Example: Getting the number of mailbox messages with PHP”: we want to find out the number of messages in a specified mailbox. The AJAM offers us a few ways to do this:

HTML

The AMI waits for queries at

http://localhost:8088/asterisk/manager

. Packet fields are tacked on the end of the URL. Try these addresses in your web browser:

http://localhost:8088/asterisk/manager?action=Login&username=admin&secret=secret5
http://localhost:8088/asterisk/manager?action=MailboxCount&mailbox=123

The response follows in the form of an HTML page, so it's not really suitable for access via a script.

Plain-Text

If we replace manager in the URL with rawman, we get plain text output. To log in and get a message count from the mailbox, then:

http://localhost:8088/asterisk/rawman?action=Login&username=admin&secret=secret5

Response: Success
Message: Authentication accepted

http://localhost:8088/asterisk/rawman?action=MailboxCount&mailbox=123

Response: Success
Message: Mailbox Message Count
Mailbox: 123
NewMessages: 0
OldMessages: 0

http://localhost:8088/asterisk/rawman?action=Logoff

Response: Goodbye
Message: Thanks for all the fish.

This text output is more script-friendly.

XML

If we want XML instead, we call mxml instead. The XML output is presented formatted for better readability. In practice, AJAM does not put line breaks inside the XML tags. Either way, a compliant XML parser won't care.

http://localhost:8088/asterisk/mxml?action=Login&username=admin&secret=secret5

<ajax-response>
    <response type='object' id='unknown'>
        <generic
            response='Success'
            message='Authentication accepted' />
    </response>
</ajax-response>

http://localhost:8088/asterisk/mxml?action=MailboxCount&mailbox=123

<ajax-response>
    <response type='object' id='unknown'>
        <generic
            response='Success'
            message='Mailbox Message Count'
            mailbox='123'
            newmessages='0'
            oldmessages='0' />
    </response>
</ajax-response>

http://localhost:8088/asterisk/mxml?action=Logoff

<ajax-response>
    <response type='object' id='unknown'>
        <generic
            response='Goodbye'
            message='Thanks for all the fish.' />
    </response>
</ajax-response>

AJAX and AJAM considerations

JSON

AJAX applications - as the name "Asynchronous JavaScript and XML" might suggest - use XML as the standard format, even though it is often criticized for its bloated structure. There are alternatives, such as JSON^[42], for example. JSON (JavaScript Object Notation) is - the name gives it away - well-suited for Javascript applications, because the data structure can be converted into an object natively and with little overhead using eval(). There are countless implementations for PHP, Perl, etc. but a JSON implementation for AJAM does not yet exist. One can, however, convert the plain-text output into JSON on the client side, if that turns out to be easier or if it's easily done using available Javascript libraries. Here's an example to get you thinking:

// We assume the received response and
// simulate it here:
var responseText = 'Response: Success\n'
+'Message: Mailbox Message Count\n'
+'Mailbox: 123\n'
+'NewMessages: 0\n'
+'OldMessages: 0\n';

// Escape single quotation marks:
responseText = responseText.replace( /\'/g, "\\'" );
// Wrap fields in quotes:
responseText = responseText.replace( /^([a-z\d]*):\s*(.*)/gmi, "'$1':'$2
'," );
// Convert to object:
eval('var packet = {'+ responseText +'}');

// Now you can access the fields as you would with any object:
alert( packet['NewMessages'] );   // returns "0"

Ping

When accessing the AJAM with an AJAX application, the ping command is particularly useful for keeping authenticated connections alive.

http://localhost:8088/asterisk/rawman?action=Ping

Response: Pong

AJAM Demo

A small sample application demonstrating AJAX access may be run at

http://localhost:8088/asterisk/static/ajamdemo.html

. This uses the highly practical JavaScript library prototype^[43] for AJAX access and displays, using the Status the currently active channels. You can use the AJAM demo as a basis for your own AJAX applications.

Apache

The Asterisk web server is a minimal implementation and cannot be seen as a wholesale replacement for a "proper" web server that can run PHP scripts or use modules, such as Apache. To unify a system that uses both, you can use Apache as a proxy for AJAM by adding

ProxyPass /ajam http://localhost:8088/asterisk

in the appropriate place in httpd.conf, so that all requests for /ajam are passed on to AJAM instead of being served by Apache.

^[41] http://de.wikipedia.org/wiki/Ajax_(Programmierung)

^[42] http://de.wikipedia.org/wiki/JSON

^[43]http://prototype.conio.net/, also http://www.prototypejs.org/, see http://en.wikipedia.org/wiki/Prototype_Javascript_Framework or http://en.wikipedia.org/wiki/Prototype-based_programming