OSCT Project - The Automated Phone Assistant - Part 1
Saturday, April 7th, 2007 5:20 pm | Articles, Contributions, Development
RSS Feed
Digg This
In this post, I stated my intentions to make an automated phone assistant for osCommerce, promising to update you on any developments.
Well, I’ve been playing over the last week and managed to get all three services outlined in that post working.
Today, I’ll discuss how I implemented the first of those services:
You call a telephone number and an automated response tells you how many pending orders you have and how much they are worth.
You can listen to an example call by clicking the icon below.
A word of warning
Please bear in mind that I will only provide a rough guide to setting up this service. It would be impossible to provide all the details as there are many possible configurations.
Don’t let that put you off trying this project. If you are relatively computer literate, you should be able to achieve it.
The Service Architecture Overview
There are two main components in this system.
The web server - your normal osCommerce store runs on this. In addition we are going to write several web service scripts (PHP files that echo data) to provide data to our telephony server.
The telephony server - this server sits in your house and handles incoming and outgoing calls. When a call is received, it runs a PHP script that retreives data from your osCommerce web service. The received data is parsed, formatted and eventually spoken back to the caller.
A telephony server? In my house!?
So now you’re thinking, “How the hell do I setup a telephony server in my home?”. Sounds complicated, doesn’t it? Luckily, some clever folks have done all the hard work for us by creating Asterisk.
Asterisk is an extremely powerful open source PBX toolkit. It’s used in small offices with a handful of employees to large call centres. And even better, it has a PHP interface, meaning it can execute PHP scripts during calls. This is how we access the osCommerce web service.
However, Asterisk runs on Linux and is complicated to setup.
That’s where trixbox comes in.
Trixbox overview and installation
trixbox is a collection of software needed to make Asterisk run. It includes CentOS (the server’s operating system) and other handy tools such as PHP, mySQL, SSH and a web server.
Without trixbox we would have to manually install Linux, then compile and install Asterisk, then make sure the firewall has properly configured, then add a web server, then setup PHP, etc., which would take forever.
With trixbox you put a CD into the tray, reboot the machine, and sit back as it does its thing in under 30 minutes. It really is that easy.
Head to trixbox.org, download a copy and burn it to a CD. I got the trixbox 2.0 ISO.
Then head to TRIXBOX Without Tears and follow the installation guide.
NOTE: Installing trixbox ERASES everything on the machine. Don’t install it on your main machine and then complain when you can’t access Microsoft Windows anymore!
I installed trixbox on an old 700MHz machine I picked up for £50. It’s more than sufficient for the job.
When you have trixbox installed, come back here.
Creating an Asterisk dialplan
Dialplans are the logic used to determine how a call is handled. We are going to add a dialplan that will accept any call placed to our osCommerce store checker number, and provide the caller with pending order information.
Open a browser and enter the URL of your trixbox server (mine is statically set to 192.168.1.100 on my local network). The trixbox web page should load. Open the Config Edit tool and select the extensions_custom.conf file.
In the [from-internal-custom] section, add the following line:
exten => 112,1,Goto(store-pending-orders-check,s,1)
This line reads as follows: Send all calls received on extension 112 to line s,1 of the [store-pending-orders-check] routine.
Now add another section to the extensions_custom.conf file:
[store-pending-orders-check]
; checks the number of pending orders and total value
exten => s,1,Wait(5)
exten => s,2,Answer()
exten => s,3,Wait(1)
exten => s,4,Playback(welcome)
exten => s,5,Authenticate(1234)
exten => s,6,Playback(pls-hold-while-try)
exten => s,7,Ringing()
exten => s,8,AGI(custom/phpagi_wrapper.php,osc-orders-pending)
exten => s,9,Playback(vm-youhave)
exten => s,10,SayNumber(${NUM_ORDERS},f)
exten => s,11,Playback(orders)
exten => s,12,Flite(’Total value is’);
exten => s,13,SayNumber(${POUNDS},f)
exten => s,14,Playback(pounds);
exten => s,15,Playback(and);
exten => s,16,SayNumber(${PENCE},f)
exten => s,17,Playback(pence)
exten => s,18,Playback(thank-you-for-calling)
exten => s,19,Hangup()
Here’s a run through of this code.
- s1-s3 answers the call.
- s4-s5 asks the user to enter a PIN (in this case 1234).
- s6-s7 reads the user a message which says ‘Please wait’ and then starts a ringing tone.
- s8 calls a PHP script. This script accesses the osCommerce web service and retreives order information. The script also sets the values of variables NUM_ORDERS, POUNDS and PENCE.
- s9-18 reads the caller a message which says ‘You have X orders. Total value is Y pounds and Z pence’.
- s19 hangs up the call.
Forwarding calls to extension 112
Unless you are calling from an extension within your network, you will not be able to call extension 112 directly. We want to be able to call one telephone number and have the call directed automatically to extension 112.
To do this, create a new extension in FreePBX with number 501. Using a softphone (e.g. X-Lite), dial *72, then enter 501, then enter 112. This means whenever you dial extension 501, your call is forwarded to extension 112.
Now create an inbound route that connects any incoming call to extension 501. Again, this can be done in FreePBX. Refer to TRIXBOX Without Tears for assistance if needed.
With that done, let’s write the PHP script that is called by this dialplan.
The orders pending PHP script
The main work is done by the PHP script below. In order to make it work, you will need to upload the provided files to the /var/lib/asterisk/agi-bin directory on your trixbox server. This directory is where Asterisk looks for AGI scripts.
Download the full set of scripts here.
<?php
// The URL of your order data service
// Remember to include your username and password if .httpd is
// enabled on your server.
$service_url = "https://USERNAME:PASSWORD@www.yourdomain.com/admin/service_pending_orders.php";
//=====================
// Functions
//=====================
// Connect to the remote service and lookup
// order information
function access_service($url) {
$fd = fopen($url, "r");
if (!$fd) {
echo "Unable to open web connection.n";
exit;
}
$value = "";
while(!feof($fd)){
$value .= fread($fd, 4096);
}
fclose($fd);
return $value;
}
// Parse the CSV order data into an array.
function parse_data($data) {
$order_info = explode("|", $data);
return $order_info;
}
//=====================
// Main program starts
//=====================
$num_orders = "0";
$pounds = "0";
$pence = "0";
// Get the data from our web service
$order_data = access_service($service_url);
// Parse the data
$info = parse_data($order_data);
// Set Asterisk channel variables so we can
// access them within the Dialplan
$agiWrapper->set_variable("NUM_ORDERS", $info[0]);
$agiWrapper->set_variable("POUNDS", $info[1]);
$agiWrapper->set_variable("PENCE", $info[2]);
?>
The script calls your web service and retrieves the number of pending orders and their total value. This data is then injected back into the dialplan in the form of three variables; NUM_ORDERS, POUNDS and PENCE.
The osCommerce web service script
Now let’s cover the final part, the script that resides on your osCommerce web server. This script accesses the mySQL store database, retreives information about pending orders, and then outputs the info in CSV format (using the pipe symbol as a delimiter).
<?php
define(‘DB_USERNAME’, ‘myUsername’);
define(‘DB_PASSWORD’, ‘myPassword’);
define(‘DB_DATABASE’, ‘myDB’);
define(‘DB_SERVER’, ‘myServer’);
$db_link = mysql_connect(DB_SERVER, DB_USERNAME, DB_PASSWORD)
or die("Unable to connect to database");
$selected = mysql_select_db(DB_DATABASE, $db_link)
or die("Unable to connect to table oscommerce");
$query = "select o.orders_id, ot.value from orders o, orders_total ot where o.orders_id=ot.orders_id and o.orders_status=’1′ and ot.class=’ot_total’";
$orders_result = mysql_query($query);
$grand_total = 0;
$num_orders = mysql_num_rows($orders_result);
while($row = mysql_fetch_array($orders_result)) {
$grand_total = $row[‘value’];
}
// Split into pounds and pence
$money[0] = 0;
$money[1] = 0;
if ($num_orders > 0) {
$money = explode(".", $grand_total);
}
// Print
echo "$num_orders|" . $money[0] . "|" . $money[1];
?>
Save this script as service_pending_orders.php and upload it to your osCommerce store admin directory. Make sure the $service_url variable in the trixbox PHP script matches the location of this PHP script.
Signing up with a VoIP service provider
If you have completed the steps outlined above, you should be able to pick up an internal phone, dial 501 and hear the status of your osCommerce store.
If you want to call from outside your network, you must sign up for a VoIP service provider. They will convert PSTN (standard phone line) calls into VoIP calls, and then forward them to your trixbox server for processing.
There are a number of these services to choose from. I’ll let you decide which to choose. For testing purposes I am using Sipgate, which gives me a London telephone number and allows me to receive incoming calls for free.
I can call that number from any phone, anywhere in the world, and hear my store assistant.
Conclusion
Outlined above is a rough guide to linking Asterisk and osCommerce to create a weird and wonderful creation.
It is only meant as a start. Once you understand the general concepts, you can begin creating your own telephone services for you and your store customers.
If you have questions or comments about this article, please post them below.
Enjoyed reading this post? Get more delivered directly to you.
Responses
Reply