Download APKs from: https://github.com/medic/medic-gateway/releases

An SMS gateway for Android. Send and receive SMS from your webapp via an Android phone.

+--------+                 +-----------+
|  web   |                 |  medic-   | <-------- SMS
| server | <---- HTTP ---- |  gateway  |
|        |                 | (android) | --------> SMS
+--------+                 +-----------+

Install stable public releases from the Google Play store, or download the latest development APK from https://github.com/medic/medic-gateway/releases.

If you're configuring medic-gateway for use with hosted medic-webapp, with a URL of e.g. https://myproject.dev.medicmobile.org and a username of gateway and a password of topSecret, fill in the settings as follows:

Please note that in the medic-branded build, the username is hard-coded as gateway, and cannot be changed.

Instance name: myproject [dev]
Password: topSecret

WebappUrl: https://gateway:[email protected]

If you're configuring medic-gateway for use with other services, you will need to use the generic build of medic-gateway, and find out the value for webapp URL from your tech support.

Some CDMA networks have limited support for multipart SMS messages. This can occur within the same network, or only when sending SMS from a GSM network to a CDMA network. Check this box if medic-gateway is running on a GSM network and:

• multipart messages sent to CDMA phones never arrive; or
• multipart messages sent to CDMA phones are truncated

When using HTTP Basic Auth with gateway, all characters in the password must be chosen from the ISO-8859-1 characterset, excluding #, /, ?, @.

This is the API specification for communications between medic-gateway and a web server. Messages in both directions are application/json.

Where a list of values is expected but there are no values provided, it is acceptable to:

• provide a null value; or
• provide an empty array ([]); or
• omit the field completely

Bar array behaviour specified above, medic-gateway must include fields specified in this document, and the web server must include all expected fields in its responses. Either party may include extra fields as they see fit.

N.B. messages are cosidered duplicate by medic-gateway if they have identical values for id. The webapp is expected to do the same.

medic-gateway will not re-process duplicate webapp-originating messages.

medic-gateway may forward a webapp-terminating message to the webapp multiple times.

medic-gateway may forward a delivery status report to the webapp multiple times for the same message. This should indicate a change of state, but duplicate delivery reports may be delivered in some circumstances, including:

• the phone receives multiple delivery status reports from the mobile network for the same message
• medic-gateway failed to process the webapp's response when the delivery report was last forwarded from medic-gateway to webapp

medic-gateway supports HTTP Basic Auth. Just include the username and password for your web endpoint when configuring medic-gateway, e.g.:

https://username:[email protected]/medic-gateway-api-endpoint

THe entire API should be implemented by a webapp at a single endpoint, e.g. https://exmaple.com/medic-gateway-api-endpoint

Expected response:

{
	"medic-gateway": true
}

medic-gateway will accept and process any relevant data received in a response. However, it may choose to only send certain types of information in a particular request (e.g. only provide a webapp-terminating SMS), and will also poll the web service periodically for webapp-originating messages, even if it has no new data to pass to the web service.

The following headers will be set by requests:

Requests and responses may be sent with Content-Encoding set to gzip.

{
	"messages": [
		{
			"id": <String: uuid, generated by `medic-gateway`>,
			"from": <String: international phone number>,
			"content": <String: message content>,
			"sms_sent": <long: ms since unix epoch that message was sent>,
			"sms_received": <long: ms since unix epoch that message was received>
		},
		...
	],
	"updates": [
		{
			"id": <String: uuid, generated by webapp>,
			"status": <String: PENDING|SENT|DELIVERED|FAILED>,
			"reason": <String: failure reason (optional - only present for status:FAILED)>
		},
		...
	],
}

The status field is defined as follows.

Clients may respond with any status code in the 200-299 range, as they feel is appropriate. medic-gateway will treat all of these statuses the same.

{
	"messages": [
		{
			"id": <String: uuid, generated by webapp>,
			"to": <String: local or international phone number>,
			"content": <String: message content>
		},
		...
	],
}

Response codes of 400 and above will be treated as errors.

If the response's Content-Type header is set to application/json, medic-gateway will attempt to parse the body as JSON. The following structure is expected:

{
	"error": true,
	"message": <String: error message>
}

The message property may be logged and/or displayed to users in the medic-gateway UI.

Treatment of response codes below 200 and between 300 and 399 will probably be handled sensibly by Android.

• JDK

• npm

To build locally and install to an attached android device:

make

To run tests and static analysis tools locally:

make test

To run tests without static analysis (faster!):

./gradlew test

There is a demonstration implementation of a server included for medic-gateway to communicate with. You can add messages to this server, and query it to see the interactions that it has with medic-gateway.

To start the demo server locally:

make demo-server

To list the data stored on the server:

curl https://localhost:8000

To make the next good request to /app return an error:

curl --data '"Something failed!"' https://localhost:8000/error

To add a webapp-originating message (to be send by medic-gateway):

curl -vvv --data '{ "id": "3E105262-070C-4913-949B-E7ACA4F42B71", "to": "+447123555888", "content": "hi" }' https://localhost:8000

To simulate a request from medic-gateway:

curl https://localhost:8000/app -H "Accept: application/json" -H "Accept-Charset: utf-8" -H "Accept-Encoding: gzip" -H "Cache-Control: no-cache" -H "Content-Type: application/json" --data '{}'

To clear the data stored on the server:

curl -X DELETE https://localhost:8000

To set a username and password on the demo server:

curl --data '{"username":"alice", "password":"secret"}' https://localhost:8000/auth

It's simple to deploy the demo server to remote NodeJS hosts.

TODO walkthrough

TODO walkthrough

Some changes were made to the Android SMS APIs in 4.4 (Kitkat®). The significant change was this:

from android 4.4 onwards, apps cannot delete messages from the device inbox unless they are set, by the user, as the default messageing app for the device

Some reading on this can be found at:

• https://android-developers.blogspot.com.es/2013/10/getting-your-sms-apps-ready-for-kitkat.html
• https://www.addhen.org/blog/2014/02/15/android-4-4-api-changes/

Adding support for kitkat® means that there is some extra code in medic-gateway whose purpose is not obvious:

Activities HeadlessSmsSendService and ComposeSmsActivity are declared in AndroidManifest.xml, but are not implemented in the code.

The BROADCAST_WAP_PUSH permission is requested in AndroidManifest.xml, and an extra BroadcastReceiver, MmsIntentProcessor is declared. When medic-gateway is the default messaging app on a device, incoming MMS messages will be ignored. Actual WAP Push messages are probably ignored too.

To support being the default messaging app, medic-gateway listens for SMS_DELIVER as well as SMS_RECEIVED. If the default SMS app, we need to ignore SMS_RECEIVED.

Since Android 6.0 (marshmallow), permissions for sending and receiving SMS must be requested both in AndroidManifest.xml and also at runtime. Read more at https://developer.android.com/intl/ru/about/versions/marshmallow/android-6.0-changes.html#behavior-runtime-permissions