The free and open source SMS gateway for Android

Instructions

  • SMSSync uses the HTTP and HTTPS protocols for communication.
    To start the SMSSync Gateway, you'll need to specify a Sync URL. This URL is where all incoming SMS will be transmitted to. Remember to enter the full URL including the filename. A typical example will be http://somedomain.com/index.php
  • For security you can specify a secret key to be sent to the Sync URL. If the secret key doesn't match on the server, the Sync URL can ignore the transmission.
  • Additionally, you can specify keywords with which to filter incoming SMS. Only matching messages will be forwarded to the SMSSync Gateway URL.
  • SMSSync uses the following variables to transmit the incoming SMS via the POST method:
    • from -- the number that sent the SMS
    • message -- the SMS sent
    • message_id -- the unique ID of the SMS
    • sent_to -- the phone number the SMS was sent to
    • secret -- the secret key set on the app
    • device_id -- the unique id set on the device to be used by the server to identify which device is communicating with it. Note: supported from v2.6.1 and above
    • sent_timestamp -- the timestamp the SMS was sent. In the UNIX timestamp format

In order for SMSSync to ensure perfect transmission, the Sync URL must return a JSON-formatted status message, as shown below.

Succeeded

{
    "payload":
    {
        "success": true,
        "error": null
    }
}


Failed
{
    "payload":
    {
        "success": false,
        "error": "error message from the server"
    }
}

 

Response from server

SMSSync allows either an auto-response message to be configured on the app itself, or to be retrieved from the server. When the app makes an HTTP Post request to sync the incoming SMS to the configured URL, the server can respond with JSON-encoded messages alongside the success message. The app then sends these messages by SMS to the specified users phone.

This makes it possible to have an instant response via SMS when an HTTP Post request is made. To leverage this feature, a JSON formatted string like the one below needs to be returned by the configured URL in response to the app's HTTP Post request.

In the app itself, ensure *Get Reply from Server* is checked to enable this feature.

Response JSON data from the Sync URL

{
    "payload": {
        "success": "true",
        "task": "send",
        "messages": [
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            },
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            },
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            }
        ]
    }
}

 

Task

SMSSync supports execution of tasks defined on the server. Currently it supports sending of messages sent from the Sync URL as SMS. This feature is targeted towards developers. The app can be configured to poll the server for new tasks at a given frequency. The server then needs to respond to HTTP GET requests with ?task=send (for example http://callback_url/smssync?task=send). The format of this response is shown below.



Response JSON data from the Sync URL

{
    "payload": {
        "task": "send",
        "secret": "secret_key",
        "messages": [
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            },
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            },
            {
                "to": "+000-000-0000",
                "message": "the message goes here"
            }
        ]
    }
}


Notes:
  • The secret key provided by the server must match the secret key configured within SMSSync, otherwise SMSSync will not execute the task.
  • To ensure the message is sent to the correct recipient, add the country code to the phone number. Eg. +254700709142. Without this, the message is sent to the number in the country where the phone is.
  • The web service should check the value of the secret key passed with each task request that SMSSync makes to it for messages to send and respond appropriately to ensure that not any instance of SMSSync can communicate with it.

A sample web service

This is a sample PHP script to demonstrate how to write a webservice to successfully communicate with SMSSync.

/**
 *  Get the phone number that sent the SMS.
 */
$error = null;
if (isset($_POST['from']))
{
    $from = $_POST['from'];
}
else
{
$error = 'The from variable was not set';

}

/**
 * Get the SMS aka the message sent.
 */
if (isset($_POST['message']))
{
    $message = $_POST['message'];
}
else
{
    $error = 'The message variable was not set';
}

// Set success to false as the default success status
$success = false;

/**
 * Get the secret key set on SMSSync side
 * for matching on the server side.
 */
if (isset($_POST['secret']))
{
    $secret = $_POST['secret'];
}


/**
 * Get the timestamp of the SMS
 */
if (isset($_POST['sent_timestamp']))
{
    $sent_timestamp = $_POST['sent_timestamp'];
}

/**
 * Get the phone number of the device SMSSync is
 * installed on.
 */
if (isset($_POST['sent_to']))
{
    $sent_to = $_POST['sent_to'];
}

/**
 * Get the unique message id
 */
if (isset($_POST['message_id']))
{
    $message_id = $_POST['message_id'];
}

/**
 * Now we have retrieved the data sent over by SMSSync
 * via HTTP. Next thing to do is to do something with
 * the data. Either echo it or write it to a file or even
 * store it in a database. This is entirely up to you.
 * After, return a JSON string back to SMSSync to know
 * if the web service received the message successfully or not.
 *
 * In this demo, we are just going to save the data
 * received into a text file.
 *
 */
if ((strlen($from) > 0) AND (strlen($message))
{
    /* The screte key set here is 123456. Make sure you enter
     * that on SMSSync.
     */
    if (($secret == '123456'))
    {
        $success = true;
    }
    else
    {
        $error = "The secret value sent from the device does not match the one on the server";
    }
    // now let's write the info sent by SMSSync
    //to a file called test.txt
    $string = "From: ".$from."\n";
    $string .= "Message: ".$message."\n";
    $string .= "Timestamp: ".$sent_timestamp."\n";
    $string .= "Messages Id:" .$message_id."\n";
    $string .= "Sent to: ".$sent_to."\n\n\n";
    $myFile = "test.txt";
    $fh = fopen($myFile, 'a') or die("can't open file");
    @fwrite($fh, $string);
    @fclose($fh);

    /**
    * Now send a JSON formatted string to SMSSync to
     * acknowledge that the web service received the message
    */
    echo json_encode(array("payload"=>array(
        "success"=>$success, "error" => $error)));

}
else
{
    echo json_encode(array("payload"=>array(
        "success"=>$success, "error" => $error)));
}

/**
 * UnComment the code below to send an instant
 * reply as SMS to the user.
 *
 * This feature requires the "Get reply from server" checked on SMSSync.
 *
 if (isset($_GET['task']))
 {
    $m = "Your message has been received";
    $f = "0267123407";
    $s = true;
    $reply[0] = array("to" => $f, "message" => $m);
    $myFile = "task.txt";
    $fh = fopen($myFile, 'a') or die("can't open file");
    @fwrite($fh, $m."\n\n");
    @fclose($fh);

    echo json_encode(array("payload"=>array("success"=>$s,"task"=>"send","messages"=>array_values($reply))));
 }*/

Assuming you've the above code saved in a file called demo.php and is located at your web server's document root, you can issue the command below to test.

    $ curl -D - -X POST http://localhost/demo.php \
        -F "from=09048370465" \
        -F "message=sample text message" \
        -F "secret=123456"

The server should return a JSON response indicating a success:true or success:false

For a complete web service application, look at Ushahidi's SMSSync plugin which utilizes most of SMSSync's features.

There is also SMSSync webservice for Django that implements most of the features. You can download it from GitHub.com. Thanks to Caine Wanjau