capcom6/android-sms-gateway

An Android SMS Gateway app that enables sending SMS messages via a local or cloud server API

Android SMS Gateway

Turns your smartphone into an SMS gateway for sending messages via API.
Explore the docs »

Report Bug · Request Feature

• About The Project
  • Features
  • Ideal For
  • Built With
• Installation
  • Prerequisites
    • Permissions
  • Installation from APK
• Getting Started
  • Local server
  • Cloud server
• Roadmap
• Contributing
• License
• Contact

About The Project

Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application allowing you to send SMS messages programmatically via API. This makes it ideal for integrating SMS functionality into your own applications or services.

Features

• No registration: No registration or email is required to create an account. In local mode you don't need an account at all!
• Send SMS by API: Use our API to send messages directly from your own applications or services.
• Supports Android 5.0 and above: The application is compatible with Android 5.0 and later versions.
• Message status tracking: Monitor the status of your sent messages in real-time.
• Starts at boot: The application starts running as soon as your device boots up.
• Multiple SIM cards: The application supports multiple SIM cards.
• Multipart messages: The application supports sending long messages with auto-partitioning.
• End-to-end encryption: No one in the middle can access the content and recipients of the messages.

Ideal For

• Notifications
• Alerts
• Two-factor authentication codes

Android SMS Gateway provides a convenient and reliable solution, whether you need to send notifications, alerts, or two-factor authentication codes.

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Installation

You can install app to your device from prebuilt APK or by building from sources.

Prerequisites

You need an Android device with Android 5.0 (Lollipop) or above for using the application.

Permissions

To use the application, you need to grant the following permissions:

• SEND_SMS: This permission is required to send SMS messages.
• READ_PHONE_STATE: This permission is required to select the SIM card. Optional, if you don't want to select the SIM card.

Installation from APK

1. Navigate to the Releases page.
2. Download the latest APK file from the list of available releases.
3. Transfer the APK file to your Android device.
4. On your Android device, go to Settings > Security (or Privacy on some devices).
5. Enable the Unknown sources option to allow installation of apps from sources other than the Play Store.
6. Use a file manager app to navigate to the location of the downloaded APK file.
7. Tap on the APK file to start the installation process.
8. Follow the on-screen prompts to complete the installation.

(back to top)

Getting Started

The Android SMS Gateway can work in two modes: with a local server started on the device or with a cloud server at sms.capcom.me. The basic API is the same for both modes and is documented on the Android SMS Gateway API Documentation.

Local server

This mode is recommended for sending messages from local network.

1. Start the app on the device.

2. Activate the Local server switch.

3. Tap the Offline button at the bottom of the screen.

4. In the Local server section, the local and public addresses of the device, along with the credentials for basic authentication, will be displayed. Please note that the public address is only usable if you have a "white" IP address and have correctly configured your firewall.

5. Make a curl call from the local network using a command like the following, replacing <username>, <password>, and <device_local_ip> with the values obtained in step 4:

   curl -X POST -u <username>:<password> \
     -H "Content-Type: application/json" \
     -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' \
     http://<device_local_ip>:8080/message
   

Cloud server

If you need to send messages with dynamic or shared device IP, you can use the cloud server. The best part? No registration, email, or phone number is required to start using it.

1. Start the app on the device.

2. Activate the Cloud server switch.

3. Tap the Offline button at the bottom of the screen.

4. In the Cloud server section, the credentials for basic authentication will be displayed.

5. Make a curl call using a command like the following, replacing <username> and <password> with the values obtained in step 4:

   curl -X POST -u <username>:<password> \
     -H "Content-Type: application/json" \
     -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' \
     https://sms.capcom.me/api/3rdparty/v1/message
   

For more examples, please refer to the API Documentation

(back to top)

Roadmap

• Add functionality to modify user credentials.
• Introduce option to adjust the local server port.
• Send notifications to an external server when the status of a message changes.
• Incorporate scheduling capabilities for dispatching messages at specific times.
• Implement region-based restrictions to prevent international SMS.
• Provide an API endpoint to retrieve the list of available SIM cards on the device.
• Include detailed error messages in responses and logs.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache-2.0 license. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/capcom6/android-sms-gateway

(back to top)

android-sms-gateway's Issues

Is it possible to add my own cloud server / tunnel local server with dynamic ip?

Or at least tunnel the localhosted server somehow? I use 4g sim card internet with dynamic IP address and cannot access my local server from outside. Any solutions?

Update libphonenumber dependency

Hello there..

I'am having an issue while sending to some new phone numbers and I figured out that new format number was published earlier in libphonenumber 8.13.3 and the current used version is 8.12.32..

Upgrading libphonenumber to latest version 8.13.27 will fix that issue.

Endpoint by SSL, date and time of SMS delivery

Thank you for the great project.

Two questions about this:

1. When using the local server, is there a way to secure the access to the endpoint by SSL?

2. Can the date and time of SMS delivery be transmitted in the response, in addition to [state] => Delivered?

on/off delivery report status

add option to off/on delivery report

send by sim2

how select sim for send?(sim1,sim2,..)

Ошибка 404, Not Found

Пробовали через POSTMAN, ниже прикладываем информацию из POSTMAN по запросу

POST http://192.168.1.12:8080/api/message/
404
161 ms
Network
addresses: {…}
local: {…}
address: "192.168.1.25"
family: "IPv4"
port: 51944
remote: {…}
address: "192.168.1.12"
family: "IPv4"
port: 8080
Request Headers
Authorization: Basic c21zOmhEbnRuTTBw
Content-Type: application/json
User-Agent: PostmanRuntime/7.26.8
Accept: /
Cache-Control: no-cache
Postman-Token: bc14e5c4-a457-4b2b-a034-8a86f69bdd5e
Host: 192.168.1.12:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 90
Request Body
{
"id": "1",
"message": "Test sms",
"phoneNumbers": [
"[phone]"
]
}
Response Headers
Content-Length: 0
Connection: keep-alive
Response Body

Phone parsing: Invalid phone number

i keep getting this response on one of the numbers in my app, ive checked the number is it is correct.

POST:
{
"id": "tH5-AUItZNqar8W5_pC8b",
"recipients": [
{
"error": "Phone parsing: Invalid phone number",
"phoneNumber": "0493563919",
"state": "Failed"
}
],
"state": "Pending"
}

GET:
{
"id": "tH5-AUItZNqar8W5_pC8b",
"recipients": [
{
"phoneNumber": "0493563919",
"state": "Failed"
}
],
"state": "Failed"
}

it also fails on "[phone]" but all the other numbers i send to work. great app by the way!

Add message limits

Almost all mobile operators limit the number of SMS messages per day, for example, 100 pcs/day. I would like to add functionality that would take this into account and postpone the message queue until the reset time. That is, two parameters are needed: the limit per day, and the time to reset the limit.

only works with Russians phone numbers !

PhoneHelper will return null if the number is not Russian

Add delays between sends

Thanks for your application, we started using it. Some mobile operators don't like it when messages are sent in batches at once. It would be nice to add functionality when it would be possible to set the delay in seconds/ minutes between sends, and even better, the delay range so that they are random :)

Private cloud/backend

Hi @capcom6 ... I have my own vps and it will be realy cool if you can provide any documentation on how to edit the app so I can use it with my own cloud.BTW great work here thank you for make in it public for us, many thanks

Question. Energy saving by app

Does the application on android need to have power saving mode turned off to run through interruptions ?

RESULT_RIL_MODEM_ERR

When trying to send a text, I get failed and RESULT_RIL_MODEM_ERR in the android app.

Android 12
Kernel 4.9.227
LG Velvet

App version: 1.12.1

Messages and recipients hang in the "Processed" state

Messages and recipients hang in the "Processed" state

If we want to process more messages (e.g. 50), after about 20-30 messages, all other messages will remain in the "Processed" state forever and are not sent at all (tested for 24 hours).

We send this way (encryption is disabled):

1. request a new message from the local phone server (one message to 1-3 recipients, length 200-300 characters)
2. save the ID from the reply
3. wait 5-10 seconds
4. request the message status for the saved ID
5. save status and ID to DB and continue from point 1) for new message

Then, after some time, we again request message statuses for messages that are not in the delivered state in DB.

At that point, the message won't even appear among the sent SMS in Google Messages.

example message status:

   "id":"Ch0CDBaJwhovohric7uG6",
   "isEncrypted":false,
   "recipients":[
      {
         "phoneNumber":"+XXXXXXXXXXXX",
         "state":"Processed"
      }
   ],
   "state":"Processed"
}

"Processed" state for mixed "Sent"/"Delivered"

Another thing I noticed is that if some recipients are in the "Delivered" state and some are in the "Sent" state, the global message state reverts from "Sent" to "Processed", which is a bit confusing, I think it should remain "Sent".

example message status:

   "id":"CAyydF5q4MKsNouxMZjS0",
   "isEncrypted":false,
   "recipients":[
      {
         "phoneNumber":"+XXXXXXXXXXXX",
         "state":"Sent"
      },
      {
         "phoneNumber":"+YYYYYYYYYYYY",
         "state":"Delivered"
      },
      {
         "phoneNumber":"+ZZZZZZZZZZZZ",
         "state":"Delivered"
      }
   ],
   "state":"Processed"
}

Invalid Phone Number

I send some message to my private work number, the number is just 4 number

Failed on multi part messages

send failed on multi part messages.

[Question] How to setup my own cloud

How can I setup my own service on my own domain? Is it possible to do that?

Basically, I don't want to use this sms.capcom.me ... I want to use my own domain.

Long numbers

I'm having Bad request using this number:

[phone]

Is it too long?

same phone as sms and wifi gateway/router works!

Amazing program.
I'm just here to tell that if you want to use the same phone as sms gateway and wifi gateway/router, it works, although this program does not tell you the local ip.
My use case is that I need to send sms message even when electricity fail so I need wifi network to be active (and sms gateway to) this is easier if one device do it all and for that using the same phone is ideal.

Activate tethering on the phone and connect to the wifi network the phone create. The only "issue" is that android-sms-gateway don't tell you the local IP so you need to discover it.
In esp I use
WiFi.gatewayIP().toString();
from
#include <WiFi.h>
after I connect to the phone wifi network.

Adding an API GET to read received SMS

Hello,

Thanks for your nice project. Do you think you can add an option to read received SMS? It is useful when someone answers to the automated SMS or to ask a question and retrieve automatically the answer.

Error on phone number

Hello, trying to make shipments using the cload service but it always tells me that the number is wrong... but I already checked and it is correct.

usage +55 = Country code
and the rest of the phone

Contribution to install Private Server

This example is using a VPS Ubuntu 22.xx with dedicated IP and a subdomain pointing to the IP

1.- Have a Virtual Machine with docker and docker compose
To install you can use these tutorials:
https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04
https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04

2.- Create a docker-compose.yaml file (SMS - MySQL - nginx) - you can use this example and adapt it to your liking
docker-compose.yaml.txt

3.- create a config.yml file (you can use the administrator guide at https://sms.capcom.me/getting-started/private-server/)
config.yml.txt

4.- Upload these files to the server (create a preferred folder)

5.- enter the server via putty using cd /[dir-create] and execute the command "docker compose up -d"

6.- When finished, enter server-ip:81 via web to enter the nginx administrator and use the data:
Email: [email protected]
Password: changeme

7.- Change service access and configure a new proxy host

8.- If everything went well you will be able to see that the service is active.

9.- do not forget to configure the URL and Token in the APP

10.- We tested our service with postman.

11.- and the test sms will arrive where we indicate

I hope it helps you, if you have questions you can read the documentation or comment to add more details.

PS: All rights and thanks to the creator of this service, it is useful for my business.