🚀 Getting Started

🔒 Private Server

To enhance privacy and control, you can host your own private server. This keeps all message data within your infrastructure while maintaining push notification capabilities through our public server at api.sms-gate.app. This setup eliminates the need to configure Firebase Cloud Messaging (FCM) or rebuild the Android app, but it does demand some technical know-how.

flowchart
    %% === MAIN BLOCKS ===
    Users["👥 Users"]
    Android["🤖 SMSGate App"]

    subgraph PrivateServer["Private Server"]
        GoServerPrivate["🐹 Server"]
        GoWorkerPrivate["🐹 Worker"]
        DB["🦭 DB"]

        GoServerPrivate <--> DB
        GoWorkerPrivate --> DB
    end

    subgraph Google["Google"]
        FCM["🔥 FCM"]
    end

    subgraph PublicServer["Public Server"]
        GoServerPublic["🐹 api.sms-gate.app"]
    end

    %% === CONNECTIONS ===

    Users -->|REST API| GoServerPrivate
    GoServerPrivate -->|notification| GoServerPublic
    GoServerPublic -->|notification| FCM
    FCM -->|PUSH| Android
    Android <--> GoServerPrivate

    %% === ALTERNATIVE NOTIFICATION PATH ===
    Android -.->|SSE| GoServerPrivate

    %% === STYLING ===
    classDef altConn stroke-dasharray: 5 5,stroke:#888,fill:none;
    class Android,GoServerPrivate,GoWorkerPrivate,DB altConn;

Prerequisites ✅

The easiest way to run the server is to use Docker. For alternative installation methods, see Private Server Documentation.

To run the server, you'll need:

• 🐧 Linux VPS
• 🐳 Docker installed
• 🗄️ MySQL/MariaDB server with empty database and privileged user
• 🔄 Reverse proxy with valid SSL certificate (project CA supported)

Run the Server 🖥️

1. Create configuration
   Copy the example config and customize:

   Get config.yml template

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

   Key sections to edit:
   Private Server Configuration Example

   gateway:
       mode: private
       private_token: your-secure-token-here # (1)!
   http:
       listen: 0.0.0.0:3000
   database: # (2)!
       host: localhost
       port: 3306
       user: root
       password: root
       database: sms
       timezone: UTC
   

   1. Must match device configuration
   2. Must match MySQL/MariaDB configuration

   Configuration Location

   By default, the application looks for config.yml in the current working directory. Alternatively, you can set the CONFIG_PATH environment variable to specify a custom path to the configuration file.

2. Launch the server

   Docker Command

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

3. Run the background worker (optional)

   Docker Command

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

   The background worker handles maintenance tasks. See Background Worker for setup details.

4. Configure reverse proxy

   Example Nginx Config

   location / {
       proxy_pass http://localhost:3000;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-For $remote_addr;
   }
   

   See Reverse Proxy Configuration for setup details and advanced options.

curl https://private.example.com/health
# Should return JSON health status

Configure Android App 📱

1. Access Settings
   Navigate to Settings tab → Cloud Server

2. Enter server details
   

   API URL: https://private.example.com/api/mobile/v1
   Private Token: your-secure-token-here
   

   API URL Path

   The API URL must include the /api/mobile/v1 path. Using just the base URL (e.g., https://private.example.com) will not work.

   HTTPS Required

   The Android app requires HTTPS for all communications with your private server unless you use an insecure build variant. Using HTTP will result in connection failures.

   To obtain a valid SSL certificate:

   • Use Let's Encrypt for a free, trusted certificate
   • Use our project CA for private IP addresses or internal domains
   • Use a tunneling service like ngrok or Cloudflare Tunnel for testing

3. Activate connection

   1. Switch to Home tab
   2. Activate Cloud server switch
   3. Tap the "Offline" button to initiate the connection and registration process
   4. Wait for the app to establish connection (button will change to "Online")

Username: A1B2C3
Password:  z9y8x7...

Using the API 📡

All API interactions with the SMSGate use the same request format and authentication methods, but the URL structure differs between Cloud and Private server modes.

URL Structure Comparison

Example: Sending a Message

# Cloud Server
curl -X POST "https://api.sms-gate.app/3rdparty/v1/messages" \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello"}}'

# Private Server
curl -X POST "https://your-domain.com/api/3rdparty/v1/messages" \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello"}}'

📚 See Also

• Private Server Documentation
• Ubuntu/Docker/Nginx Setup Guide
• Docker Compose Quickstart