repository·master·Indexed 26 days ago
https://github.com/capcom6/android-sms-gatewayA programmable SMS gateway that turns an Android smartphone into a gateway for sending and receiving SMS, MMS, and Data SMS via APIs, CLI tools, and webhooks. It supports Local Server and Cloud Server modes, end-to-end encryption, and real-time event notifications for 2FA, transactional messaging, and IoT commands. Requires Android 5.0 or above.
The project offers two pre-built variants:
Webhooks allow you to receive POST notifications for messaging events (SMS/MMS) directly from the device.
sms:received: SMS message receivedsms:sent: SMS message sentsms:delivered: SMS message deliveredsms:failed: SMS message failed to sendsms:data-received: Data SMS receivedmms:received: MMS notification received (before download)mms:downloaded: MMS fully downloaded with body and attachmentssystem:ping: Periodic heartbeat/webhooks endpoint (use http://<device_local_ip>:8080/webhooks for Local mode or https://api.sms-gate.app/3rdparty/v1/webhooks for Cloud mode)./webhooks/<unique-id>.Note: The device must have an outgoing internet connection to dispatch webhooks.
# Register a webhook
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
# Deregister a webhook
curl -X DELETE -u <username>:<password> \
http://<device_local_ip>:8080/webhooks/unique-idTo install the application on an Android device:
https://github.com/capcom6/android-sms-gateway/releasesCloud Server mode is used when dealing with dynamic or shared device IP addresses.
Cloud Server switch to "on".Online button to connect to the cloud server.<username> and <password>) from the Cloud Server section in the app.To send a message, use a curl command or the CLI tool targeting the cloud API endpoint.
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/messageLocal Server mode is ideal for sending messages from within a local network.
Local Server switch to "on".Offline button to activate the server.<username> and <password>) from the Local Server section in the app.To send a message, use a curl command or the CLI tool targeting the device's local IP on port 8080.
curl -X POST -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "textMessage": { "text": "Hello, doctors!" }, "phoneNumbers": ["+19162255887", "+19162255888"] }' \
http://<device_local_ip>:8080/messageTo function correctly, the app requires or benefits from the following permissions:
| Permission | Requirement | Purpose |
|---|---|---|
SEND_SMS | Required | Required to send SMS messages. |
READ_PHONE_STATE | Optional | Allows selecting specific SIM cards. |
READ_SMS | Optional | Allows reading previously received SMS messages. |
RECEIVE_SMS | Optional | Required to trigger webhooks on incoming SMS. |
RECEIVE_MMS | Optional | Required to trigger webhooks on incoming MMS. |
RECEIVE_WAP_PUSH | Optional | Required to trigger webhooks on incoming MMS. |
When a webhook event is triggered, the application dispatches a POST request with a JSON payload. Example for sms:received:
{
"event": "sms:received",
"payload": {
"messageId": "msg_12345abcde",
"message": "Received SMS text",
"phoneNumber": "+19162255887",
"simNumber": 1,
"receivedAt": "2024-06-07T11:41:31.000+07:00"
}
}The InboxMessage sealed class is the base type for all incoming messages. It contains common properties for any received message: address (sender), date (timestamp), and an optional subscriptionId (SIM card identifier).
Depending on the message type, you can use one of the following subclasses:
Text: For standard SMS text messages. Contains a text string.Data: For binary data messages. Contains a data byte array.MmsHeaders: Metadata for an MMS message. Contains messageId, transactionId, subject, size, and contentClass.MMS: For Multimedia messages. Contains messageId, body, subject, and a list of Attachment objects.When consuming webhooks from the Android SMS Gateway, SMS event notifications are delivered using one of several specialized payload classes derived from SmsEventPayload. These payloads provide details about the lifecycle of an SMS message (sent, delivered, failed, received, etc.).
Common fields across all payloads include:
messageId: Unique identifier for the message.sender: The sender's phone number.recipient: The recipient's phone number.simNumber: The index of the SIM card used (if applicable).phoneNumber: The primary phone number associated with the event (either sender or recipient depending on the event type).// Available SmsEventPayload subclasses:
class SmsSent(
messageId: String,
sender: String?,
recipient: String,
simNumber: Int?,
val partsCount: Int,
val sentAt: Date
)
class SmsDelivered(
messageId: String,
sender: String?,
recipient: String,
simNumber: Int?,
val deliveredAt: Date
)
class SmsFailed(
messageId: String,
sender: String?,
recipient: String,
simNumber: Int?,
val failedAt: Date,
val reason: String
)
class SmsReceived(
messageId: String,
sender: String,
recipient: String?,
simNumber: Int?,
val message: String,
val receivedAt: Date
)
class SmsDataReceived(
messageId: String,
sender: String,
recipient: String?,
simNumber: Int?,
val data: String,
val receivedAt: Date
)
class SmsCancelled(
messageId: String,
sender: String?,
recipient: String,
simNumber: Int?,
val cancelledAt: Date
)When handling an MMS type InboxMessage, you can access its multimedia components through the attachments list. Each Attachment object provides details about a specific part of the MMS:
partId: Unique identifier for the part.contentType: The MIME type of the attachment (e.g., image/jpeg).name: The filename of the attachment.size: The size of the attachment in bytes.data: The attachment content represented as a string.