
An Android application that serves as an SMS gateway. It enables the sending and receiving of SMS messages through a PulseBridge Gateway Server using an Android phone.
This is the Client Application for PulseBridge Gateway/Server
Download APKs from: https://github.com/aamitn/pulsebridge-app/releases/download/1.1.5/pulsebridge-app-SNAPSHOT-generic-release.apk
An Android application that serves as an SMS gateway. It enables the sending and receiving of SMS messages through a PulseBridge Gateway Server using an Android phone.
5 lines1+--------+ +-----------+ 2|PBgatway| |pulsebridge| <-------- SMS 3| server | <---- HTTP ---- |gateway-app| 4| | | (android) | --------> SMS 5+--------+ +-----------+
Follow these three simple steps to get started with PulseBridge Gateway:
Run PulseBridge Gateway Server by `cloning` the Repo, following the Docs and click setup credentials button. (* Server requires valid SSL and https enabled for the mobile app to work).
Download PulseBridge Gateway Mobile App from release section of this Repo and set the URL in app provided by the server.
Send SMS from the Server Frontend or API
With the PulseBridge Gateway Server running, access the user-friendly interface at https://domain.tld to send SMS messages. Alternatively, integrate the SMS functionality into your applications using the provided API.
Install the latest APK from https://github.com/aamitn/pulsebridge-app/releases/download/1.1.5/pulsebridge-app-SNAPSHOT-generic-release.apk
If you're configuring pulsebridge-gateway-app for use with hosted pulsebridge-gateway webserver, with a URL of e.g. https://example.com and a username of userand a password of password, fill in the settings as follows:
1 lines1WebappUrl: https://user:passowrd@example.com/api/sms
If you're configuring pulsebridge-gateway-app for use with other services, you will need to use the generic build of pulsebridge-gateway-app, and find out the value for CHT 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 pulsebridge-gateway-app is running on a GSM network and:
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 pulsebridge-gateway-app 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:
null value; or[]); orBar array behaviour specified above, pulsebridge-gateway-app 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 considered duplicate by pulsebridge-gateway-app if they have identical values for id. The webapp is expected to do the same.
pulsebridge-gateway-app will not re-process duplicate webapp-originating messages.
pulsebridge-gateway-app may forward a webapp-terminating message to the webapp multiple times.
pulsebridge-gateway-app 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:
pulsebridge-gateway-app failed to process the webapp's response when the delivery report was last forwarded from pulsebridge-gateway-app to webapppulsebridge-gateway-app supports HTTP Basic Auth. Just include the username and password for your web endpoint when configuring pulsebridge-gateway-app, e.g.:
1 lines1https://username:password@example.com/pulsebridge-gateway-api-endpoint
The entire API should be implemented by a web application server at a single endpoint, e.g. https://exmaple.com/pulsebridge-gateway-app-api-endpoint
Expected response:
3 lines1{ 2 "pulsebridge-gateway": true 3}
pulsebridge-gateway-app 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:
| header | value |
|---|---|
Accept | application/json |
Accept-Charset | utf-8 |
Accept-Encoding | gzip |
Cache-Control | no-cache |
Content-Type | application/json |
Requests and responses may be sent with Content-Encoding set to gzip.
20 lines1{ 2 "messages": [ 3 { 4 "id": <String: uuid, generated by `pulsebridge-gateway-app`>, 5 "from": <String: international phone number>, 6 "content": <String: message content>, 7 "sms_sent": <long: ms since unix epoch that message was sent>, 8 "sms_received": <long: ms since unix epoch that message was received> 9 }, 10 ... 11 ], 12 "updates": [ 13 { 14 "id": <String: uuid, generated by webapp>, 15 "status": <String: PENDING|SENT|DELIVERED|FAILED>, 16 "reason": <String: failure reason (optional - only present for status:FAILED)> 17 }, 18 ... 19 ], 20}
The status field is defined as follows.
| Status | Description |
|---|---|
| PENDING | The message has been sent to the gateway's network |
| SENT | The message has been sent to the recipient's network |
| DELIVERED | The message has been received by the recipient's phone |
| FAILED | The delivery has failed and will not be retried |
2xxClients may respond with any status code in the 200-299 range, as they feel is
appropriate. pulsebridge-gateway-app will treat all of these statuses the same.
10 lines1{ 2 "messages": [ 3 { 4 "id": <String: uuid, generated by webapp>, 5 "to": <String: local or international phone number>, 6 "content": <String: message content> 7 }, 8 ... 9 ], 10}
400+Response codes of 400 and above will be treated as errors.
If the response's Content-Type header is set to application/json, pulsebridge-gateway-app will attempt to parse the body as JSON. The following structure is expected:
4 lines1{ 2 "error": true, 3 "message": <String: error message> 4}
The message property may be logged and/or displayed to users in the pulsebridge-gateway-app UI.
Treatment of response codes below 200 and between 300 and 399 will probably be handled sensibly by Android.
Gateway will retry to send the SMS when any of these errors occurs: RESULT_ERROR_NO_SERVICE, RESULT_ERROR_NULL_PDU and RESULT_ERROR_RADIO_OFF.
UNSENT, so Gateway will find it and add it into the send queue automatically.retry counter increases by 1.SMS' last activity time + ( 1 minute * (retry counter ^ 1.5) ). This means the time between retries is incremental.Sending SMS to +1123123123 failed (cause: radio off) Retry #5 in 15 minFAILED and won't retry again.Sending message to +1123123123 failed (cause: radio off) Not retryingRetry button.Development guides are available in the "Android" section of the Community Health Toolkit Docs Site. You will find instructions of how to setup your development environment, build and test new features, how to work with "flavor" apps, release, publish... and so on.
pulsebridge-gateway (Repo)More details of how to setup and build the app here. The following are the most common tasks:
To build locally and install to an attached android device:
1 lines1make
OR, generate release APK using
1 lines1make assemble-release
OR, build using gradle
1 lines1gradlew build -x test
To run unit tests and static analysis tools locally:
1 lines1make test
To run end to end tests, first either connect a physical device, or start an emulated android device, and then:
1 lines1make test-ui
End to end tests only run in devices with Android 4.4 - 9.0. Also it's possible that at the end of the tests when the SDK tries to uninstall the app from the device the following error is shown:
2 lines1com.android.build.gradle.internal.testing.ConnectedDevice > runTests[4034G - 6.0] FAILED 2 com.android.builder.testing.api.DeviceException: com.android.ddmlib.InstallException: INSTALL_FAILED_VERSION_DOWNGRADE
Don't worry about that, it means the tests ran OK, but the SDK failed to remove the app for compatibility issues with your device, but this error only happens with the tests.
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 messaging app for the device
Some reading on this can be found at:
Adding support for kitkat® means that there is some extra code in pulsebridge-gateway-app whose purpose is not obvious:
AndroidManifest.xmlActivities 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 pulsebridge-gateway-app 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, pulsebridge-gateway-app 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
Copyright 2018-2024 Bitmutex Technologies <support@bitmutex.com>
The software is provided under Apache 2.0 License. Contributions to this project are accepted under the same license.
Check out the live demo or dive into the source code to see how it's built.