Switchvox Developer Blog

Build a Parent Notifier using the Extend API

Aaron Daniel
Author: Aaron Daniel
Article posted on May 28th, 2010

Imagine that you’re a school system and you want to create a scheduling system that calls parents when their child is absent from class.  You’re already running the very intuitive, user friendly Switchvox system, and you know it has some neat programming interfaces that allow you to do many interesting things.  This post will strive to satisfy your needs using the Switchvox Extend API’s and a little PHP programming to interface with your Switchvox.

Setup
First, you will need the following things:

  • Switchvox SMB 4.5
  • PHP server of some kind (Linux and Apache are used in this example)
  • Download the ZIP file: Student Scheduling System

If you don’t already have Switchvox running somewhere, you have several options.  Head over to https://www.digium.com/en/forms/swvx_demo.php if you would like to check out Switchvox.

Next, you’ll want to extract the sss.zip file you downloaded earlier into a accessible web directory on the second non-Switchvox server.  For our examples, we’re using CentOS, which stores it’s websites in /var/www/html.

cd /var/www/html
unzip /path/to/sss.zip

Once you’ve extracted the files, you should see a directory named sss, which will be accessible by going to http://servername/sss (where “hostname” is the name or IP address of the server).  It should look something like this:

Now that you have it working, you’ll need to modify the “CallParent.php” script:

  • Change $SVserver to match your server’s hostname
  • Change $SVuser  to the API admin user you want to use
  • Keep in mind that the administrator’s permissions are maintained in the Manage Admins page.  Anything this admin can do can be done through the API as well.
  • Change $SVpass to be the password of the administrator

Now that you’ve got it changed, open up the SSS interface and put in a dialable phone number and click Call.  The status bar should look like this:

screen-shot-2010-05-28-at-114744

If you get a message like this, you might want to check your outgoing call rules or the admin password you set:

screen-shot-2010-05-28-at-142734
Making Changes
Now that you’ve got the PHP scripts installed, you should be able to make your changes to them.  The important files you want to look at are:

  • CallParent.php
  • LookupStudent.php
  • tracker.php
  • tracker.lib.php
CallParent.php

This PHP script allows you to initiate the Call Creation API in Switchvox (switchvox.call).  CallParent.php takes the three required paramaters (dial_first, dial_second, and dial_as_account_id) and hands them off to the Extend PHP Library to initiate the call.

In the file, you’ll see the following section:

$clean_number = preg_replace('/[^0-9]/', '', $_GET['number']);

$request = new SwitchvoxRequest($SVserver, $SVuser, $SVpass);
$requestParams = array(
    'dial_first'               => array($clean_number),        # Cleaned Parent Number
    'dial_second'           => array('4960'),                    # The IVR
    'dial_as_account_id' => array('1550'),                    # Who's calling from SV?
);
$response = $request->send("switchvox.call", $requestParams);

Instead of calling this from a web GUI, you can rewrite this to take arguments from a command line call, and use a cron job to pull information from a database to initiate the call.  I won’t go into detail on how to do that here, but it’s only a small modification to the $clean_number variable assignment.

LookupStudent.php

This script allows the Switchvox to pull information from external systems in an XML format.  We also repurposed it to provide information to a web GUI as well, but the important bits for Switchvox are the following:

<? header ("content-type: text/xml"); ?>
<response>
    <result>
        <ivr_info>
            <variables>
                <variable>
                    <name>ATE_SSS_AbsentPeriod</name>
                    <value>2</value>
                </variable>
                <variable>
                    <name>ATE_SSS_TotalAbsences</name>
                    <value>3</value>
                </variable>
                <variable>
                    <name>ATE_SSS_Suspended</name>
                    <value>yes</value>
                </variable>
            </variables>
        </ivr_info>
    </result>
</response>

There’s two important details to keep in mind here: the header must be XML, and the content must maintain the same basic structure as this XML you see here.  To add more variables, simply add a new <variable> section with the name and value pairs.  Keep in mind, you need to inform Switchvox of the names of the variables in the IVR editor, or it won’t know what to do with them.

To automate this, simply do a database pull before you send the XML to Switchvox.  This will make it a dynamic application you can use in almost any environment.

screen-shot-2010-05-28-at-144433

tracker.php and tracker.lib.php

I split out the logging and response mechanisms of the tracker scripts, which are used by the Event Notification API (URL Manager) in Switchvox.  This is so it’s easier to make changes to one or the other without affecting unexpected areas.  You can build your application as complicated as you like, however, in this example, the tracker.php simply tells the URL Manager to send the Switchboard a URL of “http://www.google.com” to demonstrate it’s functionality.

The tracker_log function simply outputs all details about the call to a log file in the /tmp directory.  You can modify this to enter the information into your own CRM database, or do processing on a particular incoming call.

screen-shot-2010-05-28-at-144525

Wrapping Up
This is just a high level overview of the SSS we demoed in the May 24th Ask the Expert session.  I’d recommend checking it out at: https://www1.gotomeeting.com/register/859361400

One Response to “Build a Parent Notifier using the Extend API”

  1. [...] Build a Parent Notifier using the Extend API [...]

Leave a Comment