-
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 at the Sync URL. If the secret key doesn't match, the Sync URL will ignore the transmission.
- Additionally, you can specify keywords with which to filter incoming SMS. Only matching SMS will be sent 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
- sent_timestamp -- the timestamp the SMS was sent. In the UNIX timestamp format
In order for SMSSync to account for perfect transmission, the Sync URL needs to give back a formatted JSON string such as its shown below to indicate if it received the message or not.
Succeeded
{
payload: {
success: "true"
}
}
Failed
{
payload: {
success: "false"
}
}
Response from server
SMSSync allows auto response 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, it can send a JSON string that has messages in it as opposed to sending a success or failed JSON string as stated above. The app then sends the messages as SMS to 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 after the app makes the HTTP Post request.
Also, make sure *Get Reply From Server* is checked on SMSSync otherwise it will fail to send the SMS.
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 task sent from the configured Sync URL. At the moment, it supports sending of messages sent from the Sync URL as SMS. This feature is targeted towards developers. If you are a developer and you want SMSSync to send an SMS, send a JSON formatted string as shown below to SMSSync with the variable task=send. When SMSSync does an HTTP GET request with a sample URL like this one, http://callback_url/smssync?task=send, it should bring back a JSON string below.
Note: The secret key has to match the secret key configured with SMSSync, otherwise, SMSSync will not execute the task. To play it safe, add the country code to the phone number. Eg. +254700709142
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"
}
]
}
}
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.
*/
if (isset($_POST['from']))
{
$from = $_POST['from'];
}
/**
- Get the SMS aka the message sent. */ if (isset($_POST['message'])) { $message = $_POST['message']; }
// 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) > 0) AND (strlen($sent_timestamp) > 0 ) AND (strlen($sent_to) > 0) AND (strlen($message_id) > 0)) { / The screte key set here is 123456. Make sure you enter * that on SMSSync. */ if ( ( $secret == '123456')) { $success = "true"; } // 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)));
/**
- Comment the code below out if you want to send an instant
- reply as SMS to the user.
- This feature requires the "Get reply from server" checked on SMSSync. */
/**
- $msg = "Your message has been received";
- $reply[0] = array("to" => $from, "message" => $msg);
- echo json_encode(array("payload"=>array("success"=>$success,"task"=>"send","messages"=>array_values($reply)))); */
For a complete web service application, look at Ushahidi's SMSSync plugin.It utilizes most of SMSSync features.
There is also SMSSync webservice for Django that implements most of the features of SMSSync. You can download it from github.com. Thanks to Caine Wanjau