User Tools

Site Tools


foxbox_api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

foxbox_api [2016/06/14 18:35] (current)
Line 1: Line 1:
 +===== 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 [[http://​www.smsfoxbox.it/​en/​contacts|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 [[http://​www.w3schools.com/​tags/​ref_urlencode.asp|URL encoding]] constraints).
 +\\ All you need to do is passing these values from your application:​
 +  * //​username//:​ one of the users registered in your FoxBox;
 +  * //pwd//: the password of that user;
 +  * //from//: name of the sender (by default, same as //​username//​);​
 +  * //nphone//: the phone number to whom you are sending;
 +  * //testo//: the content of your SMS message.
 +
 +As an example, please analyze the following URL exploiting the Get method:
 +<​code>​
 +http://​FOXBOX_IP_ADDR/​source/​send_sms.php?​username=Admin&​pwd=XYZ123&​from=Davide&​nphone=393401122333&​testo=SMS%20%text
 +</​code>​
 +
 +As an alternative,​ you can use the Post:
 +<​code>​
 +[...]
 +    $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);
 +[...]
 +</​code>​
 +
 +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:
 +<​code>​
 +http://​FOXBOX_IP_ADDR/​source/​send_sms.php?​username=Admin&​pwd=XYZ123&​from=Davide&​nphone=393401122333&​outCh=GSMx&​testo=SMS%20%text
 +</​code>​
 +
 +: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:
 +  * Generate an outgoing SMS, containing the body of an email (loaded from a given mailbox);
 +  * Forward an incoming SMS as a new email.
 +
 +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 [[mailtosms_group|MAILtoSMSgroup]] and [[mailtosms_multi|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|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 //:
 +<​code>​
 +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; ​
 +
 +</​code>​
 +
 +Now, you just have to call this function posting the parameters you need:
 +<​code>​
 +$urlPost='​http://​SRV_IP_ADDR/​webservice.xyz'; ​
 +$params='​PHONE='​.urlencode($nmit).'&​smsTEXT='​.urlencode($testo).'&​smsDATE='​.urlencode($ricevuto); ​
 +$response=do_post_request($urlPost,​ $params);
 +</​code>​
 +
 +Lastly, on your Web server probably you will need to generate a procedure similar to this one:
 +<​code>​
 +<?
 +    $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'"​)"​);​
 +?>
 +</​code>​
 +
 +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:​
 +<​code>​
 +#UNCOMMENT THIS LINES TO ACTIVATE MYSMS MODULE (MYSQL CLIENT)
 +if [ "​$1"​ = "​RECEIVED"​ ]; then
 +    /​etc/​sms/​scripts/​mysql_parser.php
 +fi
 +</​code> ​
 +
 +This feature is configurable from FoxBox Web interface, in the menu "MySQL Module"​. The parameters you have to set are:
 +  * //MySQL socket// listening on the default port of your server, with permissions to accept incoming connection from the FoxBox IP ([[http://​dev.mysql.com/​doc/​refman/​5.0/​en/​connection-access.html|read more]]);
 +  * //​IP/​hostname//​ of your MySQL Server;
 +  * //User// able to access the tables with enough permissions to perform SELECT, INSERT, etc.;
 +  * //​Password//​ for the user, remember to verify password style ([[http://​dev.mysql.com/​doc/​refman/​5.0/​en/​old-client.html|read more]]);
 +  * //Name of the database// where we have to perform the queries.
 +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:
 +  * Customized sender (numeric or alphanumeric);​
 +  * Concatenated SMS, up to 1836 characters long;
 +  * Free delivery notification;​
 +  * Transmission rate up to 100 SMS/sec;
 +  * SSL encryption for safe communications;​
 +  * No activation costs.
 +
 +More informations are available at [[http://​sms.kdev.it|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: ​
 +<​code>​
 +#Save messages in XML format
 +if [ "​$1"​ = "​RECEIVED"​ ]; then
 +    /​etc/​sms/​scripts/​sms2xml $1 $2 $3
 +fi
 +</​code>​
 +
 +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:
 +<​code>​
 +390123456789
 +Body of the message
 +</​code>​
 +
 +:id1: Existing implementations of this logic can be found for [[asp.net_intergration|ASP.NET]] and [[flash_intergration|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:
 +  * [[nagios_integration|Nagios/​Icinga]] (visit [[http://​nagios.org/​|here]] or [[https://​www.icinga.org/​|here]] for more informations)
 +  * [[prtg_integration|PRTG Network Monitor]] (visit [[http://​www.paessler.com/​prtg|here]] for more informations)
 +  * [[zabbix_integration|Zabbix]] (visit [[http://​www.zabbix.com/​index.php|here]] for more informations)
foxbox_api.txt ยท Last modified: 2016/06/14 18:35 (external edit)