SMS Gateway for Android (capcom6/android-sms-gateway)

SMS Gateway for Android

https://github.com/capcom6/android-sms-gateway
Admin
Turns your Android smartphone into an SMS gateway, allowing you to send and receive messages...

Tokens:12,633
Snippets:83
Trust Score:8.5
Update:2 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# SMS Gateway for Android

SMS Gateway for Android is an open-source application that transforms your Android smartphone into a fully-functional SMS gateway. It enables programmatic sending and receiving of SMS messages via a REST API, making it ideal for integrating SMS functionality into applications, services, or automation workflows. The gateway supports both local server mode (running directly on the device) and cloud server mode for scenarios with dynamic IP addresses.

The application provides comprehensive features including multipart message support, real-time message status tracking, webhook notifications for incoming SMS/MMS, end-to-end encryption, multiple SIM card support, and multi-device connectivity. It requires Android 5.0 (Lollipop) or above and offers both secure (production) and insecure (development) build variants.

## Send SMS Message

Enqueues a message for sending to one or more recipients. When `deviceId` is specified, that device is used; otherwise a random registered device is chosen. Supports text messages, data messages, encryption, delivery reports, and message priority levels.

```bash
# Send a simple text SMS to multiple recipients
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "textMessage": {
      "text": "Hello, this is a test message!"
    },
    "phoneNumbers": ["+19162255887", "+19162255888"]
  }' \
  http://192.168.1.100:8080/messages

# Response (202 Accepted):
{
  "id": "PyDmBQZZXYmyxMwED8Fzy",
  "deviceId": "ABC123XYZ",
  "state": "Pending",
  "recipients": [
    {"phoneNumber": "+19162255887", "state": "Pending"},
    {"phoneNumber": "+19162255888", "state": "Pending"}
  ]
}

# Send with specific SIM card, delivery report, and TTL
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-custom-id-123",
    "textMessage": {
      "text": "Priority message with delivery confirmation"
    },
    "phoneNumbers": ["+19162255887"],
    "simNumber": 1,
    "withDeliveryReport": true,
    "ttl": 3600,
    "priority": 100
  }' \
  https://api.sms-gate.app/3rdparty/v1/messages

# Send a data SMS (binary payload)
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "dataMessage": {
      "data": "SGVsbG8gV29ybGQh",
      "port": 53739
    },
    "phoneNumbers": ["+19162255887"]
  }' \
  http://192.168.1.100:8080/messages
```

## Get Message Status

Returns the current state of a previously sent message by its ID. The state progresses through: Pending -> Processed -> Sent -> Delivered (or Failed). Use this endpoint to track message delivery status.

```bash
# Get status of a specific message
curl -X GET -u "username:password" \
  http://192.168.1.100:8080/messages/PyDmBQZZXYmyxMwED8Fzy

# Response (200 OK):
{
  "id": "PyDmBQZZXYmyxMwED8Fzy",
  "deviceId": "ABC123XYZ",
  "state": "Delivered",
  "isEncrypted": false,
  "isHashed": false,
  "recipients": [
    {"phoneNumber": "+19162255887", "state": "Delivered"},
    {"phoneNumber": "+19162255888", "state": "Sent"}
  ],
  "states": {
    "2024-01-15T10:30:00Z": "Pending",
    "2024-01-15T10:30:01Z": "Processed",
    "2024-01-15T10:30:02Z": "Sent",
    "2024-01-15T10:30:05Z": "Delivered"
  }
}
```

## List Messages

Retrieves a paginated list of messages with optional filtering by date range, state, and device. Supports pagination via limit and offset parameters.

```bash
# Get all messages with default pagination
curl -X GET -u "username:password" \
  "http://192.168.1.100:8080/messages"

# Get messages with filters and pagination
curl -X GET -u "username:password" \
  "http://192.168.1.100:8080/messages?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&state=Delivered&limit=100&offset=0&includeContent=true"

# Response (200 OK):
[
  {
    "id": "msg1",
    "deviceId": "ABC123XYZ",
    "state": "Delivered",
    "recipients": [{"phoneNumber": "+19162255887", "state": "Delivered"}],
    "textMessage": {"text": "Hello World"}
  },
  {
    "id": "msg2",
    "deviceId": "ABC123XYZ",
    "state": "Failed",
    "recipients": [{"phoneNumber": "+19162255888", "state": "Failed", "error": "timeout"}]
  }
]
```

## Register Webhook

Registers a webhook to receive HTTP POST notifications for specified events. Webhooks are sent directly from the device, so the device must have internet connectivity. If a webhook with the same ID exists, it will be replaced.

```bash
# Register webhook for incoming SMS
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "webhook-sms-received",
    "url": "https://your-server.com/webhooks/sms",
    "event": "sms:received"
  }' \
  http://192.168.1.100:8080/webhooks

# Response (201 Created):
{
  "id": "webhook-sms-received",
  "url": "https://your-server.com/webhooks/sms",
  "event": "sms:received"
}

# Register webhook for message delivery confirmation
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "webhook-delivery",
    "url": "https://your-server.com/webhooks/delivery",
    "event": "sms:delivered",
    "deviceId": "ABC123XYZ"
  }' \
  https://api.sms-gate.app/3rdparty/v1/webhooks

# Webhook payload for sms:received event:
{
  "id": "event-123",
  "webhookId": "webhook-sms-received",
  "deviceId": "ABC123XYZ",
  "event": "sms:received",
  "payload": {
    "messageId": "msg_12345abcde",
    "message": "Incoming SMS text content",
    "phoneNumber": "+19162255887",
    "sender": "+19162255887",
    "recipient": null,
    "simNumber": 1,
    "receivedAt": "2024-01-15T10:30:00Z"
  }
}

# Webhook payload for mms:downloaded event:
{
  "id": "event-456",
  "webhookId": "webhook-mms",
  "deviceId": "ABC123XYZ",
  "event": "mms:downloaded",
  "payload": {
    "messageId": "mms_67890",
    "phoneNumber": "+19162255887",
    "subject": "Photo from vacation",
    "body": "Check out this picture!",
    "receivedAt": "2024-01-15T10:35:00Z",
    "attachments": [
      {
        "partId": 1,
        "contentType": "image/jpeg",
        "name": "photo.jpg",
        "size": 102400,
        "data": "base64-encoded-content..."
      }
    ]
  }
}
```

## List and Delete Webhooks

Retrieve all registered webhooks or delete a specific webhook by ID. Webhooks in Local and Cloud mode are independent.

```bash
# List all registered webhooks
curl -X GET -u "username:password" \
  http://192.168.1.100:8080/webhooks

# Response (200 OK):
[
  {
    "id": "webhook-sms-received",
    "url": "https://your-server.com/webhooks/sms",
    "event": "sms:received"
  },
  {
    "id": "webhook-delivery",
    "url": "https://your-server.com/webhooks/delivery",
    "event": "sms:delivered",
    "deviceId": "ABC123XYZ"
  }
]

# Delete a webhook
curl -X DELETE -u "username:password" \
  http://192.168.1.100:8080/webhooks/webhook-sms-received

# Response: 204 No Content
```

## List Devices

Returns a list of all registered devices associated with your account. Useful for multi-device setups to identify which devices are available for sending messages.

```bash
# List all devices
curl -X GET -u "username:password" \
  https://api.sms-gate.app/3rdparty/v1/devices

# Response (200 OK):
[
  {
    "id": "PyDmBQZZXYmyxMwED8Fzy",
    "name": "My Device",
    "createdAt": "2024-01-01T00:00:00Z",
    "lastSeen": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "ABC123XYZ456",
    "name": "Office Phone",
    "createdAt": "2024-01-10T00:00:00Z",
    "lastSeen": "2024-01-15T09:00:00Z"
  }
]

# Remove a device
curl -X DELETE -u "username:password" \
  https://api.sms-gate.app/3rdparty/v1/devices/PyDmBQZZXYmyxMwED8Fzy

# Response: 204 No Content
```

## Get Incoming Messages (Inbox)

Retrieves incoming messages (SMS, Data SMS, MMS) with filtering and pagination. Returns messages received by the device with optional type filtering.

```bash
# Get all incoming messages
curl -X GET -u "username:password" \
  "http://192.168.1.100:8080/inbox"

# Get incoming SMS messages with filters
curl -X GET -u "username:password" \
  "http://192.168.1.100:8080/inbox?type=SMS&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&limit=50&offset=0"

# Response (200 OK):
# Header: X-Total-Count: 125
[
  {
    "id": "inbox_123",
    "type": "SMS",
    "sender": "+19162255887",
    "recipient": "+19162255000",
    "contentPreview": "Hello, how are you?",
    "simNumber": 1,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "inbox_124",
    "type": "MMS_DOWNLOADED",
    "sender": "+19162255888",
    "contentPreview": "Photo attachment",
    "simNumber": 2,
    "createdAt": "2024-01-15T10:35:00Z"
  }
]

# Refresh inbox (re-sync messages from device)
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "PyDmBQZZXYmyxMwED8Fzy",
    "since": "2024-01-01T00:00:00Z",
    "until": "2024-01-31T23:59:59Z"
  }' \
  http://192.168.1.100:8080/inbox/refresh

# Response: 202 Accepted
```

## Health Check Endpoints

System health endpoints for monitoring service status, useful for Kubernetes probes and monitoring systems.

```bash
# Readiness probe (is service ready to serve traffic)
curl -X GET http://192.168.1.100:8080/health

# Response (200 OK):
{
  "status": "pass",
  "version": "1.0.0",
  "releaseId": 1,
  "checks": {
    "database": {
      "status": "pass",
      "description": "Database connection healthy"
    }
  }
}

# Liveness probe (is service running)
curl -X GET http://192.168.1.100:8080/health/live

# Startup probe (has initialization completed)
curl -X GET http://192.168.1.100:8080/health/startup

# Ready probe
curl -X GET http://192.168.1.100:8080/health/ready
```

## Get and Update Settings

Retrieve or update device settings including encryption, gateway configuration, message limits, and webhook settings.

```bash
# Get current settings
curl -X GET -u "username:password" \
  http://192.168.1.100:8080/settings

# Response (200 OK):
{
  "encryption": {
    "passphrase": null
  },
  "gateway": {
    "cloud_url": "https://api.sms-gate.app",
    "notification_channel": "AUTO"
  },
  "messages": {
    "limit_period": "PerHour",
    "limit_value": 100,
    "log_lifetime_days": 30,
    "processing_order": "FIFO",
    "send_interval_min": 1,
    "send_interval_max": 5,
    "sim_selection_mode": "RoundRobin"
  },
  "webhooks": {
    "internet_required": true,
    "retry_count": 3
  },
  "logs": {
    "lifetime_days": 7
  },
  "ping": {
    "interval_seconds": 60
  }
}

# Partially update settings (PATCH)
curl -X PATCH -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": {
      "limit_period": "PerDay",
      "limit_value": 500,
      "sim_selection_mode": "Random"
    }
  }' \
  http://192.168.1.100:8080/settings

# Replace all settings (PUT)
curl -X PUT -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": {
      "limit_period": "PerHour",
      "limit_value": 100
    },
    "webhooks": {
      "retry_count": 5
    }
  }' \
  http://192.168.1.100:8080/settings
```

## Authentication Token Management

Generate, refresh, and revoke JWT tokens for API authentication. Useful for creating scoped access tokens with limited permissions.

```bash
# Generate a new access token
curl -X POST -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["messages:send", "messages:read"],
    "ttl": 3600
  }' \
  https://api.sms-gate.app/3rdparty/v1/auth/token

# Response (201 Created):
{
  "id": "jwt-id-123",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "refresh-token-abc...",
  "token_type": "Bearer",
  "expires_at": "2024-01-15T11:30:00Z"
}

# Use the JWT token for subsequent requests
curl -X GET \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.sms-gate.app/3rdparty/v1/messages

# Refresh an access token
curl -X POST \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.sms-gate.app/3rdparty/v1/auth/token/refresh

# Revoke a token
curl -X DELETE -u "username:password" \
  https://api.sms-gate.app/3rdparty/v1/auth/token/jwt-id-123

# Response: 204 No Content
```

## Get Logs

Retrieve application log entries for debugging and monitoring. Logs include context information for troubleshooting issues.

```bash
# Get logs within a time range
curl -X GET -u "username:password" \
  "http://192.168.1.100:8080/logs?from=2024-01-15T00:00:00Z&to=2024-01-15T23:59:59Z"

# Response (200 OK):
[
  {
    "id": 1,
    "priority": "INFO",
    "module": "gateway",
    "message": "Device registered successfully",
    "createdAt": "2024-01-15T10:00:00Z",
    "context": {
      "deviceId": "PyDmBQZZXYmyxMwED8Fzy"
    }
  },
  {
    "id": 2,
    "priority": "ERROR",
    "module": "sms",
    "message": "Failed to send message",
    "createdAt": "2024-01-15T10:30:00Z",
    "context": {
      "messageId": "msg_123",
      "error": "Network timeout"
    }
  }
]
```

## Summary

SMS Gateway for Android is designed for integration scenarios requiring programmatic SMS capabilities without relying on third-party SMS providers. Primary use cases include two-factor authentication systems, transactional notifications, appointment reminders, user verification flows, and IoT device communication via Data SMS. The gateway excels in scenarios where you need full control over your SMS infrastructure, want to avoid per-message costs from SMS providers, or require messages to originate from a real phone number.

Integration patterns typically involve either direct API calls for synchronous message sending or webhook-based architectures for receiving and processing incoming messages. For production deployments, the cloud server mode is recommended when devices have dynamic IPs, while local server mode suits fixed network environments. Multi-device setups can distribute message load across several phones, and the message queue with priority levels ensures critical messages bypass rate limits. End-to-end encryption can be enabled for sensitive communications, ensuring message content remains private even when using the cloud relay server.