Skip to content

multiOTP/SMSGatewayApp

BranchesTags
 
 

Repository files navigation

SMS Gateway App

Install App using the latest APK file available: SMS Gateway

An SMS gateway for Android, based on CHT Gateway App from Medic. Send and receive SMS from your webapp via an Android phone.

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

Use

Installation

Install App using the latest APK file available: SMS Gateway

Configuration

Set the URL of your SMS Gateway URL. You can create an SMS Gateway using the open source SMSGateway PHP class.

CDMA Compatibility Mode

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 smsgateway is running on a GSM network and:

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

Passwords

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

API

This is the API specification for communications between smsgateway 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, smsgateway 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.

Idempotence

N.B. messages are considered duplicate by smsgateway if they have identical values for id. The webapp is expected to do the same.

smsgateway will not re-process duplicate webapp-originating messages.

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

smsgateway 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
  • smsgateway failed to process the webapp's response when the delivery report was last forwarded from smsgateway to webapp

Authorisation

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

https://username:password@example.com/smsgateway-api-endpoint

Messages

The entire API should be implemented by a webapp at a single endpoint, e.g. https://1-2-3-4-5-6.net/smsgateway/

GET

Expected response:

{
	"medic-gateway": true
}

POST

smsgateway 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.

Request

Headers

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.

Content

{
	"messages": [
		{
			"id": <String: uuid, generated by `smsgateway`>,
			"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.

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

Response

Success

HTTP Status: 2xx

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

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

HTTP Status 400+

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

If the response's Content-Type header is set to application/json, smsgateway 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 smsgateway UI.

Other response codes

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

SMS Retry Mechanism

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.

  1. A possible temporary error occurs and Gateway retries sending the SMS: 1.1 SMS status will be updated to UNSENT, so Gateway will find it and add it into the send queue automatically. 1.2 SMS' retry counter increases by 1. 1.3 The retry attempt is scheduled based on this formula: SMS' last activity time + ( 1 minute * (retry counter ^ 1.5) ). This means the time between retries is incremental. 1.4 Gateway logs: the error, the retry counter and the retry scheduled time. Sample: Sending SMS to +1123123123 failed (cause: radio off) Retry #5 in 15 min

  2. Gateway has a maximum limit of attempts to retry sending SMS (currently 20), If this is reached then: 2.1 Gateway will hard fail the SMS by updating its status to FAILED and won't retry again. 2.2 Gateway logs error. Sample: Sending message to +1123123123 failed (cause: radio off) Not retrying

  3. At this point the user has the option of manually select the SMS and press Retry button. 3.1 If they do and SMS fails again, then the process will restart from step # 1.

Android Version Support

Android specific parameters

Using adb shell, you should change these two parameters:

  • sms_outgoing_check_max_count
  • sms_outgoing_check_interval_ms

Example for a limit of 200 messages per minute:

adb shell
settings put global sms_outgoing_check_max_count 200
settings put global sms_outgoing_check_interval_ms 60000

You need to reboot your Android phone. after these changes

"Default SMS/Messaging app"

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 smsgateway whose purpose is not obvious:

Non-existent activities in AndroidManifest.xml

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

Unwanted permissions

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

Extra intents

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

Runtime Permissions

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

Copyright 2013-2021 CHT Gateway - Medic Mobile, Inc. hello@medicmobile.org
Copyright 2022 SMS Gateway - SysCo systemes de communication sa info@multiotp.net

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

About

Android SMS gateway app

Topics

android java sms gateway smartphone sms-gateway on-premises

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Java 98.0%
  • Other 2.0%