Overview


Many Magpi Pro and Enterprise users have used the "SMS data entry" feature, which allows data collectors in the field to send data into Magpi using basic SMS on their phone (rather than the Magpi app).  Initially, that SMS data entry feature utilized only an international number (to send the SMS messages to) which could be expensive.


The team at Ushahidi have developed a program called SMSSync that enables simple creation of a local SMS gateway (thank you, Ushahidi!) -- this enables user organizations to quickly create a local number to send SMS messages to, and then those messages get forwarded to Magpi.com.  Basically you install SMSSync on an Android phone, put a local SIM card into the phone, and then SMS messages sent to that SIM card's phone number will get forwarded to Magpi.


Note: when sending messages from Magpi through a local gateway like SMSSync, message credits will not be deducted from your Magpi account for the outgoing messages.


This article how to covers the essential configuration to get SMSSync up and running. The application has been designed to be intuitive enough to easily get it running.


Note: SMSSync runs on any device with Android 2.1 and above. However because it relies heavily on SMS, the device needs to support SMS.


How it works

  1. User enters the number and shares a form using Structured sms
  2. The Shared form is sent as an SMS to shared number(s) from magpi server in the format: 3Z7806#Question1#Question2#QuestionN
  3. The message in the destination number is received from an international number.
  4. The response is sent, NOT by replying it to the number the message was received from, but by sending it to the local gateway number (e.g 251700000000). This way, the reply text message is sent to the number at a subsidised cost (i.e. within country’s local rates)
  5. As soon as this reply is sent to the local gateway number, SMS sync recognizes the form's short code from message format. The message would then be uploaded by SMSsync app via a working internet connection 


To get started, here are the key steps involved

  • Setting up SMS local gateway web configurations 
  • Setting up the gateway app on your mobile device. Download and install SMSsync.apk
  • Share the form
  • Start collecting data



Setting up the Web configuration 

First, start by enabling the local gateway in Web settings To do so:

  1. Select the SMS local gateway checkbox to enable it
  2. Enter a secret key
  3. Enter Structured SMS server number (this is the gateway number).
  4. Save the new settings.


A message should appear indicating that the new settings were successfully saved.




Setting up the the Gateway App

  1. Open the installed gateway app SMSsync.apk
  2. Tap on the Sync URL tab.
  3. Tap on the  icon on the actionbar. An input dialog should open.
  4. Enter a title for the Sync URL.
  5. Leave the optional secret key field blank.
  6. Enter the URL for your webservice, which is https://www.magpi.com/sms/receiveAndroidSMS
  7. Tap Ok to save the new entry
  8. Enter a comma separated value for the keyword(s). These keywords in this case will be the  form's Short Form Name  for the form you want to upload data to. It is normally found on the forms sharing page under Structured SMs when sharing a form with SMS. e.g. “From Magpi.com: Form 3Z7806 has been shared with you. To upload, reply to this number in the format: 3Z7806#sometext#magicnumber#yourtown” – The keyword to enter will be 3Z7806 

     


 

 

Starting the service

  1. Make sure you have added and enabled(checked) at least one Sync URL e.g. In the example below check Magpi Uploads.
  2. On the SYNC URL tab, tap on the Start SMSSync service to start the service. You do this if the service is disabled or you are starting a new synch service.

                                                     


Sync Configuration Settings

This is where you enable SMSSync to automatically upload messages per the Sync setting.  

Auto Sync
  1. Go to Settings screen by tapping the Settings icon icon on the actionbar 
  2. Select the Enable Auto Sync checkbox
  3. Select the Auto sync frequency and set the frequency to 1.


Task Checking

  1. Select the Enable Task Checking checkbox to enable the service.
  2. Tap on Frequency to set the frequency and set the frequency to 1.                                 


Managing Messages

Manually syncing pending message (auto sync not enabled)

Manually syncing a single pending message 

  • Go to The Pending messages tab
  • Long press on the pending message you want to sync by tapping and holding it until the actionbar menu changes.
  • Tap on the Sync icon icon on the actionbar. The sync icon should spin for a while.
  • After the sync icon spins for a while, a Toast should show with a status message.  

Manually syncing all pending messages (auto sync not enabled)

  • Tap on the Sync icon icon on the actionbar. The sync icon should spin for a while.
  • After the sync icon spins for a while, a Toast should show up with a status message.


Deleting Sent messages

To delete a single sent messages

  1. Long press on the sent message you want to delete by tapping and holding it until the actionbar menu changes.
  2. Tap on the Delete icon icon on the actionbar. A confirmation dialog should opened.
  3. Tap Yes to delete it or No to cancel the deletion.

To delete all sent messages

  1. Tap on theDelete iconicon on the actionbar. A confirmation dialog should opened.
  2. Tap Yes to delete all sent messages or No to cancel the deletion.


Deleting pending messages

  • Tap on the Delete icon icon on the actionbar. A confirmation dialog should opened.
  • Tap Yes to delete all pending messages or No to cancel the deletion