This shows you the differences between two versions of the page.
— |
foxbox_api [2016/06/14 16: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) |