The SMS Gateway for Android™ app enables sending and receiving SMS messages through an API that can be accessed directly on the device or via a cloud server when direct device access is not possible.
Copy the command below to clone the repository to your machine.
Turns your smartphone into an SMS gateway for sending and receiving messages via API.
Explore the docs »
Report Bug
·
Request Feature
SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application that allows you to send SMS messages programmatically via an API or CLI tool and receive webhooks on incoming SMS. This makes it ideal for integrating SMS functionality into your own applications or services.
📱 Core Functionality:
💬 Message Handling:
🔒 Security and Privacy:
🔧 Advanced Features:
🔌 Integration:
Note: It is not recommended to use this for batch sending due to potential mobile operator restrictions.
You can install app to your device from prebuilt APK.
The project provides two pre-built variants:
You need an Android device with Android 5.0 (Lollipop) or above for using the application.
To use the application, you need to grant the following permissions:
For integration examples, please refer to the CLI Tool Documentation and API Documentation
The SMS Gateway for Android can work in two modes: with a Local Server started on the device or with a Cloud Server. The basic API is the same for both modes and is documented on the SMS Gateway for Android API Documentation page.
This mode is ideal for sending messages from a local network.
Launch the app on your device.
Toggle the Local Server switch to the "on" position.
Tap the Offline button at the bottom of the screen to activate the server.
In the Local Server section, your device's local and public IP addresses will be displayed, along with the credentials for basic authentication. Note that the public IP address is only accessible if you have a public (or "white") IP and your firewall is configured correctly.
To send a message from within the local network, execute a curl command like the one below. Replace <username>, <password>, and <device_local_ip> with the actual values provided in the previous step:
curl -X POST -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "textMessage": { "text": "Hello, doctors!" }, "phoneNumbers": ["+19162255887", "+19162255888"] }' \
http://<device_local_ip>:8080/message
Alternatively, you can use the CLI Tool:
smsgate -e 'http://<device_local_ip>:8080/message' -u <username> -p <password> \
send --phones '+19162255887,+19162255888' 'Hello, doctors!'
Use the cloud server mode when dealing with dynamic or shared device IP addresses.
Launch the app on your device.
Toggle the Cloud Server switch to the "on" position.
Tap the Online button located at the bottom of the screen to connect to the cloud server.
In the Cloud Server section, the credentials for basic authentication will be displayed.
To send a message via the cloud server, perform a curl request with a command similar to the following, substituting <username> and <password> with the actual values obtained in step 4:
curl -X POST -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "textMessage": { "text": "Hello, doctors!" }, "phoneNumbers": ["+19162255887", "+19162255888"] }' \
https://api.sms-gate.app/3rdparty/v1/message
Or with CLI:
smsgate -u <username> -p <password> \
send --phones '+19162255887,+19162255888' 'Hello, doctors!'
For further privacy, you can deploy your own private server. See the Private Server section for more details.
Use webhooks to receive notifications for messaging events (e.g., incoming SMS and MMS).
| Event | Description |
|---|---|
sms:received |
Triggered when an SMS message is received |
sms:sent |
Triggered when an SMS message is sent |
sms:delivered |
Triggered when an SMS message is delivered |
sms:failed |
Triggered when an SMS message fails to send |
sms:data-received |
Triggered when a data SMS is received |
mms:received |
Triggered when an MMS notification is received (before download) |
mms:downloaded |
Triggered when an MMS message is fully downloaded with body and attachments |
system:ping |
Periodic heartbeat event |
Follow these steps to set up webhooks:
Set up your own HTTP server with a valid SSL certificate to receive webhooks. For testing purposes, webhook.site can be useful.
Register your webhook with an API request:
curl -X POST -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "id": "unique-id", "url": "https://webhook.site/<your-uuid>", "event": "sms:received" }' \
http://<device_local_ip>:8080/webhooks
Send an SMS to the device.
The application will dispatch POST request to the specified URL with a payload such as:
{
"event": "sms:received",
"payload": {
"messageId": "msg_12345abcde",
"message": "Received SMS text",
"phoneNumber": "+19162255887",
"simNumber": 1,
"receivedAt": "2024-06-07T11:41:31.000+07:00"
}
}
To deregister a webhook, execute a curl request using the following pattern:
curl -X DELETE -u <username>:<password> \
http://<device_local_ip>:8080/webhooks/unique-id
For cloud mode the process is similar, simply change the URL to https://api.sms-gate.app/3rdparty/v1/webhooks. Webhooks in Local and Cloud mode are independent.
Note: Webhooks are transmitted directly from the device; therefore, the device must have an outgoing internet connection. As the requests originate from the device, incoming messages remain inaccessible to us.
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)Distributed under the Apache-2.0 license. See LICENSE for more information.
If you have any questions or suggestions, feel free to reach out through the following channels: