Table of Contents

FoxBox API

To easily integrate FoxBox within your server environment, we developed several APIs giving you the possibility of sending/receiving messages from everywhere you need.
Here we will list all of them, with an explanation of their usage.

:!: If you are thinking of a solution we didn't implement yet, please contact us, and we will collaborate with you in its implementation.

#1: HTTP Get/Post

The easier way to communicate with your FoxBox, providing the required informations to internal scripts using a simple URL (please consider the URL encoding constraints).
All you need to do is passing these values from your application:

As an example, please analyze the following URL exploiting the Get method: 

http://FOXBOX_IP_ADDR/source/send_sms.php?username=Admin&pwd=XYZ123&from=Davide&nphone=393401122333&testo=SMS%20%text

As an alternative, you can use the Post: 

[...]
    $url='http://FOXBOX_IP_ADDR/source/send_sms.php'; 
    $params='username='.urlencode($usr).'&pwd='.urlencode($pass).'&from='.urlencode($from).'&nphone='.urlencode($num).'&testo='.urlencode($text); 
    $response=do_post_request($url, $params);
[...]

Once executed this procedure will return a confirmation message, and the SMS will be automatically sent in a few seconds.

:id1: It is possible to send an SMS to multiple receivers, separating the phone numbers using the character “;”.

In case you have a FoxBox LX800 Multi16, you can explicitly define the GSM modem to be used (GSM0, GSM1, GSM2, etc.) for sending the message. This is done using the outCh parameter, thus the previous URL becomes: 

http://FOXBOX_IP_ADDR/source/send_sms.php?username=Admin&pwd=XYZ123&from=Davide&nphone=393401122333&outCh=GSMx&testo=SMS%20%text

:id1: To send using the load-balancer over the available modems, set ALL instead of GSMx.

#2: MAILtoSMS and SMStoMAIL features

Respectively, they will enable you to:

These features are both easily configurable from the FoxBox Web interface, menu System Profile.
Once you have properly filled the required fields, the device has all the necessary parameters to automatically handle the forwarding procedures.

:id1: Advanced forwarding features are MAILtoSMSgroup and MAILtoSMSmulti.

#3: FTP/SSH direct connection

For advanced users, we provide the possibility of generating new messages directly on the modem's queues, using the SSH and FTP servers already installed on the device.
When you upload the SMS inside of the folder /mnt/flash/spool/ougoing/ (according to SMS file format), using a client (FileZilla, WinSCP, Cyberduck, etc.) or a Bash command (scp), this will be automatically sent in a few seconds.

#4: POST to Web service

This feature allows you to post your incoming messages to an external Web service, in order to process them on a different machine (maybe with more computational power).

To keep the internal scripts as simple as possibile this feature is not installed by default, but you can easily add it pasting these new lines into the file /etc/sms/scripts/parser.php : 

function do_post_request($url, $data, $optional_headers = null) { 
    $params = array('http' => array( 
        'method' => 'POST', 
        'content' => $data 
    )); 
    if ($optional_headers !== null) { 
        $params['http']['header'] = $optional_headers; 
    } 
    $ctx = stream_context_create($params); 
    $fp = @fopen($url, 'rb', false, $ctx); 
    if (!$fp) { 
        throw new Exception("Problem with $url, $php_errormsg"); 
    } 
    $response = @stream_get_contents($fp); 
    if ($response === false) { 
        throw new Exception("Problem reading data from $url, $php_errormsg"); 
    } 
    return $response; 
}

Now, you just have to call this function posting the parameters you need: 

$urlPost='http://SRV_IP_ADDR/webservice.xyz'; 
$params='PHONE='.urlencode($nmit).'&smsTEXT='.urlencode($testo).'&smsDATE='.urlencode($ricevuto); 
$response=do_post_request($urlPost, $params);

Lastly, on your Web server probably you will need to generate a procedure similar to this one: 

<?
    $sender=$_REQUEST['PHONE'];
    $text=$_REQUEST['smsTEXT'];
    $deldate=$_REQUEST['smsDATE'];
    $db = mysql_connect("localhost", "dbuser", "password");
    if ($db == FALSE)
        die ("Error cannot connect to MYSQL");
    mysql_select_db("SMS", $db);
    $query = mysql_query("insert into incoming values  ('','$sender','$text', '$deldate'")");
?>

Note that you can apply this procedure to every SMS event (received, sent or failed). You can also use this logic with all kinds of Web services, using PHP, ASP, JSP, etc.

#5: MySQL integration

The FoxBox internal database is based on SQLite, a very stable and efficient solution, but if you need to integrate it with your IT architecture that uses MySQL we already have a solution: the MySMS module.

This plugin is already installed, and in order to activate it you need to remove the sharp character (i.e. “#”) from these lines of the internal Eventhandler: 

#UNCOMMENT THIS LINES TO ACTIVATE MYSMS MODULE (MYSQL CLIENT)
if [ "$1" = "RECEIVED" ]; then
    /etc/sms/scripts/mysql_parser.php
fi

This feature is configurable from FoxBox Web interface, in the menu “MySQL Module”. The parameters you have to set are:

Note that you can choose to store messages just on MySQL database, or both. After you finished filling up required fields, click “Save Configuration” to apply changes.

Your MySQL database should contain a table named messages, containing the following fields:
< times,froms,tos,subject,sent,texts >.

#6: Connection to KDEV SMS Gateway

This is the main service of our SMS Gateway division, and it has been fully integrated with FoxBox devices in order to use them as enhanced clients.

The service has been designed for companies, software house, ISP, Web agencies, portals, and every other FoxBox user. The main advantages are:

More informations are available at sms.kdev.it.

#7: Encoding incoming SMS with XML

Here you can see how to export data from a received SMS into a simple XML document. This integration is particularly useful to create an interface between FoxBox and external applications, passing informations via this well known standard.

The XML transformation script is already installed, and it can be easily activated by removing the sharp character (i.e. “#”) from these lines of the internal Eventhandler: 

#Save messages in XML format
if [ "$1" = "RECEIVED" ]; then
    /etc/sms/scripts/sms2xml $1 $2 $3
fi

This code provides the call to sms2xml script for each RECEIVED message, but it can be easily extended to manage also SENT or FAILED ones. Obviously, depending on your IT infrastructure, in some cases you will need to modify the XML file format generated by default, in order to meet the requirements of specific softwares.

If this XML module is active, each time you will receive an SMS it will be stored inside of the file accessible at the address FOXBOX_IP_ADDR/xml/sms.xml .
Its internal format, by default, will be: 

390123456789
Body of the message

:id1: Existing implementations of this logic can be found for ASP.NET and Adobe Flash.

#8: Network monitoring tools

Knowing the importance of always being aware of the current state of your network systems, we developed a set of specific interfaces for the most important network monitoring tools on the market. These will allow you to receive SMS notifications as soon as a relevant event occurs.

Up to now, the list of supported monitoring softwares is: