{"id":20301972,"url":"https://github.com/medic/cht-gateway","last_synced_at":"2025-04-11T13:37:00.724Z","repository":{"id":41419544,"uuid":"56782861","full_name":"medic/cht-gateway","owner":"medic","description":"Android SMS gateway app for CHT Applications","archived":false,"fork":false,"pushed_at":"2024-02-28T02:03:30.000Z","size":1013,"stargazers_count":86,"open_issues_count":42,"forks_count":41,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-03-25T09:49:28.342Z","etag":null,"topics":["android","cht","hacktoberfest","health","mhealth","sms","sms-gateway"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/medic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"medic","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2016-04-21T15:00:05.000Z","updated_at":"2025-03-18T22:05:52.000Z","dependencies_parsed_at":"2024-11-14T16:34:20.896Z","dependency_job_id":"bf00128d-d4ca-42f0-b78a-0aca53d0c7bd","html_url":"https://github.com/medic/cht-gateway","commit_stats":null,"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fcht-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/medic","download_url":"https://codeload.github.com/medic/cht-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248410244,"owners_count":21098772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","cht","hacktoberfest","health","mhealth","sms","sms-gateway"],"created_at":"2024-11-14T16:28:40.510Z","updated_at":"2025-04-11T13:37:00.699Z","avatar_url":"https://github.com/medic.png","language":"Java","funding_links":["https://github.com/sponsors/medic"],"categories":[],"sub_categories":[],"readme":"`CHT Gateway App`\n===============\n\n[![cht-gateway build](https://github.com/medic/cht-gateway/actions/workflows/build.yml/badge.svg)](https://github.com/medic/cht-gateway/actions/workflows/build.yml)\n\nDownload APKs from: https://github.com/medic/cht-gateway/releases\n\n-----\n\nAn SMS gateway for Android.  Send and receive SMS from your webapp via an Android phone.\n\n\t+--------+                 +-----------+\n\t|  web   |                 |  cht-     | \u003c-------- SMS\n\t| server | \u003c---- HTTP ---- |  gateway  |\n\t|        |                 | (android) | --------\u003e SMS\n\t+--------+                 +-----------+\n\n# Use\n\n## Installation\n\nInstall the latest APK from https://github.com/medic/cht-gateway/releases\n\n## Configuration\n\n### CHT\n\nIf you're configuring `cht-gateway` for use with hosted [`CHT-Core`](https://github.com/medic/cht-core), 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:\n\n#### Medic-branded gateway\n\nPlease note that in the medic-branded build, the username is hard-coded as `gateway`, and cannot be changed.\n\n```\nInstance name: myproject [dev]\nPassword: topSecret\n```\n\n#### Generic-branded gateway\n\n```\nWebappUrl: https://gateway:topSecret@myproject.some-subdomain.medicmobile.org/api/sms\n```\n\n### Other\n\nIf you're configuring `cht-gateway` for use with other services, you will need to use the _generic_ build of `cht-gateway`, and find out the value for _CHT URL_ from your tech support.\n\n### CDMA Compatibility Mode\n\nSome 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 `cht-gateway` is running on a GSM network and:\n\n* multipart messages sent to CDMA phones never arrive; or\n* multipart messages sent to CDMA phones are truncated\n\n# Passwords\n\nWhen using HTTP Basic Auth with gateway, all characters in the password must be chosen from the [ISO-8859-1](https://en.wikipedia.org/wiki/ISO/IEC_8859-1) characterset, excluding `#`, `/`, `?`, `@`.\n\n# API\n\nThis is the API specification for communications between `cht-gateway` and a web server.  Messages in both directions are `application/json`.\n\nWhere a list of values is expected but there are no values provided, it is acceptable to:\n\n* provide a `null` value; or\n* provide an empty array (`[]`); or\n* omit the field completely\n\nBar array behaviour specified above, `cht-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\n## Idempotence\n\nN.B. messages are considered duplicate by `cht-gateway` if they have identical values for `id`.  The webapp is expected to do the same.\n\n`cht-gateway` will not re-process duplicate webapp-originating messages.\n\n`cht-gateway` may forward a webapp-terminating message to the webapp multiple times.\n\n`cht-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:\n\n* the phone receives multiple delivery status reports from the mobile network for the same message\n* `cht-gateway` failed to process the webapp's response when the delivery report was last forwarded from `cht-gateway` to webapp\n\n## Authorisation\n\n`cht-gateway` supports [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication).  Just include the username and password for your web endpoint when configuring `cht-gateway`, e.g.:\n\n\thttps://username:password@example.com/cht-gateway-api-endpoint\n\n## Messages\n\nThe entire API should be implemented by a webapp at a single endpoint, e.g. https://exmaple.com/cht-gateway-api-endpoint\n\n### GET\n\nExpected response:\n\n\t{\n\t\t\"medic-gateway\": true\n\t}\n\n### POST\n\n`cht-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.\n\n### Request\n\n#### Headers\n\nThe following headers will be set by requests:\n\nheader           | value\n-----------------|-------------------\n`Accept`         | `application/json`\n`Accept-Charset` | `utf-8`\n`Accept-Encoding`| `gzip`\n`Cache-Control`  | `no-cache`\n`Content-Type`   | `application/json`\n\nRequests and responses may be sent with `Content-Encoding` set to `gzip`.\n\n#### Content\n\n\t{\n\t\t\"messages\": [\n\t\t\t{\n\t\t\t\t\"id\": \u003cString: uuid, generated by `cht-gateway`\u003e,\n\t\t\t\t\"from\": \u003cString: international phone number\u003e,\n\t\t\t\t\"content\": \u003cString: message content\u003e,\n\t\t\t\t\"sms_sent\": \u003clong: ms since unix epoch that message was sent\u003e,\n\t\t\t\t\"sms_received\": \u003clong: ms since unix epoch that message was received\u003e\n\t\t\t},\n\t\t\t...\n\t\t],\n\t\t\"updates\": [\n\t\t\t{\n\t\t\t\t\"id\": \u003cString: uuid, generated by webapp\u003e,\n\t\t\t\t\"status\": \u003cString: PENDING|SENT|DELIVERED|FAILED\u003e,\n\t\t\t\t\"reason\": \u003cString: failure reason (optional - only present for status:FAILED)\u003e\n\t\t\t},\n\t\t\t...\n\t\t],\n\t}\n\nThe status field is defined as follows.\n\nStatus           | Description\n-----------------|-------------------\nPENDING | The message has been sent to the gateway's network\nSENT | The message has been sent to the recipient's network\nDELIVERED | The message has been received by the recipient's phone\nFAILED | The delivery has failed and will not be retried\n\n### Response\n\n#### Success\n\n##### HTTP Status: `2xx`\n\nClients may respond with any status code in the `200`-`299` range, as they feel is\nappropriate.  `cht-gateway` will treat all of these statuses the same.\n\n##### Content\n\n\t{\n\t\t\"messages\": [\n\t\t\t{\n\t\t\t\t\"id\": \u003cString: uuid, generated by webapp\u003e,\n\t\t\t\t\"to\": \u003cString: local or international phone number\u003e,\n\t\t\t\t\"content\": \u003cString: message content\u003e\n\t\t\t},\n\t\t\t...\n\t\t],\n\t}\n\n#### HTTP Status `400`+\n\nResponse codes of `400` and above will be treated as errors.\n\nIf the response's `Content-Type` header is set to `application/json`, `cht-gateway` will attempt to parse the body as JSON.  The following structure is expected:\n\n\t{\n\t\t\"error\": true,\n\t\t\"message\": \u003cString: error message\u003e\n\t}\n\nThe `message` property may be logged and/or displayed to users in the `cht-gateway` UI.\n\n#### Other response codes\n\nTreatment of response codes below `200` and between `300` and `399` will _probably_ be handled sensibly by Android.\n\n# SMS Retry Mechanism\n\nGateway 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`.\n\n1. A possible temporary error occurs and Gateway retries sending the SMS:\n    1.1 SMS status will be updated to `UNSENT`, so Gateway will find it and add it into the `send queue` automatically.\n    1.2 SMS' `retry counter` increases by 1.\n    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.\n    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`\n\n2. Gateway has a maximum limit of attempts to retry sending SMS (currently 20), If this is reached then:\n    2.1 Gateway will hard fail the SMS by updating its status to `FAILED` and won't retry again.\n    2.2 Gateway logs error. Sample: `Sending message to +1123123123 failed (cause: radio off) Not retrying`\n\n3. At this point the user has the option of manually select the SMS and press `Retry` button.\n    3.1 If they do and SMS fails again, then the process will restart from step # 1.\n\n# Development\n\n## Requirements\n\nDevelopment guides are available in the \"Android\" section of the [Community Health Toolkit Docs Site](https://docs.communityhealthtoolkit.org/core/guides/android/). 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.\n\n### `demo-server`\n\n* npm\n\n## Building locally\n\nMore details of how to setup and build the app [here](https://docs.communityhealthtoolkit.org/core/guides/android/development-setup/). The following are the most common tasks:\n\n### Build and install\n\nTo build locally and install to an attached android device:\n\n\tmake\n\n### Tests\n\nTo run unit tests and static analysis tools locally:\n\n\tmake test\n\nTo run end to end tests, first either connect a physical device, or start an emulated android device, and then:\n\n    make test-ui\n\nEnd 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:\n\n```\ncom.android.build.gradle.internal.testing.ConnectedDevice \u003e runTests[4034G - 6.0] FAILED \n        com.android.builder.testing.api.DeviceException: com.android.ddmlib.InstallException: INSTALL_FAILED_VERSION_DOWNGRADE\n```\n\nDon'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.\n\n## `demo-server`\n\nThere is a demonstration implementation of a server included for `cht-gateway` to communicate with.  You can add messages to this server, and query it to see the interactions that it has with `cht-gateway`.\n\n### Local\n\nTo start the demo server locally:\n\n\tmake demo-server\n\nTo list the data stored on the server:\n\n\tcurl http://localhost:8000\n\nTo make the next good request to `/app` return an error:\n\n\tcurl --data '\"Something failed!\"' http://localhost:8000/error\n\nTo add a webapp-originating message (to be send by `cht-gateway`):\n\n\tcurl -vvv --data '{ \"id\": \"3E105262-070C-4913-949B-E7ACA4F42B71\", \"to\": \"+447123555888\", \"content\": \"hi\" }' http://localhost:8000\n\nTo simulate a request from `cht-gateway`:\n\n\tcurl http://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 '{}'\n\nTo clear the data stored on the server:\n\n\tcurl -X DELETE http://localhost:8000\n\nTo set a username and password on the demo server:\n\n\tcurl --data '{\"username\":\"alice\", \"password\":\"secret\"}' http://localhost:8000/auth\n\n### Remote\n\nIt's simple to deploy the demo server to remote NodeJS hosts.\n\n#### Heroku\n\nTODO walkthrough\n\n#### Modulus\n\nTODO walkthrough\n\n## Releasing\n\n1. Create a git tag for the version, eg: `v1.7.4`.\n2. Push the tag to the repo and GitHub Actions will build and publish the apk to GitHub.\n3. Announce the release on the [CHT forum](https://forum.communityhealthtoolkit.org), under the \"Product - Releases\" category.\n\n# Android Version Support\n\n## \"Default SMS/Messaging app\"\n\nSome changes were made to the Android SMS APIs in 4.4 (Kitkat®).  The significant change was this:\n\n\u003e 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_\n\nSome reading on this can be found at:\n\n* http://android-developers.blogspot.com.es/2013/10/getting-your-sms-apps-ready-for-kitkat.html\n* https://www.addhen.org/blog/2014/02/15/android-4-4-api-changes/\n\nAdding support for kitkat® means that there is some extra code in `cht-gateway` whose purpose is not obvious:\n\n### Non-existent activities in `AndroidManifest.xml`\n\nActivities `HeadlessSmsSendService` and `ComposeSmsActivity` are declared in `AndroidManifest.xml`, but are not implemented in the code.\n\n### Unwanted permissions\n\nThe `BROADCAST_WAP_PUSH` permission is requested in `AndroidManifest.xml`, and an extra `BroadcastReceiver`, `MmsIntentProcessor` is declared.  When `cht-gateway` is the default messaging app on a device, incoming MMS messages will be ignored.  Actual WAP Push messages are probably ignored too.\n\n### Extra intents\n\nTo support being the default messaging app, `cht-gateway` listens for `SMS_DELIVER` as well as `SMS_RECEIVED`.  If the default SMS app, we need to ignore `SMS_RECEIVED`.\n\n## Runtime Permissions\n\nSince 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\n\n## Copyright\n\nCopyright 2013-2021 Medic Mobile, Inc. \u003chello@medicmobile.org\u003e\n\n## License\n\nThe software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fcht-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedic%2Fcht-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fcht-gateway/lists"}