SMS Gateway for Android

https://docs.sms-gate.app
Admin
SMS Gateway for Android turns your Android smartphone into an SMS and MMS gateway, allowing you to...
Tokens:81,889
Snippets:342
Trust Score:6.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install CLI on Linux

Source: https://docs.sms-gate.app/integration/cli

Downloads and installs the binary for Linux x86_64 systems.

```bash
curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Linux_x86_64.tar.gz
tar -xzf smsgate_Linux_x86_64.tar.gz
chmod +x smsgate
sudo mv smsgate /usr/local/bin/smsgate
```

--------------------------------

### Install CLI via Go

Source: https://docs.sms-gate.app/integration/cli

Installs the CLI tool using the Go package manager.

```bash
go install github.com/android-sms-gateway/cli@latest
```

--------------------------------

### Send Message Examples

Source: https://docs.sms-gate.app/integration/cli

Various examples demonstrating how to send messages with different options like multiple recipients, device selection, and priority.

```bash
# Send a simple text message
smsgate send --phones '+12025550123' 'Hello, Dr. Turk!'

# Send to multiple numbers
smsgate send --phones '+12025550123' --phones '+12025550124' 'Hello, doctors!'

# Send with explicit device selection
smsgate send --phones '+12025550123' --device-id device123 'Message'

# Send with SIM number selection (1-based)
smsgate send --phones '+12025550123' --sim-number 2 'Message'

# Send with priority (>=100 bypasses limits)
smsgate send --phones '+12025550123' --priority 100 'Urgent message'

# Send with time-to-live (TTL)
smsgate send --phones '+12025550123' --ttl 1h30m 'Expiring message'

# Send with expiration date (RFC3339 format)
smsgate send --phones '+12025550123' --valid-until '2027-12-31T23:59:59Z' 'Message'

# Disable delivery report
smsgate send --phones '+12025550123' --delivery-report=false 'Message'

# Skip phone number validation
smsgate send --phones '+12025550123' --skip-phone-validation 'Message'
```

--------------------------------

### Install CLI on macOS

Source: https://docs.sms-gate.app/integration/cli

Downloads and installs the binary for Apple Silicon macOS systems.

```bash
curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Darwin_arm64.tar.gz
tar -xzf smsgate_Darwin_arm64.tar.gz
chmod +x smsgate
sudo mv smsgate /usr/local/bin/smsgate
```

--------------------------------

### Download Configuration Template

Source: https://docs.sms-gate.app/getting-started/private-server

Use wget to download the example configuration file for customization.

```bash
wget https://raw.githubusercontent.com/android-sms-gateway/server/master/configs/config.example.yml -O config.yml
```

--------------------------------

### Install SMS Gateway Helm Chart

Source: https://docs.sms-gate.app/features/private-server

Installs or upgrades the SMS Gateway Helm chart, creating a namespace if it doesn't exist.

```bash
helm upgrade --install sms-gate-server sms-gate/server \
    --create-namespace \
    --namespace sms-gate \
    --values values.yaml

```

--------------------------------

### Get Device List with Activity Status

Source: https://docs.sms-gate.app/blog/2025/08/05/optimizing-device-selection-with-deviceactivewithin

This example shows how to retrieve a list of devices and their last seen timestamps, which can be used to determine appropriate `deviceActiveWithin` values.

```APIDOC
## GET /3rdparty/v1/devices

### Description
Retrieves a list of all registered devices along with their last seen timestamps. This information is useful for understanding device activity patterns and setting effective `deviceActiveWithin` thresholds.

### Method
GET

### Endpoint
`/3rdparty/v1/devices`

### Parameters
None

### Request Example
```bash
curl -X GET https://api.sms-gate.app/3rdparty/v1/devices \
  -u "${SMSGATE_USER}:${SMSGATE_PASS}"
```

### Response
#### Success Response (200)
- **devices** (array of objects) - A list of device objects.
  - **id** (string) - The unique identifier of the device.
  - **name** (string) - The name of the device.
  - **lastSeen** (string) - The timestamp of the last activity for the device in ISO 8601 format (e.g., "2025-08-05T06:30:45Z").

#### Response Example
```json
[
  {
    "id": "yVULogr4Y1ksRfnos1Dsw",
    "name": "Primary Device",
    "lastSeen": "2025-08-05T06:30:45Z"
  }
]
```
```

--------------------------------

### Private Server Configuration Example

Source: https://docs.sms-gate.app/getting-started/private-server

Example configuration for a private SMS-Gate server. Key sections to edit include gateway mode, private token, HTTP listen address, and database credentials.

```yaml
gateway:
    mode: private
    private_token: your-secure-token-here 
http:
    listen: 0.0.0.0:3000
database: 
    host: localhost
    port: 3306
    user: root
    password: root
    database: sms
    timezone: UTC
```

--------------------------------

### Configure .env File

Source: https://docs.sms-gate.app/integration/cli

Example of setting environment variables for CLI authentication and endpoint configuration.

```text
ASG_ENDPOINT="https://api.sms-gate.app/3rdparty/v1"
ASG_USERNAME="your_username"
ASG_PASSWORD="your_password"
```

--------------------------------

### Install CLI on Windows

Source: https://docs.sms-gate.app/integration/cli

Downloads and extracts the binary for Windows systems using PowerShell.

```powershell
Invoke-WebRequest https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Windows_x86_64.zip -OutFile smsgate.zip
Expand-Archive smsgate.zip
```

--------------------------------

### Code Examples

Source: https://docs.sms-gate.app/blog/2025/08/07/mastering-message-retrieval-a-developers-guide-to-get-messages-api

Real-world code examples for retrieving SMS messages using Python, Node.js (JavaScript), and cURL.

```APIDOC
## Code Examples

### Python Requests
```python
import requests
from datetime import datetime, timedelta

# Configure for your environment
BASE_URL = "http://localhost:8080"  # Local
# BASE_URL = "https://api.sms-gate.app/3rdparty/v1"  # Cloud
AUTH = ("your_username", "your_password")

# Get messages from last hour
one_hour_ago = (datetime.utcnow() - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
params = {
    "from": one_hour_ago,
    "limit": 10
}

response = requests.get(
    f"{BASE_URL}/messages",
    auth=AUTH,
    params=params
)

if response.status_code == 200:
    messages = response.json()
    total = response.headers.get('X-Total-Count')
    print(f"Retrieved {len(messages)} of {total} messages")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Node.js Axios
```javascript
const axios = require('axios');
const { DateTime } = require('luxon');

// Configure for your environment
const BASE_URL = 'http://localhost:8080'; // Local
// const BASE_URL = 'https://api.sms-gate.app/3rdparty/v1'; // Cloud
const auth = { username: 'your_username', password: 'your_password' };

// Get messages from last hour
const oneHourAgo = DateTime.utc().minus({ hours: 1 }).toISO();
const params = {
  from: oneHourAgo,
  limit: 10
};

axios.get(`${BASE_URL}/messages`, { auth, params })
  .then(response => {
    console.log(`Retrieved ${response.data.length} of ${response.headers['x-total-count']} messages`);
    // Process messages
  })
  .catch(error => {
    console.error(`Error ${error.response?.status}: ${error.response?.data}`);
  });
```

### cURL
```bash
# Local server example
curl -u user:pass "http://localhost:8080/messages?limit=10"
```
```

--------------------------------

### Example Response from GET /messages

Source: https://docs.sms-gate.app/blog/2025/08/07/mastering-message-retrieval-a-developers-guide-to-get-messages-api

A successful request to the GET /messages endpoint returns a JSON array of message objects. The X-Total-Count header indicates the total number of available messages.

```json
[
  {
    "id": "I6gSljKlTN3Fe-BJpEcrE",
    "deviceId": "uCh54LY9eovMomc2Un2eU",
    "state": "Pending",
    "isHashed": false,
    "isEncrypted": false,
    "recipients": [
      {
        "phoneNumber": "+1234567890",
        "state": "Pending",
        "error": null
      }
    ],
    "states": {
      "Pending": "2025-07-15T12:30:45Z"
    }
  }
]

```

--------------------------------

### Worker Configuration Example

Source: https://docs.sms-gate.app/features/private-server

Example configuration for the SMS Gateway worker, specifying database connection details and task intervals for cleanup and hashing.

```yaml
http:
  listen: :3000  # Metrics endpoint
database:
  host: localhost
  port: 3306
  user: root
  password: root
  database: sms
  timezone: UTC
tasks:
  devices_cleanup:
    interval: 24h
    max_age: 720h  # 30 days
  messages_cleanup:
    interval: 24h
    max_age: 720h  # 30 days
  messages_hashing:
    interval: 168h  # 7 days

```

--------------------------------

### Run Locally

Source: https://docs.sms-gate.app/services/twilio-fallback

Execute this command to run the Twilio Fallback Service locally after installation.

```bash
./twilio-fallback

```

--------------------------------

### Python Input Validation Example

Source: https://docs.sms-gate.app/integration/get-to-post

A basic Python snippet demonstrating input validation for a phone number, ensuring it starts with a '+'.

```python
if not to_phone.startswith('+'):
    return invalid_number_error()

```

--------------------------------

### Migration Path Examples

Source: https://docs.sms-gate.app/blog/category/webhooks

Comparison between current backward-compatible payloads and future payloads after the deprecation period.

```json
{
  "sender": "+1234567890",
  "recipient": "+9876543210",
  "phoneNumber": "+1234567890"  // Still works!
}
```

```json
{
  "sender": "+1234567890",
  "recipient": "+9876543210"
  // phoneNumber removed in future major version
}
```

--------------------------------

### Batch Send Examples

Source: https://docs.sms-gate.app/integration/cli

Common usage patterns for batch sending via CSV and Excel files.

```bash
# Basic batch send
smsgate batch send --map phone=Phone,text=Message contacts.csv

# Excel with custom sheet and no headers
smsgate batch send --sheet "Summer Campaign" --header=false --map phone=col_1,text=col_2 campaign.xlsx

# High concurrency with error continuation
smsgate batch send --map phone=Phone,text=Message --concurrency=10 --continue-on-error large_list.csv

# Send with device and SIM selection
smsgate batch send --map phone=Phone,text=Message,device_id=Device,sim_number=SIM device_specific.csv

# Priority-based sending
smsgate batch send --map phone=Phone,text=Message,priority=Priority priority_campaign.csv
```

--------------------------------

### Example JWT Token

Source: https://docs.sms-gate.app/blog/2025/12/10/securing-your-sms-gateway-migrating-from-basic-auth-to-jwt

A sample JWT token structure.

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwic2NvcGVzIjpbIm1lc3NhZ2VzOnNlbmQiXSwiZXhwIjoxNzMzNzg1MjAwfQ.signature_here
```

--------------------------------

### Webhook Integration Patterns

Source: https://docs.sms-gate.app/blog/category/api

Examples for handling new and existing webhook integrations, including migration to the updated payload structure.

```javascript
app.post('/webhook', (req, res) => {
  const { sender, recipient, message } = req.body.payload;

  console.log(`Message from ${sender} to ${recipient || 'unknown'}`);

  // Your business logic here

  res.sendStatus(200);
});
```

```javascript
// Old code still works
app.post('/webhook', (req, res) => {
  const { phoneNumber, message } = req.body.payload;

  console.log(`Message from ${phoneNumber}`);

  res.sendStatus(200);
});
```

```javascript
// Enhanced code with new fields
app.post('/webhook', (req, res) => {
  const { sender, recipient, message } = req.body.payload;

  // Use sender (explicit) instead of phoneNumber (ambiguous)
  console.log(`Message from ${sender} to ${recipient || 'unknown'}`);

  res.sendStatus(200);
});
```

--------------------------------

### Batch Send Output and Progress

Source: https://docs.sms-gate.app/integration/cli

Examples of summary output and real-time progress tracking during batch operations.

```text
Batch send summary: total=100 enqueued=95 failed=3 skipped=2
```

```text
[4] 019d1950-ae49-7501-a48f-44dad39a6dd0: Pending
[9] 019d1950-ae49-7599-b103-2f8a321747c0: Pending
[8] 019d1950-ae49-751c-9b17-ba92a2eda9b7: Pending
...
```

--------------------------------

### Backward Compatible Payload Example (Phase 1)

Source: https://docs.sms-gate.app/blog/category/features

This example shows the payload structure during Phase 1, which is backward compatible and includes the deprecated `phoneNumber` field alongside `sender` and `recipient`.

```json
{
  "sender": "+1234567890",
  "recipient": "+9876543210",
  "phoneNumber": "+1234567890"  // Still works!
}
```

--------------------------------

### Sample Device Listing Response

Source: https://docs.sms-gate.app/blog/2025/07/20/targeting-messages-to-specific-devices

Example response from the device listing API, showing device IDs, names, and last seen timestamps.

```json
[
  {
    "id": "yVULogr4Y1ksRfnos1Dsw",
    "name": "Samsung Galaxy S23",
    "lastSeen": "2025-07-20T08:30:45Z"
  },
  {
    "id": "GhYSOK_rNnjPUzDyV2E-u",
    "name": "Google Pixel 7",
    "lastSeen": "2025-07-20T07:15:22Z"
  }
]
```

--------------------------------

### CSV File Formats

Source: https://docs.sms-gate.app/integration/cli

Examples of CSV file structures for batch messaging with and without headers.

```text
Phone,Message,Device,Priority
+12025550123,"Hello Dr. Turk!",device1,1
+12025550124,"Hello Dr. Smith!",device1,2
+12025550125,"Hello Dr. Jones!",device2,1
```

```text
+12025550123,"Hello Dr. Turk!",device1,1
+12025550124,"Hello Dr. Smith!",device1,2
+12025550125,"Hello Dr. Jones!",device2,1
```

--------------------------------

### Configure JWT Token TTL

Source: https://docs.sms-gate.app/faq/authentication

Example JSON configuration for setting the Time-To-Live (TTL) for a JWT token. This example sets the TTL to 2 hours (7200 seconds) and includes scopes for sending and reading messages.

```json
{
  "ttl": 7200,  // 2 hours instead of 1 hour
  "scopes": ["messages:send", "messages:read"]
}

```

--------------------------------

### GET /3rdparty/v1/devices

Source: https://docs.sms-gate.app/features/multi-device

Retrieves a list of all devices currently connected to the account.

```APIDOC
## GET /3rdparty/v1/devices

### Description
Returns a list of devices associated with the authenticated account.

### Method
GET

### Endpoint
https://api.sms-gate.app/3rdparty/v1/devices
```

--------------------------------

### Python Client Example for Pagination

Source: https://docs.sms-gate.app/blog/2025/08/07/mastering-message-retrieval-a-developers-guide-to-get-messages-api

A Python script demonstrating how to paginate through messages using the `requests` library, respecting `limit` and `X-Total-Count` headers.

```APIDOC
```python
import requests

def get_all_messages(base_url, auth):
    offset = 0
    limit = 50
    all_messages = []
    with requests.Session() as s:
        s.auth = auth
        while True:
            params = {"offset": offset, "limit": limit}
            r = s.get(f"{base_url}/messages", params=params, timeout=10)
            if r.status_code != 200:
                raise RuntimeError(f"GET /messages failed: {r.status_code} {r.text}")
            messages = r.json()
            if not messages:
                break
            all_messages.extend(messages)
            total = int(r.headers.get("X-Total-Count") or 0)
            offset += len(messages)
            # Stop when we’ve reached the reported total (if provided) or page is short.
            if (total and offset >= total) or len(messages) < limit:
                break
    return all_messages
```
```

--------------------------------

### Sample cURL Request

Source: https://docs.sms-gate.app/integration/get-to-post

Example of how to send an SMS using a cURL command with 'to' and 'message' parameters.

```bash
curl "https://your-api.com/send-sms?to=%2B1234567890&message=Test"

```

--------------------------------

### Python Flask Local Deployment

Source: https://docs.sms-gate.app/integration/get-to-post

Sets environment variables for SMS API credentials and starts the Flask application for local development.

```bash
# Python Flask
export SMS_API_USERNAME="your_username"
export SMS_API_PASSWORD="your_password"
python flask_app.py

```

--------------------------------

### AWS Lambda Deployment Package

Source: https://docs.sms-gate.app/integration/get-to-post

Installs Python dependencies locally and creates a zip archive for updating an AWS Lambda function code.

```bash
# AWS Lambda Deployment
pip install requests -t .
zip -r lambda.zip .
aws lambda update-function-code --function-name sms-gateway --zip-file fileb://lambda.zip

```

--------------------------------

### Generate Admin Token

Source: https://docs.sms-gate.app/blog/2025/12/10/securing-your-sms-gateway-migrating-from-basic-auth-to-jwt

Example of generating a token with broad administrative privileges, including managing messages, devices, and webhooks, with a 4-hour expiration.

```python
# Token for administration (4 hours)
admin_token = generate_token(
    scopes=["messages:list", "messages:read", "devices:list", "devices:delete", "webhooks:list", "webhooks:write", "webhooks:delete"],
    ttl=14400
)
```

--------------------------------

### Build and Run SMS Gateway from Source

Source: https://docs.sms-gate.app/features/private-server

Clones the repository, builds the binary, makes it executable, and then runs the server. Requires Git and Go 1.24+.

```bash
git clone https://github.com/android-sms-gateway/server.git
cd server
go build -o sms-gateway ./cmd/sms-gateway
chmod +x sms-gateway

```

```bash
./sms-gateway db:migrate up

```

```bash
./sms-gateway

```

--------------------------------

### Build Backend Services

Source: https://docs.sms-gate.app/getting-started/custom-gateway

Commands to build the backend binary or Docker container.

```bash
make build  # Binary
make docker-build  # Container
```

--------------------------------

### Decoded JWT Payload Example

Source: https://docs.sms-gate.app/blog/2025/12/10/securing-your-sms-gateway-migrating-from-basic-auth-to-jwt

An example of a decoded JWT payload, showing user information, scopes, and expiration.

```json
{
  "sub": "user123",
  "scopes": ["messages:send", "messages:read"],
  "exp": 1733785200,
  "iat": 1733781600
}
```

--------------------------------

### Future Payload Example (After Deprecation)

Source: https://docs.sms-gate.app/blog/category/features

This example represents the future payload structure after the `phoneNumber` field is removed, relying solely on `sender` and `recipient`.

```json
{
  "sender": "+1234567890",
  "recipient": "+9876543210"
  // phoneNumber removed in future major version
}
```

--------------------------------

### Convert GET to POST with Node.js Express

Source: https://docs.sms-gate.app/integration/get-to-post

Uses Express and Axios to proxy GET requests to the SMS Gateway API with basic authentication.

```javascript
const express = require('express');
const axios = require('axios');

const app = express();
const port = process.env.PORT || 3000;

const SMS_API_USERNAME = process.env.SMS_API_USERNAME;
const SMS_API_PASSWORD = process.env.SMS_API_PASSWORD;

app.get('/send-sms', async (req, res) => {
    const { to, message } = req.query;
    const missing = [];

    if (!to) missing.push('to');
    if (!message) missing.push('message');

    if (missing.length) {
        return res.status(400).json({ 
            error: `Missing parameters: ${missing.join(', ')}` 
        });
    }

    const targetUrl = 'https://api.sms-gate.app/3rdparty/v1/messages';
    const headers = { 'Content-Type': 'application/json' };
    const payload = { 
        message: message,
        phoneNumbers: [to]
    };

    try {
        const response = await axios.post(targetUrl, payload, {
            auth: {
                username: SMS_API_USERNAME,
                password: SMS_API_PASSWORD
            },
            headers: headers,
            validateStatus: () => true // Forward all status codes
        });

        res.status(response.status)
            .set('Content-Type', response.headers['content-type'])
            .send(response.data);
    } catch (error) {
        res.status(500).json({ 
            error: `SMS gateway error: ${error.message}` 
        });
    }
});

app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});
```

--------------------------------

### Convert GET to POST with Python Flask

Source: https://docs.sms-gate.app/integration/get-to-post

Uses Flask to handle incoming GET requests and forward them as authenticated POST requests to the SMS Gateway.

```python
import os

from flask import Flask, request, jsonify, Response
import requests
from requests.auth import HTTPBasicAuth

app = Flask(__name__)

SMS_API_USERNAME = os.environ.get('SMS_API_USERNAME')
SMS_API_PASSWORD = os.environ.get('SMS_API_PASSWORD')

@app.route('/send-sms', methods=['GET'])
def send_sms():
    # Extract query parameters
    to_phone = request.args.get('to')
    message = request.args.get('message')

    # Validate required parameters
    missing = []
    if not to_phone:
        missing.append('to')
    if not message:
        missing.append('message')

    if missing:
        return jsonify(error=f'Missing parameters: {", ".join(missing)}'), 400

    # Prepare request to SMS gateway
    target_url = 'https://api.sms-gate.app/3rdparty/v1/messages'
    headers = {'Content-Type': 'application/json'}
    payload = {
        'message': message,
        'phoneNumbers': [to_phone]
    }

    try:
        auth = HTTPBasicAuth(SMS_API_USERNAME, SMS_API_PASSWORD)

        response = requests.post(
            target_url,
            auth=auth,
            headers=headers,
            json=payload
        )

        # Forward response
        return Response(
            response=response.text,
            status=response.status_code,
            content_type=response.headers.get('Content-Type', 'application/json')
        )

    except requests.exceptions.RequestException as e:
        return jsonify(error=f'SMS gateway error: {str(e)}'), 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)
```

--------------------------------

### Example values.yaml for Helm Chart

Source: https://docs.sms-gate.app/features/private-server

Configuration file for the SMS Gate Helm chart. Specifies image pull policy, database settings, and gateway private token.

```yaml
image:
  pullPolicy: IfNotPresent

database:
  deployInternal: true
  mariadb:
    rootPassword: ${GENERATE_MARIADB_ROOT_PASSWORD}
  password: ${GENERATE_DATABASE_PASSWORD}

gateway:
  privateToken: ${GENERATE_PRIVATE_TOKEN}

```

--------------------------------

### Migrate from Basic Auth to JWT (Python)

Source: https://docs.sms-gate.app/integration/authentication

Example demonstrating the migration from Basic Authentication to JWT Bearer tokens for sending messages. It first obtains a JWT token and then uses it for the message request.

```python
# Basic Auth example
response = requests.post(
    "https://api.sms-gate.app/3rdparty/v1/messages",
    auth=("username", "password"),
    json={
        "phoneNumbers": ["+1234567890"],
        "textMessage": {"text": "Hello world!"}
    }
)


```

```python
# JWT authentication example
# First, get a token
token_response = requests.post(
    "https://api.sms-gate.app/3rdparty/v1/auth/token",
    auth=("username", "password"),
    json={
        "ttl": 3600,
        "scopes": ["messages:send"]
    }
)

if token_response.status_code == 201:
    token_data = token_response.json()
    access_token = token_data["access_token"]

    # Then use the token
    response = requests.post(
        "https://api.sms-gate.app/3rdparty/v1/messages",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        },
        json={
            "phoneNumbers": ["+1234567890"],
            "textMessage": {"text": "Hello world!"}
        }
    )


```

--------------------------------

### Get Message Status

Source: https://docs.sms-gate.app/integration/cli

Retrieves the current status of a previously sent message.

```APIDOC
## smsgate status

### Description
Retrieves the status of a message using its unique ID.

### Parameters
#### Path Parameters
- **Message ID** (string) - Required - The ID returned from the send command.
```

--------------------------------

### CLI Usage Syntax

Source: https://docs.sms-gate.app/integration/cli

General syntax for executing CLI commands.

```bash
smsgate [global options] command [command options] [arguments...]
```

--------------------------------

### Secure Token Storage using Environment Variables

Source: https://docs.sms-gate.app/blog/2025/12/10/securing-your-sms-gateway-migrating-from-basic-auth-to-jwt

Demonstrates secure storage of sensitive credentials like API tokens using environment variables. Requires the `os` module.

```python
import os

# ✓ Good: Environment variables
TOKEN_URL = os.getenv("SMS_TOKEN_URL")
USERNAME = os.getenv("SMS_USERNAME")
PASSWORD = os.getenv("SMS_PASSWORD")

```

--------------------------------

### Local Network Solutions for Webhooks

Source: https://docs.sms-gate.app/features/webhooks

Guidance on setting up webhooks for servers within private networks.

```APIDOC
## Local Network Solutions

For webhooks within private networks, consider the following options:

1.  **Project CA Certificates**: Generate trusted certificates for private IPs using our Certificate Authority.
2.  **ADB Port Forwarding**: Use `127.0.0.1` with reverse port forwarding.
    ```bash
    adb reverse tcp:9876 tcp:8080
    ```
    Then register your webhook to `http://127.0.0.1:9876/webhook`.
3.  **Secure Tunnels**: Services like Cloudflare Tunnel or ngrok provide HTTPS endpoints.
4.  **Insecure Build Variant** (Not Recommended): For local development and testing, use the insecure build variant that allows communication over HTTP without SSL.
```

--------------------------------

### POST /3rdparty/v1/messages with deviceActiveWithin

Source: https://docs.sms-gate.app/blog/2025/08/05/optimizing-device-selection-with-deviceactivewithin

This example demonstrates how to send a message using the `deviceActiveWithin` query parameter to ensure it is routed to a device that has been active within the last 12 hours.

```APIDOC
## POST /3rdparty/v1/messages?deviceActiveWithin=12

### Description
Sends a message to specified phone numbers, routing it only through devices that have been active within the last 12 hours. This helps ensure message delivery via responsive devices.

### Method
POST

### Endpoint
`/3rdparty/v1/messages?deviceActiveWithin={hours}`

### Parameters
#### Query Parameters
- **deviceActiveWithin** (integer) - Optional - Filters devices to those active within the specified number of hours. A value of `0` disables filtering. Defaults to `0`.

#### Request Body
- **textMessage** (object) - Required - Contains the message content.
  - **text** (string) - Required - The actual text of the message.
- **phoneNumbers** (array of strings) - Required - A list of phone numbers to send the message to.

### Request Example
```json
{
  "textMessage": {
    "text": "Your OTP is 1234"
  },
  "phoneNumbers": ["+1234567890"]
}
```

### Response
#### Success Response (200)
- **messageId** (string) - The unique identifier for the sent message.

#### Error Response (400)
- **message** (string) - Describes the error, e.g., "No active device with such ID found" if no devices meet the `deviceActiveWithin` criteria.
```

--------------------------------

### Build Android Release

Source: https://docs.sms-gate.app/getting-started/custom-gateway

Command to compile the Android application for release.

```bash
./gradlew assembleRelease
```

--------------------------------

### GET /3rdparty/v1/messages/{messageId}

Source: https://docs.sms-gate.app/features/status-tracking

Retrieve the current status of a specific message using its unique identifier.

```APIDOC
## GET /3rdparty/v1/messages/{messageId}

### Description
Retrieves the status and details of a message by its ID.

### Method
GET

### Endpoint
https://api.sms-gate.app/3rdparty/v1/messages/{messageId}

### Parameters
#### Path Parameters
- **messageId** (string) - Required - The unique identifier of the message.

### Request Example
curl -X GET https://api.sms-gate.app/3rdparty/v1/messages/zXDYfTmTVf3iMd16zzdBj -u "user:pass"

### Response
#### Success Response (200)
- **id** (string) - Message identifier
- **state** (string) - Current status of the message
- **reason** (string) - Reason for failure if applicable

#### Response Example
{
  "id": "zXDYfTmTVf3iMd16zzdBj",
  "state": "Failed",
  "reason": "Invalid number"
}
```

--------------------------------

### GET /health/startup - Startup Probe

Source: https://docs.sms-gate.app/features/health

The Startup Probe endpoint determines if the application has completed its startup sequence. It uses the same response format as the readiness probe.

```APIDOC
## GET /health/startup

### Description
Determines if the application has completed its startup sequence.

### Method
GET

### Endpoint
/health/startup

### Response
#### Success Response (200)
- **status** (string) - The overall status of the health check ('pass', 'warn', 'fail').
- **version** (string) - The version of the application.
- **releaseId** (string) - The release identifier.
- **checks** (object) - A map of individual health check results.
  - **db:ping** (object) - Database ping status.
    - **description** (string) - Description of the check.
    - **observedUnit** (string) - Unit of the observed value.
    - **observedValue** (integer) - The measured value.
    - **status** (string) - The status of this specific check ('pass', 'warn', 'fail').

#### Response Example
```json
{
  "status": "pass",
  "version": "1.33.0",
  "releaseId": "1234",
  "checks": {
    "db:ping": {
      "description": "Database ping",
      "observedUnit": "failed pings",
      "observedValue": 0,
      "status": "pass"
    }
  }
}
```
```

--------------------------------

### Webhook Payload Structure

Source: https://docs.sms-gate.app/features/status-tracking

Example JSON payload received via webhooks when a message status changes.

```json
{
  "event": "sms:failed",
  "payload": {
    "messageId": "zXDYfTmTVf3iMd16zzdBj",
    "sender": "+1234567890",
    "recipient": "+9876543210",
    "phoneNumber": "+9876543210",
    "simNumber": 1,
    "failedAt": "2024-02-20T15:30:00Z",
    "reason": "Invalid number"
  }
}
```

--------------------------------

### Run SMS Gateway Server with Docker

Source: https://docs.sms-gate.app/features/private-server

Launches the SMS Gateway server in a Docker container. Mounts a local config.yml file for configuration.

```bash
docker run -d --name sms-gateway \
    -p 3000:3000 \
    -v $(pwd)/config.yml:/app/config.yml \
    ghcr.io/android-sms-gateway/server:latest

```

--------------------------------

### Multi-SIM Incoming SMS Payloads

Source: https://docs.sms-gate.app/blog/category/webhooks

Examples showing how the recipient field clarifies which SIM received the message.

```json
{
  "event": "sms:received",
  "payload": {
    "sender": "+9998887777",
    "recipient": "+1112223333",  // ← Now explicit!
    "simNumber": 1
  }
}
```

```json
{
  "event": "sms:received",
  "payload": {
    "sender": "+7776665555",
    "recipient": "+4445556666",  // ← Clear which SIM!
    "simNumber": 2
  }
}
```

--------------------------------

### Before Enhancement: Ambiguous Webhook Payload

Source: https://docs.sms-gate.app/blog/category/features

This is an example of the webhook payload structure before the enhancement, where `phoneNumber` could be ambiguous.

```json
{
  "payload": {
    "messageId": "abc123",
    "phoneNumber": "+1234567890",
    "simNumber": 1,
    "message": "Hello World"
  }
}
```

--------------------------------

### Token Generation with Different TTLs

Source: https://docs.sms-gate.app/blog/2025/12/10/securing-your-sms-gateway-migrating-from-basic-auth-to-jwt

Demonstrates how to generate tokens with varying time-to-live (TTL) values suitable for different service types, from long-running services to one-time operations.

```python
# For long-running services
token_manager.get_token(scopes=["messages:send"], ttl=3600)  # 1 hour

# For batch jobs
token_manager.get_token(scopes=["messages:send"], ttl=600)   # 10 minutes

# For one-time operations
token_manager.get_token(scopes=["messages:send"], ttl=300)   # 5 minutes
```

--------------------------------

### Launch SMS-Gateway Server with Docker

Source: https://docs.sms-gate.app/getting-started/private-server

Run the SMS-Gateway server in detached mode using Docker, mapping the local config.yml to the container and exposing port 3000.

```bash
docker run -d --name sms-gateway \
    -p 3000:3000 \
    -v $(pwd)/config.yml:/app/config.yml \
    ghcr.io/android-sms-gateway/server:latest
```

--------------------------------

### HTTP Method and Path for GET /messages

Source: https://docs.sms-gate.app/blog/2025/08/07/mastering-message-retrieval-a-developers-guide-to-get-messages-api

This specifies the HTTP method and path for the message retrieval endpoint.

```http
GET /messages

```

--------------------------------

### Default Configuration Parameters

Source: https://docs.sms-gate.app/features/settings-management

Represents the default structure for device settings, including gateway, logs, messages, ping, and webhooks. All settings are nullable and can be reset to default by passing null.

```json
{
    "gateway": {
        "notification_channel": "AUTO"
    },
    "logs": {
        "lifetime_days": 30
    },
    "messages": {
        "limit_period": "Disabled",
        "limit_value": null,
        "log_lifetime_days": null,
        "send_interval_max": null,
        "send_interval_min": null,
        "sim_selection_mode": "OSDefault"
    },
    "ping": {
        "interval_seconds": null
    },
    "webhooks": {
        "internet_required": true,
        "retry_count": 1
    }
}

```

--------------------------------

### Common Error Responses

Source: https://docs.sms-gate.app/skill.md

Examples of common error response formats for validation, rate limiting, and authentication issues.

```APIDOC
### Common Error Responses

**Validation Error:**
```json
{
  "error": "ValidationError",
  "message": "Invalid phone number format",
  "details": {
    "phoneNumbers": ["Must be valid E.164 format"]
  }
}
```

**Rate Limit Exceeded:**
```json
{
  "error": "RateLimitExceeded",
  "message": "Message rate limit exceeded",
  "retryAfter": 60
}
```

**Authentication Errors:**
- **401 Unauthorized**: Invalid credentials or expired JWT token
  - For Basic Auth: Verify username/password
  - For JWT: Generate new token
- **403 Forbidden**: Insufficient scopes (JWT) or account locked

**Device Not Available:**
```json
{
  "error": "NoActiveDevice",
  "message": "No active device found"
}
```
```

--------------------------------

### GET /inbox

Source: https://docs.sms-gate.app/features/reading-messages

List incoming messages with filtering and pagination support. This endpoint is only available in Local Server Mode.

```APIDOC
## GET /inbox

### Description
Retrieves incoming messages with filtering and pagination support.

### Method
GET

### Endpoint
`/inbox`

### Query Parameters
- **type** (string) - Optional - Filter by message type: `SMS`, `DATA_SMS`, `MMS`, `MMS_DOWNLOADED`
- **limit** (integer) - Optional - Maximum messages to return (1-500, default: 50)
- **offset** (integer) - Optional - Number of messages to skip (default: 0)
- **from** (string) - Optional - Start of date range (ISO 8601 format)
- **to** (string) - Optional - End of date range (ISO 8601 format)
- **deviceId** (string) - Optional - Filter by device ID

### Request Example
List inbox messages
```curl
curl -u <username>:<password> \
  "http://<device_local_ip>:8080/inbox?type=SMS&limit=10&offset=0"
```

### Response
#### Success Response (200)
- **id** (string) - Message ID
- **type** (string) - Message type
- **sender** (string) - Sender's phone number
- **recipient** (string) - Recipient's phone number
- **simNumber** (integer) - SIM card number used
- **contentPreview** (string) - A preview of the message content
- **createdAt** (string) - Timestamp when the message was received (ISO 8601 format)

#### Response Example
```json
[
  {
    "id": "PyDmBQZZXYmyxMwED8Fzy",
    "type": "SMS",
    "sender": "+79990001234",
    "recipient": "+79990001234",
    "simNumber": 1,
    "contentPreview": "Hello World!",
    "createdAt": "2020-01-01T00:00:00Z"
  }
]
```

### Response Headers
- **X-Total-Count** (integer) - Total number of messages available
```

--------------------------------

### Get Message Status with SMSGate CLI

Source: https://docs.sms-gate.app/integration/cli

Retrieve the status of a specific sent message by providing its unique ID.

```bash
smsgate status zXDYfTmTVf3iMd16zzdBj
```

--------------------------------

### Sample Device List Response

Source: https://docs.sms-gate.app/blog/2025/08/05/optimizing-device-selection-with-deviceactivewithin

This is a sample JSON response from the device listing API, showing device IDs, names, and their last seen timestamps.

```json
[
  {
    "id": "yVULogr4Y1ksRfnos1Dsw",
    "name": "Primary Device",
    "lastSeen": "2025-08-05T06:30:45Z"
  }
]
```

--------------------------------

### Webhook Payload Structure

Source: https://docs.sms-gate.app/blog/2025/07/12/beyond-plain-text-unlocking-the-hidden-power-of-data-sms

This is an example of the JSON payload structure you will receive when a Data SMS is delivered to your configured webhook endpoint.

```json
{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:data-received",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "abc123",
    "data": "eyJjb21tYW5kIjogIlNUQVJUX0lSUklHQVRJT04iLCAiZHVyYXRpb24iOiAzMH0=",
    "phoneNumber": "6505551212",
    "simNumber": 1,
    "receivedAt": "2024-06-22T15:46:11.000+07:00"
  },
  "webhookId": "RktVAK82cXioNZbRbf87K"
}

```

--------------------------------

### Error Response for Inactive Device

Source: https://docs.sms-gate.app/blog/2025/08/05/optimizing-device-selection-with-deviceactivewithin

This is an example of the JSON response received when no active devices are found matching the specified criteria.

```json
{
  "message": "No active device with such ID found"
}
```
Tokens:
Raw