Switchvox Developer Blog

Browse Call Recordings with iTunes Cover Flow

dblood — 2012年1月04日 17:51:01 +0000

This tutorial will show you how to convert your call recordings into MP3 files, complete with meta data and cover art, and browse them with Cover Flow in iTunes on a Mac. Along the way, you’ll also learn about call recordings and making Switchvox API calls with Perl.

Let’s say you are a call queue administrator. You have 5 people working for you, answering calls in the queue. You want to be able to easily and quickly review a days worth of calls and determine how everyone is doing. You want to see, roughly, how may calls each person is taking, how long they are, and listen to a few for quality assurance.

You could do all this with a slick interface if you had each call as an MP3 file in iTunes. So, let’s do it.

Prerequisites

You will need a Linux server running FTP and Samba. I assume you already know how to set this up, but if not, there are some great resources on the web.

For my FTP server, I use ProFTPD. It’s included with Fedora and most other Linux distributions. http://proftpd.org
Samba is a great project that allows you to share files from a Linux server on a Windows network. Apple and Linux clients also support Windows file sharing. Samba is also included in most Linux distributions, as well as handy GUI tools to set it up. http://www.samba.org/
To process the call recordings to MP3 files, we will use the open source, command line MP3 encoder called Lame. This is also included in many Linux distributions, but it is often not installed by default. Please note, to be safe, you should have a company license to use MP3 encoding. http://lame.sourceforge.net/

OK, now that those requirements are out of the way, let’s get started!

Step 1: Setting Up Switchvox

First, let’s set up the call recordings. Switchvox enables you to backup call recordings to an FTP server, then deletes them from the Switchvox PBX. We will first enter our FTP server settings, then enable call recording for all calls in our call queue.

In the Switchvox Admin interface, click on “Tools -> Call Recording”. Then click on “Modify Recording Settings”. Enter the FTP Hostname, FTP Username, FTP Password and FTP Path, if needed. Click on “Test FTP Settings”. A new window will open, and if your entered everything correctly, all five tests should be marked with a green “Passed”. If not, correct any errors and test again. When you are finished, click “Save Settings”

[画像:ftp_settings]

Now, click “Create Call Recording”. At the top of the page, enter a label in the box next to “Call Recording Label”. This string will be turned into a directory name on your FTP server, and all calls recorded with this recording rule will be placed in that directory. I labeled mine “Queue Calls”. Next, in the “Recording Targets” box, click “Call Queues”, and click on the queue(s) you want to record.

[画像:call_recordings_1]

Scroll down to “Call Recording Limit” and set a limit. I chose “Until the date/time” and chose a date 1 year from today. Then, under “How Long to Keep Recordings”, click “Backup and then delete calls after” and change to 10 to 1.

[画像:call_recordings_2]

Click “Save Call Recording” and we’re done with this part. Now, all calls in the queues you specified will be backed up every 15 minutes to the FTP server specified in the previous step.

Step 2: Processing the Call Recordings

OK, so far so good. All of our queue calls are getting recorded and then backed up on our FTP server. Mine are going into the directory “/home/call_recordings/Queue_Calls”. We now need to take these recordings, which are WAV files, and convert them in MP3 files with cover art and metadata. To do this, we’ll use a Perl script and the Lame MP3 encoder.

The Perl script needs to do several things:

Parse the XML file associated with each call recording to get the data about the call.
Use that data to get a profile image from the Switchvox PBX.
Make an MP3 file for each call recording, and place it in a directory shared via Samba.
Keep track of what it’s already done, so it doesn’t process a file multiple times.

To accomplish this, we’ll use the following CPAN modules:

File::Find
XML::Simple
Switchvox::API

First, let’s define some global variables that tell the rest of the code where to find things:

my $SOURCE_DIR = '/home/call_recordings/Queue_Calls';
my $DESTINATION_DIR = '/home/dblood/call_recordings';
my $PBX_HOSTNAME = '10.10.2.106';
my $PBX_LOGIN = 'admin';
my $PBX_PASSWORD = 'admin';
my $DATA_DIR = '/home/call_recordings';

$SOURCE_DIR is the directory on the server where the call recordings are backed up.
$DESTINATION_DIR is the shared Samba directory where the MP3 file will go.
$DATA_DIR is where the file that holds our history data will be kept.
$PBX_* are the specifics of your Switchvox PBX.

Next, we have the main steps:

my %already_done = load_history();
my @processed;
File::Find::find(\&process, ($SOURCE_DIR));
save_history(@processed);

First we load the history. This is all the filenames we’ve already processed, so we don’t process them again. They are saved in a text file, one filename per line. We load them into a hash for easy look up.

Next, we use File::Find to process every file in the $SOURCE_DIR. For each file, it calls the subroutine process() with the filename.

Finally, we add the list of processed files to out history.

The important part here is the processing of files. Let’s take a look at that.

sub process {
	my $filename = $_;
	if ($filename !~ /.xml$/) {
		return;
	}
	if ($already_done{$filename}) {
		return;
	}
	my $wav_file = $filename;
	$wav_file =~ s/\.xml$/\.wav/;
	$wav_file = $File::Find::dir . "/" . $wav_file;
	# is the wav file here?
	if (! -e $wav_file) {
		print STDERR "$wav_file is missing - skipping\n";
		next;
	}
	print "processing $filename\n";
	my $data = XML::Simple::XMLin($File::Find::name, ForceArray => 0, KeyAttr => '' );
	my $call_id = $data->{recorded_call_id};
	my $name = $call_id . ' - ' . $data->{to_caller_id} . " - " . $data->{from_caller_id};
	my $queue = $data->{recorded_cid};
	my $queue_member = $data->{to_caller_id};
	my $date = $data->{date_created_ts};
	# get the image for the queue member
	my $image_filename = get_profile_image($data->{to_account_id});
	# set up the lame command & arguments
	my @command = ('lame', '--tt', $name, '--tl', $queue, '--ta', $queue_member, '--tc', "Date: $date", '--add-id3v2');
	# if we have an image, use it
	if (defined $image_filename) {
		push @command, '--ti';
		push @command, $image_filename;
	}
	push @command, $wav_file;
	push @command, $DESTINATION_DIR . "/" . $queue . " - " . $name . ".mp3";
	# make the mp3 file
	system(@command);
	push @processed, $filename;
}

Remember, this subroutine is called with the filename of every file in the $SOURCE_DIR directory. That includes a WAV file and an XML file for each call recording. We only want the XML files for now, so filter the WAV files out. Also, don’t process any files we already processed in previous runs.

Next, we need to get the filename of the WAV file associated with the XML file we are proccessing. They have the same name, but obviously the extension is different. Also, we need the full path. That is contained in the package variable $File::Find::dir.

After testing that the WAV file actually exists, we move on to extracting the metadata from the XML file. We convert the XML to a hash with XML::Simple::XMLin for easy access, then, for better readability, assign the data we are interested in to individual variables. The XML looks like this:


 Queue Calls
 1008
 
 The Queue <301>
 
 1186
 
 858 765-9812
 1130
 James Smith <103>
 389
 2011年10月20日 14:18:18.819689
 1319145499

Next, we use the Switchvox API get the URL of the profile image for the queue member that took the call, and save it to disk. I’ll explain this in more detail later. Then we assemble the lame command line, and pass it to the Perl command “system” for execution. Last, we push the filename we just just processed onto the @processed array to save to our history at the very end.

This is all everyday Perl stuff. But how do we use the Switchvox API to get the profile image? Switchvox::API is available from CPAN, and you can take a look at it here: http://search.cpan.org/~dwp/Switchvox-API-1.0/lib/Switchvox/API.pm

Here’s our get_profile_image subroutine:

sub get_profile_image {
	my ($account_id) = @_;
	my $api = new Switchvox::API(
								 hostname => $PBX_HOSTNAME,
								 username => $PBX_LOGIN,
								 password => $PBX_PASSWORD
								);
	my $method = 'switchvox.extensions.getInfo';
	my $params = {
				 account_ids => {
								 account_id => [$account_id]
								 }
				 };
	my $response = $api->api_request(
									 method => $method,
									 parameters => $params
									);
	my $filename;
	if ($response->{api_status} eq 'success') {
		my $response_data = XML::Simple::XMLin($response->content, ForceArray => 0, KeyAttr => '' );
		if ($response_data && $response_data->{result} && $response_data->{result}->{extensions} &&
			$response_data->{result}->{extensions}->{extension}) {
			my $url = $response_data->{result}->{extensions}->{extension}->{profile_image_link};
			$filename = '/tmp/' . $account_id . '.jpg';
			system('wget', '-O', $filename, '--no-check-certificate', $url);
		}
	} 
	return $filename;
}

First, instantiate a Switchvox::API object with the hostname, username and password for your Switchvox PBX. Next we define the method name, in this case “switchvox.extensions.getInfo”. The documentation for this method can be found here: http://developers.digium.com/switchvox/wiki/index.php/Switchvox.extensions.getInfo

Then, we define the parameters. In this case, we have the account ID, so we use that. The Perl data structure:

{
 account_ids => {
 account_id => [$account_id]
 }
}

is equivalent to the XML

Next, we make the request, check for success, and then access the response hash key “profile_image_link”. The best way to see what your dealing with in the response is to use Data::Dumper. The code

print Dumper $response_data;

will print the response data structure to the terminal. Don’t forget to “use Data::Dumper;” if you do this.

Finally, we need the profile image on disk. To do this, we use wget.

After all this, we return the filename of the profile image on disk, or undef if we were unable to get one.

The final step in this section is to create a cron that will run our Perl script once or twice a day. I’ll leave that to the reader, but you can find some hints here: http://en.wikipedia.org/wiki/Cron

Step 3: Getting the MP3 Files into iTunes

Now we have an MP3 file for each call recording in the shared Samaba directory. We just need to get these files into iTunes on our Mac.

iTunes is pretty picky about how it handles media. It needs the media files to be stored locally. We’ll use Automator to make an app that will import the files into iTunes from the mounted Samba directory.

First, lets make a playlist that will hold only the call recordings. Open iTunes, and at the top click on “File” and then “New Playlist”. A new playlist will apear on the bottom of the left panel, already highlighted. Name this “Call Recordings”

Next, let’s mount the Samba directory from the server. In Finder, click “Go -> Connect To Server”. A list of servers will pop up. Choose your Smaba server, and your Mac should connect. If it goes well, a new Finder window will appear.

Now, let’s make a directory on your Mac where we can store the MP3 files. I made it in my home directory and called it “call_recordings”.

Next, let’s make the Automator app.

Open Finder, and click on “Applications” in the left panel.
Double click “Automator”
Make sure “Workflow” is highlighted in the top panel and click “Choose”
In the left hand column under “Library” select “Files and Folders”
In the next column double-click “Get Specified Finder items”
A “Get Specified Finder Items” pane should open on the main screen.
Click the “Add” button on this screen and select the Samba folder, in our case “dblood -> call_recordings”
Now from the second column from the left double-click on the “Get Folder Contents” action.
In the leftmost column click on “Files and Folders” then in the next column click on “Move Finder Items”
In this pane, in the first drop down, select “Other” and navigate to the directory you created on your Mac to store the MP3 files. Be sure to also check the box “Replace existing files”
Now on the left-most column click on “music” then in the next column dobule-click on “Import Files into iTunes”
In the first drop down, “Existing Playlist” should already be selected. In the second drop down, choose the playlist we created earlier, “Call Recordings”

Save it to your desktop, using “File -> Save”, and be sure to save it as File Format: Application.

[画像:automator]

Find the Automator app you just created, and run it. It should import the mp3 files into iTunes, and open iTunes. Click on the “Call Recordings” playlist, and choose “View -> as Cover Flow”. Now you can easily browse and listen to your call recordings.

[画像:itunes_final]

Anytime you want to browse new call recordings, just make sure the Samba share is mounted, and run the Automator app again.

Step 4: Additional Steps

My tutorial is done, but there are some further step you might want to take on your own:

Schedule the import into iTunes to happen automatically once per day.
Change the metadata we pass to Lame to make it more useful to your situation.

I’m sure you can think of many more. You can download the code from this tutorial here Enjoy!

]]>

Sending Alerts for Important Queue Metrics

junichi — 2011年11月18日 18:26:03 +0000

This tutorial shows you how to create a perl script to send email alerts when important call queue metrics are reached. For example the total number of abandoned calls for a queue can become extremely high. The manager in charge will be notified via email or text message so he can follow up with his team to assess the situation.

Prerequisites:

Experience in perl and setting up cron jobs
Familiarity with the Extend API
The Switchvox::API perl library downloaded and installed.

Create an iCal Appointment Reminder System

Adrian Phruksukarn — 2011年10月21日 22:15:44 +0000

This tutorial will show you how to create a reminder system that will call you to remind you of upcoming meetings.

Ten minutes before each event in your calendar, your Switchvox PBX will call you to remind you that you have an upcoming appointment. If a phone number is found in your meeting description, you will have the option to press ‘1′ and have the Switchvox PBX call you back and connect you to that number at the meeting time. When your PBX calls you to connect you to that number, it will read to you any pin or extensions that it found in the appointment description before connecting you to the call.

For example, take the following scenario:

Let’s say I have the following appointment in iCal:
[画像:iCal Meeting]
At 1:20 on that day, my phone will ring, and I’ll hear the following prompt:

“You have an appointment beginning in ten minutes. The following phone number was found in your appointment details: eight, five, eight, five, five, five, one, two, one, two. Press 1 if you would like the PBX it initiate a call to this number at the appointment time. Otherwise press 2.”

Since I know that the number I heard is the conference bridge I use with Joe and Fred, I press 1 so that I can automatically call in to the meeting.

Ten minutes later, my phone rings and I hear the following:

“The system found the following pin or extension in your appointment details: five, five, five, five. You will now be connected to you call.”

I then hear ringing on my phone, and am then connected to the conference bridge that Joe and Fred use. When prompted, I know to enter 5555 to join the correct conference room and Joe, Fred, and I begin our meeting.

This all sounds pretty complicated, but it’s actually quite simple to accomplish with some IVRs, the switchvox.call API, and just a small bit of coding. I will walk you through the whole process. This example is written in perl, but it shouldn’t be too difficult to write this using another language. This tutorial also assumes that the calendar application you are using stores or can export your appointments in iCalendar format. Most major applications do. A list of applications that support the iCalendar format can be found here.

Prerequisite: Review the Documentation

I suggest that before you start this tutorial, you read over some of the documentation and become familiar with the Extend API. This way, you will have some background to better understand everything in this tutorial. If you choose to skip this reading now, I strongly recommend you go back and review it before writing any applications of your own.

Recommended Reading:

Application Overview

The first item you’ll need to address for building this application is getting the most up to date iCalendar file of your appointments. There are many ways to achieve this, but I won’t be going over them in detail. I accomplished this task by creating an Automator workflow on my Mac to export my “Appointments” calendar from iCal. I then used iCal to schedule the workflow to run every night at 3 am (see here). Finally, I have a cron job on my Ubuntu machine that fetches the most recent iCal export at 3:15am every day.

Once you have a method for getting the most up to date iCalendar compliant file containing all of your appointments, the application consists of the following:

A perl script that runs on a cron to check if any calls need to be made.
A mod_perl script running on Apache that accepts requests from the Switchvox PBX.
A postgresql database with two tables for storing information about calls we need to make.
Some IVRs on your Switchvox PBX.

That’s it!

Step 1: Verify your setup

If the machine where you’ll be hosting your application is on the same network as your Switchvox PBX, you shouldn’t have to do anything to get access to the Extend API. If not, you’ll have to make sure that the application can access port 443 on your Switchvox. Also, be sure that the Switchvox Access Control lets your web server have access to the Admin API Service.

The easiest way to test all this is to ssh into your web server and then follow the Interact with the Extend API using Wget tutorial. By the end of that tutorial, you should have sent and received some sample XML, and you’ll be ready to continue.

Step 2: Setting up Switchvox

First we’ll tackle all the tasks we need to perform on our Switchvox to make this application works:

Recording Sounds

We need to record a few sounds that we’ll use as prompts in IVRs. In your Switchvox Admin interface, got to Tools -> Media -> Sound Manager. Here, we’re going to need to create 5 sounds. Here are the sounds I created and what I named them:

Sound Name	Description
Upcoming Appointment	“You have an upcoming appointment in 10 minutes.”
Upcoming Appointment: has number	“The following phone number was found in your appointment details.”
Upcoming Appointment: callback	“Press 1 if you would like the PBX to initiate a call to this number at the appointment time. Otherwise press 2.”
Upcoming Appointment: pin or ext	“The system found the following pin or extension in your appointment details.”
Upcoming Appointment: connecting	“You will now be connected to your call.”

IVR Menus

The next step is to create the IVR menus that will process our reminders. I created 4 IVR menus in call. First I created one which I named Appointment Reminders:

[画像:Appointment Reminders IVR Menu]

Here’s a breakdown of the actions in the IVR menu:

The first action this IVR menu does is play the sound that tells you that you have an appointment in 10 minutes.
It then has a conditional cause that checks an IVR variable called has_number. If this variable is not equal to 1, the caller will be redirected to the “Hangup” IVR menu because there is nothing more to do.
Otherwise, the next action is to play the sound which informs the user that a phone number was found in the appointment details.
It then uses the “Say Digits/Letters” action to read the phone number we found. This phone number is found in an IVR variable called callback_number.
It then plays the sound that asks the user to press 1 if they would like their Switchvox to set up the call at the appointment time, or 2 if not.
Finally, it listens for the user to select an option. If the caller presses 2, they are redirected to the “Hangup” IVR, and if they press 1, they are redirected to the “Appointment Setup callback” IVR menu.

You might be wondering how the IVR variables are getting set. We’ll get into that with our perl script later on, so for now just trust me that those variables will be set with the appropriate values.

The “Appointment Setup callback” IVR menu consists only of two actions. It uses Send Call Values to URL, and then redirects the call to the Hangup IVR menu.

[画像:Appointment Setup callback]

The key here is the Send Call Values to URL action. Since the user wants to be called at the appointment time I need to send the information from the call back to my application. The URL for my action is the following:

http://10.10.8.0/confirm_callback?callback_number=%callback_number%&callback_pin=%callback_pin%&appointment_id=%appointment_id%

I’m sending the following IVR variables to my mod_perl script:

callback_number - The number to call
callback_pin - Any pin or extension we found in the appointment details
appointment_id - The ID of the appointment

With those two IVR menus we’ve handle the reminder part of our application covered, next we’ll create two more IVR menus that handle the callback part.

First let’s have a look at the “Appointment callback” IVR menu:

[画像:Appointment callback]

This IVR menu is very simple. It has only three actions:

The first action is a Conditional Clause. If the has_number IVR variable is equal to 1, it sends the caller to the “Appointment remind pin” IVR Menu.
Otherwise, it continues and plays the sound that informs the caller they are being connected to their call.
Finally it sends the caller to an external number. The number to send the call to is in the callback_number IVR Variable. (Please note that depending upon your system setup, you may need to create a call rule to be used by this action to ensure your 10 digit number gets routed out to the correct provider on your system. Please see your Switchvox documentation on call rules for more details.)

The “Appointment remind pin” IVR menu is equally as simple:

[画像:Appointment remind pin]

This IVR Menu has three actions:

It plays a sound letting the caller know that a pin or extension was found along with the phone number in the appointment details.
It then uses the Say Digits/Letters action to read the number back to the caller from the callback_pin IVR variable.
It then redirects the caller to action two in the “Appointment callback” IVR menu.

Create IVR Extensions

The last step in all this is to create a couple of IVR Extensions. For my application I set up extension 600 to route to the “Appointment Reminders” IVR menu and extension 601 to route to the “Appointment callback” IVR menu.

[画像:IVR Extensions]

With that we are done setting up all the pieces we need on our Switchvox PBX.

Step 3: Database Schema

The rest of my application will be running on an Ubuntu machine. On that machine I set up a PostgreSQL database to store some information about calls that need to be made. I created two tables in my database:

CREATE TABLE appointment_callbacks (
 appointment_id varchar(128),
 callback_number varchar(16),
 callback_pin  varchar(6)
);
CREATE TABLE finished_reminders (
 appointment_id varchar(128),
 call_type    varchar(16)
);

The finished_reminders table is used to store appointments we’ve already called about to make sure we don’t accidentally call ourselves about the same appointment twice. The appointment_callbacks table is used to schedule calls that connect us to our meeting phone numbers.

Step 4: Getting perl Modules

You are going to need a few perl modules to write the rest of the application. In addition to all the modules for mod_perl and connecting to a PostgreSQL database, you’ll need the following:

iCal::Parser
Switchvox::API

If you’re unfamiliar with how to get or install perl modules, http://www.cpan.org is a good place to start reading.

Step 5: Writing the SetCallback Handler

The next step is to write our SetCallback handler. This is what will handle the Send Call Values to URL action from our “Appointment Setup callback” IVR menu. The code for this handler is pretty straightforward. We simply take the values we get from the IVR action and insert them into our appointment_callbacks table:

package SetCallback;
use strict;
use warnings;
use Apache2::RequestRec;
use Apache2::Const -compile => qw(OK);
use DBI;
use CGI;
use Data::Dumper;
sub handler {
 my $apache = shift;
 my $cgi = new CGI($apache->args);
 my ($sql, $sth, $db);
 $db = DBI->connect("dbi:Pg:dbname=appointments", "db_user", "db_pass");
 my $insert_values = {};
 $insert_values->{appointment_id} = $db->quote($cgi->param('appointment_id'));
 $insert_values->{callback_number} = $db->quote($cgi->param('callback_number'));
 $insert_values->{callback_pin} = $db->quote($cgi->param('callback_pin'));
 if (!$insert_values->{callback_pin}) {
 delete $insert_values->{callback_pin};
 }
 my $sql = "INSERT INTO appointment_callbacks (" . join(', ', keys %$insert_values) . ") ".
 "VALUES (" . join(', ', values %$insert_values) . ")";
 $sth = $db->prepare($sql);
 $sth->execute();
 return Apache2::Const::OK;
}
1;

Now, when a caller presses 1 to ask to be called back at the appointment time, our handler will take the store the call information in our database.

Step 6: Appointment Checking Script

Finally, we’re at our last step. This script is the brains of our application and is a little more involved than our handler script, but still not too bad. I called my script checkAppointments.pl and I’ll break it down for you here in sections.

Setting up modules and variables

This part of the script simply loads the needed perl modules and sets up some variables I’ll need later on.

#!/usr/bin/perl
BEGIN { $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0; }
use Data::Dumper;
use DateTime;
use DBI;
use iCal::Parser;
use Switchvox::API;
my $ICAL_FILE = 'icsFiles/Appointments.ics';
my $EXTENSION = 100;
my $ACCOUNT_ID = 1102;
my $REMIND_IVR = 600;
my $CONNECT_IVR = 601;
my $SV_HOST = '10.10.2.202';
my $SV_ADMIN = 'admin';
my $SV_PASSWORD = 'password';
my $db;

I set the PERL_LWP_SSL_VERIFY_HOSTNAME environment variable equal to 0 because I haven’t set up my Switchvox with a valid SSL certificate, and I don’t want my API request to fail. My phone extension is 100 and my account_id is 1102. You can find the account_id for your extension by calling the switchvox.extensions.getInfo API. The REMIND_IVR and CONNECT_IVR variables are set to the two IVR extensions we created earlier. The ICAL_FILE variable should point to where your iCalendar compliant file can be found. Everything else should be pretty self explanatory.

In the next chunk of code, I parse the iCalendar file and use the current date to get only today’s events.

#Get current date/time
my $now = DateTime->now();
my $day = $now->day();
my $month = $now->month();
my $year = $now->year();
my $now_epoch = $now->epoch();
#parse iCalendar file
my $parser = new iCal::Parser();
my $hash = $parser->parse($ICAL_FILE);
my $calendar = $parser->calendar();
my $todays_events = $calendar->{events}{$year}{$month}{$day};

If you read the documentation for iCal::Parser, you’ll see that the calendar object that the parser returns is a hash broken up by date. For each date, the value is a hash of events, with the event’s id as a key, and an event hash as the value. Knowing that, we’ll loop through the todays_events hash in our next block of code:

# check all of todays events
foreach my $event_uid (keys %{$todays_events}) {
 my $event = $todays_events->{$event_uid};
 my $event_start_datetime = $event->{DTSTART}; 
 # make sure event hasn't happened yet
 if ($event_start_datetime->epoch() > $now_epoch) {
 my $time_difference = $event_start_datetime->delta_ms($now);
 if ($time_difference->{minutes} < 11 && $time_difference->{minutes} > 9) {
 make_reminder_call(
 event_uid => $event_uid,
 db => $db,
 event => $event
 );
 } elsif ($time_difference->{minutes} < 2) {
 check_for_callback(
 event_uid => $event_uid,
 db => $db
 );
 }
 }
}

We get the start time of each event and compare it to the current time to make sure the event time has not passed yet. If it hasn’t we use the delta_ms function of the DateTime perl module to determine how many minutes away the event’s start time is from the current time. If that time difference is between 11 and 9 minutes, we call our make_reminder_call subroutine. If it is less than 2 minutes, we call the check_for_callback subroutine. We give ourselves a couple minutes of leeway just in case there is a delay in running our script. The two subroutines we call will account for this to prevent from multiple calls occurring for the same appointment.

Next, here’s a peek at our make_reminder_call subroutine:

# Initiate a call to remind user of appointment
sub make_reminder_call {
 my %in = @_;
 my ($sql, $sth, $callback_number, $callback_pin);
 my $db = $in{db};
 my $event_uid = $in{event_uid},
 my $event = $in{event};
 my $has_number = 0;
 if (!$db) {
 $db = DBI->connect("dbi:Pg:dbname=appointments", "ajp", "ajp");
 }
 # check if we've already made a call for this event
 $sql = "SELECT COUNT(*) FROM finished_reminders ".
 " WHERE call_type = 'remind' AND appointment_id = '$event_uid'";
 $sth = $db->prepare($sql);
 $sth->execute();
 my $already_reminded = $sth->fetchrow_array;
 return if $already_reminded;
 if ($event->{DESCRIPTION} =~ m/\(?(\d{3})\)?[\s-.]?(\d{3})[\s-.]?(\d{4})/) {
 $has_number = 1;
 $callback_number = 1ドル.2ドル.3ドル;
 $event->{DESCRIPTION} =~ m/(\(?\d{3}\)?[\s-.]?\d{3}[\s-.]?\d{4})/;
 my $whole_num = 1ドル;
 # see if we have a pin or ext in the description after the phone number
 my $index_after_number = index($event->{DESCRIPTION}, $whole_num) + length($whole_num);
 my $string_after_number = substr($event->{DESCRIPTION}, $index_after_number);
 if ($string_after_number =~ m/(\d{3,6})/) {
 $callback_pin = 1ドル;
 }
 }
 $sql = "INSERT INTO finished_reminders (call_type, appointment_id) ".
 "VALUES ('remind', '$event_uid')";
 $sth = $db->prepare($sql);
 $sth->execute();
 make_call(
 has_number => $has_number,
 callback_number => $callback_number,
 callback_pin => $callback_pin,
 appointment_id => $event_uid,
 ivr => $REMIND_IVR
 );
}

Because we have a two minute window for when a reminder call will be initiated, we first check the finished_reminders table to make sure we haven’t already made a reminder call for this appointment. If we have we’ll just return. Otherwise, we use a regular expression to see if we can find anything that matches a phone number in the event’s description. If we find a phone number, we set the has_number variable equal to 1. We also look at the description after the phone number to see if we can find anything that might be a pin or an extension. Finally, we insert into the finished_reminders table to make sure we don’t make a reminder call for this appointment again, and then we call the make_call subroutine to actually make the call.

Next is the check_for_callback routine which is called to see if an appointment that is about to start requires a call to connect the user to a phone number in the event description:

# Check if the user wants a call for this meeting, initiate callback if yes
sub check_for_callback {
 my %in = @_;
 my ($sql, $sth);
 my $has_number = 0;
 my $db = $in{db};
 my $event_uid = $in{event_uid};
 if (!$db) {
 $db = DBI->connect("dbi:Pg:dbname=appointments", "ajp", "ajp");
 }
 # check if we're supposed to initiate the call for this event
 $sql = "SELECT * FROM appointment_callbacks WHERE appointment_id = '$event_uid'";
 $sth = $db->prepare($sql);
 $sth->execute();
 my $callback = $sth->fetchrow_hashref;
 return if !$callback->{appointment_id};
 # check if we've already made a call for this event
 $sql = "SELECT COUNT(*) FROM finished_reminders ".
 " WHERE call_type = 'callback' AND appointment_id = '$event_uid'";
 $sth = $db->prepare($sql);
 $sth->execute();
 my $already_reminded = $sth->fetchrow_array;
 return if $already_reminded;
 if ($callback->{callback_pin}) {
 $has_number = 1;
 }
 $sql = "INSERT INTO finished_reminders (call_type, appointment_id) ".
 "VALUES ('callback', '$event_uid')";
 $sth = $db->prepare($sql);
 $sth->execute();
 make_call(
 has_number => $has_number,
 callback_number => $callback->{callback_number},
 callback_pin => $callback->{callback_pin},
 appointment_id => $event_uid,
 ivr => $CONNECT_IVR
 );
}

This subroutine first queries the appointment_callbacks table to see if we need to make a call for this appointment. If you look back at the perl handler that is called by the Send Call Values to URL IVR action, you’ll recall that if the user requested to be called back at the appointment start time, we inserted a row into this table. If we don’t find a row for our appointment in the appointment_callbacks table, then we just return from the subroutine. Next, because we have two minute window for this subroutine to be called for an appointment, we check the finished_reminders table to see if we’ve already made a call for this appointment. If we’ve already made a call, we just return. Finally, we insert into the finished_reminders table and then take the values from the appointment_callbacks table and call the make_call subroutine.

That brings us to the last piece of the puzzle, which is our make_call subroutine.

# actually make the call
sub make_call {
 my %in = @_;
 my $has_number = $in{has_number};
 my $callback_number = $in{callback_number};
 my $callback_pin = $in{callback_pin};
 my $appointment_id = $in{appointment_id};
 my $ivr = $in{ivr};
 my $api = new Switchvox::API(
 hostname => $SV_HOST,
 username => $SV_ADMIN,
 password => $SV_PASSWORD
 );
 my $response = $api->api_request(
 method => 'switchvox.call',
 parameters => {
 dial_first => $EXTENSION,
 dial_as_account_id => $ACCOUNT_ID,
 dial_second => $ivr,
 variables => [ {
 variable => [
 'has_number=' . $has_number,
 'callback_number=' . $callback_number,
 'callback_pin=' . $callback_pin,
 'appointment_id=' . $appointment_id
 ]
 } ]
 }
 );
}

This subroutine simply takes the values that are passed into it and makes and request to the switchvox.call API. The “variables” parameters that we pass in are used by the call API to set IVR variables. That’s how our IVR knows which way to route the call and which digits to read back on the call.

Wrap Up

The last thing I did for this application was to create a cron job to call my checkAppointments.pl script once every minute. Now I’ll never forget about another meeting again. That’s the end of my little tutorial, but there’s probably more you should do if you wanted to use this application in a production environment. For example, some error checking and exception handling would be a good idea, and you probably only want to parse your iCalendar file if it had actually changed. I hope this little write up has given you some ideas for using the Switchvox Extend API. It makes it possible to create some pretty powerful applications with relatively minimal effort. You can download all the code from this example here

]]>

5.0 Released - Over 175 new Switchvox APIs

David Podolsky — 2011年6月09日 19:57:59 +0000

Last week we released Switchvox 5.0 that has a ton of new features and also includes over 175 new Switchvox API calls. Switchvox developers can use these new API calls to build applications that integrate their Switchvox PBX with the rest of their business applications. Below is a list of the new API calls and descriptions of what they are used for. For more information on each call just visit our Developers Wiki for full descriptions, parameter details, and example requests and responses for each method.

Extensions

switchvox.extensions.getInfo - Retrieve simple information about extensions.
switchvox.extensions.getVoicemailInfo - Gets the voicemail/fax disk usage information for every phone extension.
switchvox.extensions.search - Search extensions and retrieve simple extension information.
switchvox.extensions.checkConflicts - Check for any unwated conflicts with a new extension number.

Extensions Agent Log In/Out

switchvox.extensions.agentLogIn.add - Add an Agent Log In extension
switchvox.extensions.agentLogIn.getInfo - Get details about an Agent Log In extension
switchvox.extensions.agentLogIn.remove - Remove an Agent Log In extension
switchvox.extensions.agentLogIn.update - Update an Agent Log In extension
switchvox.extensions.agentLogOut.add - Add an Agent Log Out extension
switchvox.extensions.agentLogOut.getInfo - Get details about an Agent Log Out extension
switchvox.extensions.agentLogOut.remove - Remove an Agent Log Out extension
switchvox.extensions.agentLogOut.update - Update an Agent Log Out extension

Extensions Call Parking

switchvox.extensions.callParking.add - Create a call parking extension.
switchvox.extensions.callParking.getInfo - Retrieve information about a call parking extension.
switchvox.extensions.callParking.remove - Remove a call parking extension.
switchvox.extensions.callParking.update - Update a call parking extension.

Extensions Call Queues

switchvox.extensions.callQueues.add - Create a Call Queue extension
switchvox.extensions.callQueues.getInfo - Get details about a Call Queue extension
switchvox.extensions.callQueues.remove - Delete a Call Queue extension
switchvox.extensions.callQueues.update - Update a Call Queue extension
switchvox.extensions.callQueues.members.add - Add members to an existing Call Queue
switchvox.extensions.callQueues.members.remove - Remove members from an existing Call Queue

Extensions Simple and Meetme Conferencing

switchvox.extensions.meetMeConference.add - Create a meet me conference room extension.
switchvox.extensions.meetMeConference.getInfo - Retrieve information about a meet me conference room extension.
switchvox.extensions.meetMeConference.remove - Remove an meet me conference room extension.
switchvox.extensions.meetMeConference.update - Update a meet me conference room extension.
switchvox.extensions.simpleConferenceRoom.add - Create a simple conference room extension.
switchvox.extensions.simpleConferenceRoom.getInfo - Retrieve information about a simple conference room extension.
switchvox.extensions.simpleConferenceRoom.remove - Remove an simple conference room extension.
switchvox.extensions.simpleConferenceRoom.update - Update a simple conference room extension.

Extensions Dialtone

switchvox.extensions.dialTone.add - Create a dial tone extension.
switchvox.extensions.dialTone.getInfo - Retrieve information about a dial tone extension.
switchvox.extensions.dialTone.remove - Remove a dial tone extension.

Extensions Directory

switchvox.extensions.directory.add - Create a directory extension.
switchvox.extensions.directory.getInfo - Retrieve information about a directory extension.
switchvox.extensions.directory.remove - Remove a directory extension.
switchvox.extensions.directory.update - Update a directory extension.

Extensions Feature Codes

switchvox.extensions.featureCodes.callMonitoring.add - Create a call monitoring feature code
switchvox.extensions.featureCodes.callMonitoring.getInfo - Retrieve information about a call monitoring feature code
switchvox.extensions.featureCodes.callMonitoring.remove - Delete a call monitoring feature code
switchvox.extensions.featureCodes.directedPickup.add - Create a directed pickup feature code
switchvox.extensions.featureCodes.directedPickup.getInfo - Retrieve information about a directed pickup feature code
switchvox.extensions.featureCodes.directedPickup.remove - Delete a directed pickup feature code
switchvox.extensions.featureCodes.fax.add - Create a fax feature code
switchvox.extensions.featureCodes.fax.getInfo - Retrieve information about a fax feature code
switchvox.extensions.featureCodes.fax.remove - Delete a fax feature code
switchvox.extensions.featureCodes.fax.update - Update a fax feature code
switchvox.extensions.featureCodes.goToVoicemail.add - Add a go to voicemail feature code
switchvox.extensions.featureCodes.goToVoicemail.getInfo - Gte details about a go to voicemail feature code
switchvox.extensions.featureCodes.goToVoicemail.remove - Remove a go to voicemail feature code
switchvox.extensions.featureCodes.personalIntercom.add - Create a personal intercom feature code
switchvox.extensions.featureCodes.personalIntercom.getInfo - Retrieve information about a personal intercom feature code
switchvox.extensions.featureCodes.personalIntercom.remove - Delete a personal intercom feature code
switchvox.extensions.featureCodes.personalIntercom.update - Update a personal intercom feature code

Extensions Group Pickup

switchvox.extensions.groupPickup.add - Create a group pickup extension.
switchvox.extensions.groupPickup.getInfo - Retrieve information about a group pickup extension.
switchvox.extensions.groupPickup.remove - Remove a group pickup extension.
switchvox.extensions.groupPickup.update - Update a group pickup extension.
switchvox.extensions.intercom.add - Create an intercom extension.

Extensions Intercom

switchvox.extensions.intercom.getInfo - Retrieve information about an intercom extension.
switchvox.extensions.intercom.remove - Remove an intercom extension.
switchvox.extensions.intercom.update - Update an intercom extension.

Extensions IVRs

switchvox.extensions.ivr.add - Create an IVR extension.
switchvox.extensions.ivr.getInfo - Retrieve information about an IVR extension.
switchvox.extensions.ivr.menus.getList - Get a list of IVR extensions.
switchvox.extensions.ivr.remove - Remove an IVR extension.
switchvox.extensions.ivr.update - Update an IVR extension.

Extensions Phones (Sip,Analog,Virtual)

switchvox.extensions.phones.attachImage - Attach a profile image to an extension.
switchvox.extensions.phones.bulk.upload - Create extensions in bulk from a CSV file.
switchvox.extensions.phones.outgoingCallRules.add - Attach a list of outgoing call rules to a list of phone accounts.
switchvox.extensions.phones.outgoingCallRules.remove - Remove a list of outgoing call rules from a list of phone accounts.
switchvox.extensions.phones.sip.add - Create a SIP extension.
switchvox.extensions.phones.sip.update - Update a SIP extension.
switchvox.extensions.phones.virtual.update - Update a virtual extension.

Extension Templates

switchvox.extensions.phones.template.getInfo - Get detailed information about a phone template.
switchvox.extensions.phones.template.getList - Get a list of phone templates
switchvox.extensions.phones.template.add - Create an extension template
switchvox.extensions.phones.template.update - Update an extension template
switchvox.extensions.phones.template.remove - Remove an extension template

Extension Voicemail Access

switchvox.extensions.voicemailAccess.add - Create a voicemail extension
switchvox.extensions.voicemailAccess.getInfo - Retrieve information about a voicemail extension
switchvox.extensions.voicemailAccess.remove - Remove a voicemail extension
switchvox.extensions.voicemailAccess.update - Update a voicemail extension

Extension Groups

switchvox.extensionGroups.getList - Returns a list of all extension groups on the system.
switchvox.extensionGroups.remove - Remove an extension group.
switchvox.extensionGroups.members.add - Add members to an extension group.
switchvox.extensionGroups.members.update - Update the position of members within a group.
switchvox.extensionGroups.members.remove - Remove members from an extension group.

Call Reports, Queue Reports, Queue Logs

switchvox.callReports.did.search - Generate a call report based on incoming DID specific search parameters.
switchvox.callQueueLogs.search - Generate a call queue log based on search parameters.
switchvox.callQueueMemberLogs.search - Generate a call queue member log based on the report parameters.
switchvox.callQueueMissedCalls.getList - Get a list of missed calls based on call uniqueid.
switchvox.callQueueReports.search - Generate a call queue report based on specific search parameters.
switchvox.callQueueMemberReports.search - Generate a call queue member report based on specific search parameters.
switchvox.callQueues.getCurrentStatus - Get a list of all members of a queue and their current status. Also get a listing of all the current callers waiting in the queue and their current status.

Outgoing Call Rules

switchvox.outgoingCallRules.getList - Returns a list of outgoing call rules available in the system.‭
switchvox.outgoingCallRules.getInfo - Returns detailed information about a specific call rule.
switchvox.outgoingCallRules.add - Adds new outgoing call rule.
switchvox.outgoingCallRules.update - Updates existing outgoing call rule.
switchvox.outgoingCallRules.remove - Removes an existing call rule.
switchvox.outgoingCallRules.checkConflicts - Check for any conflicts with the PBX that a new call rule may create.
switchvox.outgoingCallDiagnostics.update - Updates the outgoing call diagnostic field.
switchvox.outgoingCallDiagnostics.getInfo - Returns outgoing call diagnostic value.
switchvox.outgoingCallerIdRules.add - Add new caller id rule.
switchvox.outgoingCallerIdRules.update - Updates caller id rule.
switchvox.outgoingCallerIdRules.remove - Deletes a caller id rule.
switchvox.outgoingCallerIdRules.getList - Returns a list of all existing caller id rules.
switchvox.outgoingCallerIdRules.getInfo - Returns information about a particular caller id rule.
switchvox.outgoingCallerIdRules.search - Returns information about caller id rules based on criteria entered.

Incoming DID Routes

switchvox.incomingDidRoutes.add - Add new incoming DID route.
switchvox.incomingDidRoutes.update - Updates an existing incoming DID route.
switchvox.incomingDidRoutes.remove - Deletes an existing DID route.
switchvox.incomingDidRoutes.getList - Returns a list of all existing incoming DID routes.
switchvox.incomingDidRoutes.getInfo - Returns information about a particular incoming DID route.
switchvox.incomingDidRoutes.search - Returns information about incoming DID routes based on criteria entered.

System Status

switchvox.status.voipProviders.getList - Returns a list of voip providers and their registration status.
switchvox.status.phones.getList - Returns a list of all phones and their registration status.
switchvox.status.telephonyCards.getList - Returns a list of devices and the status of each device channel.

System Settings

switchvox.systemClock.getInfo - Returns the current time and timezone of the PBX.
switchvox.diskUsage.getInfo - Gets disk usage information.

Swithvox Updates

switchvox.updates.getRenewalDate - Gets the subscription expiration date.
switchvox.updates.download - Download an available update
switchvox.updates.apply - Apply a downloaded update

Phone Configuration

switchvox.phoneSetup.phones.update - Update a phone
switchvox.phoneSetup.phones.bulk.update - Update the state of a list of phones
switchvox.phoneSetup.phones.reboot - Reboot one or more phones
switchvox.phoneSetup.phones.configured.additionalLines.getList - Gets a list of additional lines for a configured phone.
switchvox.phoneSetup.phones.configured.additionalLines.update - Update an additional line for a configured phone.
switchvox.phoneSetup.options.getInfo - Gets all the advanced phone setup options.
switchvox.phoneSetup.options.update - Updates the advanced phone setup options.

Scheduled Call, Queue, and Queue Member Reporting

switchvox.scheduler.add - Creates a recurring schedule.
switchvox.scheduler.getInfo - Gets information about a previously created schedule.
switchvox.scheduler.update - Update a recurring schedule.
switchvox.scheduler.remove - Remove a schedule.
switchvox.scheduledReports.callReports.add - Creates a scheduled call report using a predefined schedule.
switchvox.scheduledReports.callReports.getInfo - Gets information about a previously created scheduled call report.
switchvox.scheduledReports.callReports.getList - Get a list of all scheduled call reports on the PBX.
switchvox.scheduledReports.callReports.update - Update a scheduled call report.
switchvox.scheduledReports.callReports.remove - Remove a scheduled call report.
switchvox.scheduledReports.queueReports.add - Creates a scheduled queue report using a predefined schedule.
switchvox.scheduledReports.queueReports.getInfo - Gets information about a previously created scheduled queue report.
switchvox.scheduledReports.queueReports.getList - Get a list of all scheduled queue reports on the PBX.
switchvox.scheduledReports.queueReports.update - Update a scheduled queue report.
switchvox.scheduledReports.queueReports.remove - Remove a scheduled queue report.
switchvox.scheduledReports.queueMemberReports.add - Creates a scheduled queue member report using a predefined schedule.
switchvox.scheduledReports.queueMemberReports.getInfo - Gets information about a previously created scheduled queue member report.
switchvox.scheduledReports.queueMemberReports.getList - Get a list of all scheduled queue member reports on the PBX.
switchvox.scheduledReports.queueMemberReports.update - Update a scheduled queue member report.
switchvox.scheduledReports.queueMemberReports.remove - Remove a scheduled queue member report.

Parking Lots Get List

switchvox.parkingLots.getList - Get a list of all currently parked calls

Call Recordings

switchvox.callRecordings.settings.getInfo - Get settings related to call recordings
switchvox.callRecordings.settings.update - Update settings related to call recordings
switchvox.callRecordings.scheduledRecordings.getList - Get a list of schedules used to record calls
switchvox.callRecordings.scheduledRecordings.add - Add a new schedule to record calls
switchvox.callRecordings.scheduledRecordings.update - Update a schedule used to record calls
switchvox.callRecordings.scheduledRecordings.remove - Remove a schedule used to record calls
switchvox.callRecordings.recordedCalls.remove - Remove a recorded call

Admin Converged Devices

switchvox.convergedDevices.search - Find out if a number passed in belongs to a converged device
switchvox.convergedDevices.getList - Get a list of all converged devices on the system

Admin Account Management

switchvox.admins.getList - Return a list of all admin accounts in the system.
switchvox.admins.getInfo - Retrieve information about an admin account.
switchvox.admins.add - Create a new admin account.
switchvox.admins.update - Update an admin account.
switchvox.admins.remove - Remove an admin account.
switchvox.admins.accessPermissions.getInfo - Retrieve the list of access permissions associated with an admin account.
switchvox.admins.accessPermissions.update - Update the access permissions associated with an admin account.

Backups

switchvox.backups.directories.getList - Get a list and info about all the directories available for backing up
switchvox.backups.directories.getInfo - Retrieves all information of specific directory, including size

User Settings

switchvox.users.cookies.getPassword - This method fetches the token that can be set in the Cookie header of HTTPS requests for authentication. Cookie authentications is a lighter weight alternative to digest authentication on every request.
switchvox.users.timezone.getInfo - Fetches the timezone / current time information for a user.
switchvox.users.localization.update - Updates the localization setting for a user.
switchvox.users.phones.reboot - Reboot phones belonging to the user
switchvox.users.distinctiveRing.tones.update - Update a ringtone already in user’s ringtone library

User Converged Devices

switchvox.users.convergedDevices.getList - Get a list of your converged devices.
switchvox.users.convergedDevices.add - Add a converged device.
switchvox.users.convergedDevices.update - Update a converged device.
switchvox.users.convergedDevices.remove - Remove a
switchvox.users.convergedDevices.authorize -
switchvox.users.convergedDevices.deauthorize -
switchvox.users.extensionGroups.getList - Get a list of user viewable extension groups.

Build a Parent Notifier using the Extend API

Aaron Daniel — 2010年5月28日 19:53:18 +0000

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:



 
 
 
 
 ATE_SSS_AbsentPeriod
 2
 
 
 ATE_SSS_TotalAbsences
 3
 
 
 ATE_SSS_Suspended
 yes

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 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

]]>

Monitoring Switchvox with SNMP and Zabbix

Larry Gilbert — 2010年5月04日 19:11:49 +0000

Switchvox SMB 4.5 introduces the ability to expose the PBX’s operational data with the Simple Network Management Protocol (SNMP). Now you can keep tabs on your Switchvox along with other devices on your network in a single SNMP monitor.

In this post I’ll give you some quick examples of things you can do with this. Here at Digium’s San Diego office we use Zabbix 1.8.2, but the principles are the same for any network monitor capable of working with SNMP.

Step One : Switchvox SNMP Settings

Before starting in on Zabbix, you’ll need to make a couple of changes on your Switchvox to allow access to SNMP without throwing it open to the whole world.

Network Settings

First, go under Machine Admin to the Network Settings panel. Look for the SNMP settings there. These are all security settings for authorization. At the very least you should set the community name to a secret string. If you use a non-Zabbix monitor that supports SNMPv3, also set the user name and password to something secure; SNMP versions 1 and 2c do not use the name and password.

Highlighted: the SNMP community name field

SNMPv3 is recommended as it is much more secure than older versions. However, you may need to use the older versions if you have good reason. In the case of Zabbix, it has a known bug with SNMPv3 waiting to be fixed at this writing. For the sake of demonstration, we choose to use SNMPv2c here. Caution: don’t forget that changing your network settings drops any active calls.

Access Control

Next, look under Machine Admin again for Access Control. Here, set Switchvox’s internal firewall to allow SNMP access from your monitoring host.

Switchvox's access control page; the SNMP setting is highlighted

Step Two : Zabbix monitoring of Switchvox calls

Now that that’s done, we’re ready to have some fun. One metric you might be interested in tracking is the number of phone calls being handled at any given time (it’s a phone system, after all).

Adding a host entry to Zabbix

Go to Configuration / Hosts and click “Create Hosts.” The most important things here are the Switchvox’s IP address and domain name. You need to enter at least one or the other, but you can enter both. Zabbix will use whichever you tell it to use.

Creating a host entry in Zabbix

Add the first item: Number of current calls

We’ll need to look up the “SNMP Settings” section in the Switchvox Administrator Manual, examine the items listed there, and find the object ID (OID) for the item we want to track. Here we find the OID for total current calls is 1.3.6.1.4.1.22736.10.5.1 (in Zabbix, you don’t need to enter the leading dot). Let’s create an item for that. Under Configuration / Hosts, set the drop-down menu on the right to “Items” and click “Create Item.”

Details of Zabbix's "Create Item" screen

Most of the defaults provided by Zabbix are reasonable for this (you may have to select your new host if it’s not showing in the host field). You can enter whatever you want for a description. But to enter the appropriate fields for SNMP, we’ll need to change the type to “SNMPv2 agent” first. Then we can fill in the OID as well as the community name we set on the Switchvox. We’ll enter a key name of “swvxCurrentCallsTotal”, which is just an arbitrary handle to use if we want to use this item in calculations later. Finally, we fill in the “new application” field with “Phone calls”; this is a name (arbitrary, again) that will help us organize monitored items, as we’ll see below.

After filling in values for the new item

Check your work

Once saved, Zabbix should begin reading and tracking this value immediately. But first you might want to make sure that SNMP is working in general. You should be back on the Configuration / Hosts page, so choose “Hosts” in the drop-down menu, look for the Switchvox’s entry, and look under the “Availability” column. Among the status indicators there, you should see the SNMP indicator highlighted in green. If it’s gray, wait a bit longer since there might not have been an update since you added the item. If it’s red, the SNMP check is not working; go back to the Switchvox admin pages and verify that you’ve used the correct community name and opened access to SNMP under Access Control. If it’s green, all is well.

The host configuration screen, showing that SNMP is available on the Switchvox

Now if you go to the Monitoring / Latest Data page and look up the Switchvox, you should see the number of calls for the moment and the last time there was an update for that item. (Also, now you can see how the name “Phone calls” is used.)

"Latest data" view of the new item

Step Three : Zabbix monitoring of VOIP providers

Another item that would be good to track is the status of VOIP providers–you’ll want to know if any of them go down (especially if you have only one).

Add a new item

Look at the list of Switchvox OIDs in the manual and under “VOIP Providers” you’ll see an item for the number of providers in an “OK” state. (Later we’ll see how to keep an eye on this value for changes.) The OID to use is 1.3.6.1.4.1.22736.10.2.2.

Adding an item for VOIP providers

In the same subsection, you’ll see that you can even monitor individual providers if you want. (You can do that on your own time; we have only so much space here.)

Check your work

Go back to Monitoring / Latest Data and you should see both items now. If you wait a minute or two and you still don’t see the new one, go back and make sure you used the correct SNMP community name (usually the lack of new data is the only clue you’ll get that the community name is wrong).

Both new items in the "Latest data" view

Step Four : Monitoring system resources

We can also monitor general system resources such as memory and hard disk space. There are a couple of ways to get at data for these. Switchvox provides its own set of values, as detailed in the list of Switchvox OIDs for “Hardware Status” in the admin manual. It also provides values from the “iso.org.dod.internet.private.enterprises.ucdavis” tree (here’s a handy reference courtesy of ByteSphere Technologies). If up-to-the-minute data is important to you, you should use the latter, as the Switchvox values are a snapshot taken only once every 10 minutes. For the purposes of this tutorial, though, we will go ahead and use the Switchvox values.

Add items for memory and hard disk usage

Let’s add items for used memory and hard disk space, starting with the memory. As the admin manual says, the OID is 1.3.6.1.4.1.22736.10.3.1.1. Now things get a little different. We enter “B” for units to indicate bytes; this is a magic value that tells Zabbix to automatically scale the values to kilobytes, megabytes, etc. as needed. Then we need to enter a custom multiplier of 1024 because the values reported via SNMP are in fact kilobytes; otherwise the values stored will be too small. Switchvox only updates these values once every 10 minutes, so there’s no need to set the update interval to be shorter than 600 seconds.

Adding the new item for used memory

Add an item for CPU load

One other useful value is the CPU load (again, Switchvox’s version of this value updates only once every 10 minutes). Here too we have to do something a little differently: since the value can have up to two decimal places, the type has to be set to “Numeric (float).” Otherwise, Zabbix will reject the item as “not supported” since it can’t store a floating-point number as an integer.

Entering new item for CPU load

Step Five : Raising alarms with triggers

We’ve got some good data to look at and to analyze with fancy graphs (the Zabbix graphs are another exercise for the reader). But it would be nice to use these in a way that will actively warn us if there is a problem. In Zabbix, this is where triggers come in. A trigger simply watches for specific values or specific kinds of changes in values, then fires off an action such as sending an e-mail if and when this happens.

Beginning a new trigger: VOIP provider failure

For a PBX, a useful trigger would be in the event of one or more VOIP providers failing. We can base the trigger on the value of the “total OK providers” item we defined earlier falling below a defined level.

To begin, go to the Configuration / Hosts page, look for the entry for your Switchvox, and hit its “Triggers” link to take you to its triggers page. Click the “Create Trigger” button in the upper right corner to get a new form for creating a trigger. Go ahead and enter a name for it now.

The trigger creation screen

Set the condition for firing the trigger

Zabbix has an easy method for choosing the expression to evaluate in a trigger; we can reach it by hitting “Select” next to the expression field.

Creating a new trigger condition

For the item, we hit “Select” and get a new window with the list of items we’ve defined. We choose “Number of providers OK” from the list. Looking at the drop-down menu for “Function,” we have a dizzying array of choices, but for our purpose, the simplest is the best: just watch for the number of OK values to fall below a certain number. Choose “Last value < N” for the function, then enter the minimum number of OK providers in the field for N. (You can enter the actual number you want to watch for, or if you want to experiment and intentionally set off the trigger, you can enter an inflated number here.)

The completed condition information

Wrap up the new trigger

Hit “Insert” to save the condition. Why is it “Insert”? Because in reality we can define more than one condition for a trigger–although we don’t need to here. We can just skip down to “Severity” and set it to reflect the seriousness of the situation in the trigger. There’s no need to touch anything else right now.

The completed trigger screen

Check your work

Once we’ve saved this, we have our first trigger. We can look it up under Monitoring / Triggers now. If the limit defined above is the real-life number we want to watch for, the status will say “OK” and the severity will show up with a green background (even if it is a high severity). If you took the suggestion of setting the limit intentionally too high, you should see the word “PROBLEM” in red, blinking. (There is a third status, “UNKNOWN”, that shows up in gray at times when Zabbix is unable to get a current value.)

The new trigger on the trigger monitoring page

Zabbix will also let you define an action to be taken when a trigger is fired–for example, sending an e-mail or instant message, or executing a command.

We’ve barely scratched the surface of what can be done with Zabbix monitoring in this article. But the basics shown here, together with the the Zabbix documentation and the list of SNMP OIDs in the Switchvox admin manual, should give you a good springboard for developing a complete panel of things to monitor to keep your PBX running smoothly and give you early warning of trouble so you can spot it before your phone users do.

]]>

Ruby Interface for the Switchvox Extend API

David Podolsky — 2010年4月23日 22:34:12 +0000

If you love to program in Ruby, then you are in luck because a community developer just released a RubyGem for interacting with the Switchvox API. Its 100% ruby and it only has one gem dependency (json).

You can download the library and read the forum post from our Client Libraries Page

If you’re familiar with Ruby but would like to work in another language, you still might like to check out the Ruby API so that you can quickly duplicate it in that other language. If you write a client library in a language that we don’t already have available, please tell us about it.

]]>

4.5 Released - Over 60 new Switchvox API Calls

David Podolsky — 2010年1月28日 18:14:29 +0000

I hope everyone is enjoying all the new features that came out in 4.5 last week. Along with all the new features, came a bunch of new API calls that our developers can take advantage of for developing cool integrations with Switchvox. Below is a list of over 60 new API calls and descriptions of what they do. For more information on each call just visit our Developers Wiki for descriptions and example XML requests and responses for each method.

Extensions

switchvox.extensions.phones.sip.add - Create a SIP extension.
switchvox.extensions.phones.sip.update - Update a SIP extension.
switchvox.extensions.phones.virtual.add - Create a virtual extension.
switchvox.extensions.phones.virtual.update - Update a virtual extension.
switchvox.extensions.getVoicemailInfo - Gets the voicemail/fax disk usage information for every phone extension.
switchvox.extensions.phones.attachImage - Attach a profile image to an extension.

Extension Groups

switchvox.extensionGroups.getInfo - Get extension group information and a list of extensions it contains.
switchvox.extensionGroups.add - Add a new extension group.
switchvox.extensionGroups.update - Update an extension group.
switchvox.extensionGroups.remove - Remove an extension group.

Current Calls

switchvox.currentCalls.getList - Returns a list of all in-progress calls on the system.
switchvox.currentCalls.hangUp - Hangs up the specified call.

SNMP Settings

switchvox.snmpSettings.getInfo - Get the SNMP settings
switchvox.snmpSettings.update - Change the SNMP settings

Phone Configuration

switchvox.phoneSetup.phones.getList - Gets a list of all phones
switchvox.phoneSetup.phones.reboot - Reboot one or more phones
switchvox.phoneSetup.phones.configured.additionalLines.getList - Gets a list of additional lines for a configured phone.
switchvox.phoneSetup.phones.configured.additionalLines.update - Update an additional line for a configured phone.

IVR Distinctive Ring Hints

switchvox.ivr.distinctiveRingHints.getList - Get all IVR distinctive ring hints.
switchvox.ivr.distinctiveRingHints.add - Adds an IVR distinctive ring hint.
switchvox.ivr.distinctiveRingHints.remove - Removes an IVR distinctive ring hint.

New Call Creation Settings

switchvox.call - Creates a call in the system between two extensions or external numbers.

Localization

switchvox.localization.getInfo - Gets the localization setting for an admin.
switchvox.localization.update - Updates the localization setting for an admin.

Distinctive Ringing

switchvox.distinctiveRing.tones.add - Upload and add a WAV to the admin’s (system-wide) ringtone library
switchvox.distinctiveRing.tones.getFile - Get the URL of a ringtone from the admin’s library
switchvox.distinctiveRing.tones.getList - List all available ringtones in the admin’s library
switchvox.distinctiveRing.tones.remove - Remove a ringtone from the admin’s library
switchvox.distinctiveRing.tones.update - Update a ringtone already in the admin’s library

Profile Images

switchvox.images.add - Upload an image.
switchvox.images.getFile - Gets a list of URLs to where you can download various sizes of the image.
switchvox.images.remove - Delete an image and remove any references to it.
switchvox.images.updateCrop - Update the cropping of an image.

Realtime Parking Lot Information

switchvox.parkingLots.getList - Get a list of all currently parked calls

User Localization

switchvox.users.timezone.getInfo - Fetches the timezone / current time information for a user.
switchvox.users.localization.getInfo - Gets the localization setting for a user.
switchvox.users.localization.update - Updates the localization setting for a user.

User Phones

switchvox.users.phones.getList - Gets a list of all phones belonging to the user
switchvox.users.phones.reboot - Reboot phones belonging to the user

User Phonebooks

switchvox.users.phonebooks.getList - Gets the list of phonebooks for a user.
switchvox.users.phonebooks.getInfo - Get the details and entries for a phonebook
switchvox.users.phonebooks.entry.getInfo - Get the details of a single phonebook entry

User Profile Images

switchvox.users.profile.images.add - Upload a new profile image.
switchvox.users.profile.images.attach - Attach a profile image to an account.
switchvox.users.profile.images.getFile - Retrieve a list of URLs for the different sizes of the image.
switchvox.users.profile.images.remove - Delete a profile image and remove references to it.
switchvox.users.profile.images.updateCrop - Update the cropping of a profile image.

User Phone Configuration Options

switchvox.users.phoneOptions.getInfo - Gets the phone options for a user.
switchvox.users.phoneOptions.update - Updates a users phone options.

User Realtime Current Calls

switchvox.users.currentCalls.getList - Gets a list of current calls for a user
switchvox.users.currentCalls.startRecording - Record a call
switchvox.users.currentCalls.stopRecording - stop recording a call

User Distinctive Ringing

switchvox.users.distinctiveRing.rules.getList - Get a list of all rules and conditions for a specific account.
switchvox.users.distinctiveRing.rules.add - Begin adding a distinctive ring rule
switchvox.users.distinctiveRing.rules.update - Make changes to an existing distinctive ring rule
switchvox.users.distinctiveRing.rules.remove - Remove an existing distinctive ring rule
switchvox.users.distinctiveRing.rules.conditions.add - Add a condition to a specific rule.
switchvox.users.distinctiveRing.rules.conditions.update - Update a condition.
switchvox.users.distinctiveRing.rules.conditions.remove - Remove a condition.
switchvox.users.distinctiveRing.tones.add - Upload and add a WAV to user’s ringtone library
switchvox.users.distinctiveRing.tones.getFile - Get the URL of a ringtone from the user’s or admin’s library

]]>

Making Batch Requests with the Extend API

David Podolsky — 2009年7月29日 20:28:07 +0000

Introduced in version 18313 of the Switchvox SMB 4.0 Product is support for performing batch requests through the Extend API Core Methods. Many times developers will need to make multiple requests through the Extend API and don’t want to incur the latency of separate HTTP requests for every API method. This is where batch requests come into play. Developers can now include multiple requests into one large batch request and submit that to the Extend API and receive one batch response.

Ok enough theory, time for a real world example.

Say you are a developer and your company has asked you to get some information off the PBX for an extension. This information needs to include: Any extra numbers in an extension’s profile, the call logs for the past two days for an extension, and a list of an extension’s call rule sets.

Without batched requests, this would be 3 separate calls to these Extend API Core Methods:
switchvox.users.profile.extraNumbers.getList
switchvox.users.callLogs.search
switchvox.users.callRuleSets.getList

With batched requests you can include them into one call like this:


 
 
 1004
 
 
 
 
 2009年7月28日 00:00:00
 2009年07月29日 23:59:59
 1004
 
 
 
 
 unanswered
 1004

Then your response might look something like this:

There you have it. 3 requests packed into 1.

]]>

About Versions for API Methods

Justine Witt — 2009年6月01日 18:56:42 +0000

Future changes to the Switchvox software will include changes and additions to the Extend API. To minimize the impact those changes could have on your integrated applications, we have added a version number to each API method. If a Switchvox software update includes significant changes to an API method, such as new required parameters or different attribute names, we will make those changes available in a new version of the method. That way, if your methods indicate a version number then you can feel free to update your Switchvox software, secure in the knowledge that your apps will continue to function normally until you have a chance to update your code to the new version of the API.

We’ve assigned a first version number to each method: 17487. Although this is the only version right now, we encourage you to include it in your API requests. To indicate the version, use the ‘version’ attribute of the request tag (just like you do with the method itself). Here’s an example:



 100
 200

(We will be updating the information and code across Developer Central to reflect this change to the request tag.)

If you do not indicate a version number, the latest version available is used.
If you indicate a version number that does not match a version number for that method, the closest earlier version is used. This lets you use one version number across all of your requests.
If we make a minor change to an API method, such as adding a new optional parameter, we will include those changes in the existing version of the method. That means that minor changes will be automatically included when you update your Switchvox software. As much as possible, we will try to create a new version of a method if our changes will mean that you have to change your code.

]]>