FON Script Interface

Fon Script Interface Overview

The FON Script Interface allows software developers and system integrators to extend the functionality of their PBXtra CCE systems by allowing them to create customized extensions to the PBXtra system using a standardized API. This facility allows the creation of custom IVR applications that will impress your friends, and probably get you promoted ;-).

Example Application

One example of a FON Script application is a store locater. This program would prompt the caller to key in his zip code, and look up a list of stores in a cross reference table of a database. Once the correct store is identified the caller is then automatically connected with the correct store.

Prerequisite

You must have the PBXtra Call Center Edition of the Fonality software in order to use this feature. In CCE it will be shown in your call menu as "Run Script".

How To Configure Run Script

1. Log into your PBXtra Admin Web Interface using your administrative username and password.
2. Click on the AutoAnswer tab.
3. Click on the call menu tab.
4. Add a new Call Sequence named Run Script.
5. Specify the path to the script in your /var/lib/asterisk/agi-bin/ directory.

Exmaple:

my_script.agi

Example for a script listening on a port:

fon://ip.add.re.ss:port

Note: If you are running PBXtra Core version 1.2.14-fon-o or newer, you can also pass HTTP style arguments to the script like this:

my_script.agi?extension=${EXTEN}

You can look for them in your script using the environment variables.

Calling Your Script

If you have connected your FON Interface Script to your call menu, you can dial "0" from any of your extensions to reach your main menu, and subsequently reach the AGI for testing. You may also dial in from an external line.

Example Script

This example Perl script is available under the GNU License. It demonstrates basic interaction with the PBXtra Core software from your server using the STDOUT file handle. It also shows how to get digit input from your callers.

#!/usr/bin/perl
use strict;      # Load the strict pragma to enforce good program form
use Socket;      # Load the socket library to let us speak TCP/IP
use Carp;        # Load an error handling library
use IO::Handle;  # Overload the I/O functions with more appropriate ones

my $port = 4573; # TCP Port number to listen on

$|=1; # Activate auto-flush to disable text buffering in perl

# Setup Variables
my %AGI;       # Init a hash structure to be used for AGI environment
my $tests = 0; # A counter for the number of tests that have been run
my $fail = 0;  # A counter for failure conditions
my $pass = 0;  # A counter for success conditions

##############################################################################
# checkresult: A function to check the return status of a command to 
#              detect any errors.
#
#   Arguments: $res = A result from an AGI command
#     Returns: none, sets $pass and $fail counters
##############################################################################
sub checkresult {
        my ($res) = @_;
        my $retval;
        $tests++;
        chomp $res;
        if ($res =~ /^200/) {
                $res =~ /result=(-?\d+)/;
                if (!length($1)) {
                        print STDERR "FAIL ($res)\n";
                        $fail++;
                } else {
                        print STDERR "PASS ($1)\n";
                        $pass++;
                }
        } else {
                print STDERR "FAIL (unexpected result '$res')\n";
                $fail++;
        }
}

# Set up a TCP/IP socket, and bind/listen to it for new connections
# from the PXBtra Core software (the client)
socket(SERVER, PF_INET, SOCK_STREAM, 0);
setsockopt(SERVER, SOL_SOCKET, SO_REUSEADDR, pack("l", 1));
bind(SERVER, sockaddr_in($port, INADDR_ANY)) || die("can't bind\n");
listen(SERVER, SOMAXCONN);

# Start the FastAGI/FON request loop
for(;;) {
        # We will wait for a connection. The accept() call will block until
        # a connection arrives. While processing, connections line up.
        my $raddr = accept(CLIENT, SERVER); # Get the next connection
        my ($s, $p) = sockaddr_in($raddr);  # 
        CLIENT->autoflush(1); # Disable text buffering client connection

        while(<CLIENT>) { # Read all the text sent from the client to the server
                chomp;    # Eliminate any newlines on the end of the text
                last unless length($_); # If the line is empty, stop reading
                if (/^agi_(\w+)\:\s+(.*)$/) { # Look for variables starting with agi_
                        # Set AGI hash keyed by variable name to the value found
                        $AGI{$1} = $2; # $1 is match from first set of parens above
                                       # $2 is match from second set of parens...
                }
        }

        # Print out a summary of the AGI environment. 
        # Visible in asterisk -r console.
        print STDERR "AGI Environment Dump from $s:$p --\n";
        foreach my $i (sort keys %AGI) {
                print STDERR " -- $i = $AGI{$i}\n";
        }

        # Begin the first test. This plays a sound file, checks the result, and
        # counts the result.
        print STDERR "1.  Testing 'sendfile'...";
        # Tell PBXtra Core (client) to play a sound file to the caller
        print CLIENT "STREAM FILE beep \"\"\n"; 
        my $result = <CLIENT>; # Read data from the PBXtra Core (client)
        &checkresult($result); # Check the output fo