User Tools

Site Tools


custom_actions

Differences

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

Link to this comparison view

custom_actions [2016/06/14 18:35] (current)
Line 1: Line 1:
 +===== How to execute custom actions on messages =====
 +In this guide we will exploit the flexibility of the FoxBox internal software to define custom actions, that will be executed over a certain subset of incoming or outgoing messages. This allows you to easily customize the internal logic of the device.
 +
 +There are two ways to manage these events:
 +  * Using the Custom Actions tool;
 +  * Coding extensions for the Eventhandler.
 +
 +==== #1: Custom Actions ====
 +You can configure this feature from the Web interface, menu //Custom Application//​. Inside of this window you will find two forms, the first one for actions on incoming messages, and the second for the outgoing ones. 
 +
 +To better explain how this tool works, it is better to create a simple example: a small lottery. ​
 +\\ The operating logic here is that for every SMS message received by our FoxBox and containing a certain numeric code, we want to check if this is the winning one in order to eventually answer with an SMS of congratulations.
 +
 +Obviously, for this application we will need to check the text of each incoming message, and in case we find the message with the winning code we have to extract the sender'​s phone number to deliver the SMS containing the congratulations.
 +
 +A shell script that performs all these actions is listed below:
 +<​code>​
 +#!/bin/sh
 +#This is a sample script for Custom RX Actions
 +#PURPOSE: The script searches a code inside of the incoming message, and if the code is matched replies with the message "You WIN!"
 +#The winning code is: 1223456
 +
 +#We set some useful variable
 +SEARCH="​123456"​
 +TEXT="​You WIN!"
 +
 +#We parse the received message ($1 is the full path to it), to check if it contains the winner code.
 +CODE=`/​bin/​cat $1 | grep "​$SEARCH"​`
 +
 +#If the message content equals exactly the winner code, reply with the message "You WIN!"
 +if [ "​$CODE"​ == "​$SEARCH"​ ]; then
 +    #We need to extract the sender'​s phone number to reply
 +    NUMB=`/​bin/​cat $1 | /bin/grep "​From:"​ | awk '​{print $2}'`
 +    ​
 +    #Now I generate the file containing the reply on the outgoing queue
 +    FILE=`/​bin/​mktemp /​mnt/​flash/​spool/​outgoing/​send_XXXXXX`
 +    echo "To: $NUMB" >> $FILE
 +    echo ""​ >> $FILE
 +    echo "​$TEXT"​ >> $FILE
 +fi
 +</​code>​
 +:id1: The reply message has to be compliant with the standard SMS file format, described [[sms_file_format|here]].
 +
 +To enable this Custom Action we also have to activate it from the Eventhandler,​ just uncommenting the block below deleting the //sharp character// (i.e. "#"​):​
 +<​code>​
 +#This is the custom script written by user for TX action
 +#if [ "​$1"​ = "​RECEIVED"​ ]; then  ​
 +#/​mnt/​flash/​root/​source/​custom/​custom_rx "​$2" ​                         ​
 +#fi
 +</​code>​
 +
 +To try this script, just copy and paste it inside of the form //Custom application applied to received items//. Then, send a message with the winning code, and you will receive the SMS of congratulations.
 +
 +
 +==== #2: Eventhandler extensions ====
 +You can configure this feature from the Web interface, menu //​Eventhandler//​. ​
 +\\ Here you will find a form showing the full content of the script, available to be modified depending on your needs. Thus you can assign meanings to LEDs, disable incoming or outgoing messages, and a lot of other things.
 +
 +To activate already defined extensions, you just need to uncomment their specific blocks enclosed between //sharp character// (i.e. "#"​). The opposite behavior will let you to deactivate them.
 +\\ As an example, please consider how we enabled Custom Actions in the previous paragraph.
 +
 +To define a new extension, you will need to write a new block like this one:
 +<​code>​
 +#UNCOMMENT THIS LINES TO EXECUTE THE NEW CUSTOM ACTION
 +#if [ "​$1"​ = <​certain_event>​ ]; then
 +#/​etc/​sms/​scripts/​myscript.php
 +#fi
 +</​code>​
 +Now the procedure defined in //​myscript.php//​ will be executed everytime the SMS engine will manage a message belonging to the <​certain_event>​. Possible values of this variable are:
 +  * "​RECEIVED"​ = incoming message;
 +  * "​SENT"​ = outgoing message correctly sent;
 +  * "​FAILED"​ = outgoing message not sent, because of some internal error;
 +  * "​REPORT"​ = delivery report on a previously sent message.
 +
 +The arguments you can pass to the new script are:
 +  * //$1//: the event identificative (SENT, RECEIVED, FAILED or REPORT);
 +  * //$2//: the full path to the SMS file;
 +  * //$3//: the message ID of an outgoing message, only used if you sent a message successfully with delivery report enabled.
  
custom_actions.txt ยท Last modified: 2016/06/14 18:35 (external edit)