🚀 Getting Started

☁️ Cloud Server

Use Cloud Server mode when your device has dynamic or shared IP addresses. Start immediately—no registration, email, or phone number required.

Key Features ⚡

• 🌐 No registration required
• 🔄 Hybrid push-pull architecture
• ⏱️ Dynamic and shared device IP support
• 🔒 Basic authentication

Requirements ⚠️

• Requires Google Play Services for Firebase Cloud Messaging (FCM) push notifications
• Provides a Server-Sent Events (SSE) fallback for devices without Play Services
• Needs active internet connection

Message Flow 📨

sequenceDiagram
    participant API
    participant Server
    participant FCM
    participant Device

    API->>Server: POST /messages
    Server->>Server: Store in DB
    par Notification Flow
        alt Firebase Cloud Messaging
            Server->>FCM: Send push notification
            FCM->>Device: Deliver FCM message
        else Server-Sent Events
            Server->>Device: Send event
        end
        Device->>Server: Get messages
        Server->>Device: Return messages
    and Scheduled Polling
        loop Every 15 minutes
            Device->>Server: Get messages (polling)
            Server->>Device: Return messages
        end
    end

    Device->>Device: Process SMS
    Device->>Server: Report message status
    Server->>API: Webhook notification (optional)

🔔 Push Notification📡 SSE Fallback⏰ Scheduled Polling Custom Ping

graph LR
    A[API Request] --> B[Server]
    B --> C[FCM]
    C --> D[Device]
    D --> E[Retrieve Messages]

• Instant delivery via Firebase
• Primary message channel

graph LR
    A[API Request] --> B[Server]
    B -->|SSE connection| C[Device]
    C --> D[Retrieve Messages]

• Fallback when FCM is unavailable
• Persistent connection for real-time events
• Shows persistent notification on device during operation
• May increase battery consumption due to the long-lived connection

graph LR
    A[Device] --> B{Every 15min}
    B --> C[Check Server]
    C --> D[Get Messages]

• Fallback mechanism
• Ensures message delivery

• Configurable check interval
• May increase battery consumption

Notification Channel Selection 🔔

The app allows you to control which notification channel is used:

When to use SSE Only:

• Enterprise environments where FCM is restricted by firewall policies
• Devices without Google Play Services (e.g., Chinese devices, custom ROMs)
• Privacy-focused deployments wanting to avoid Google services
• Testing SSE functionality

Configuration:

Change the notification channel in the app settings:

1. Navigate to Settings → Cloud Server
2. Find Notification Channel option
3. Select Auto or SSE Only
4. Restart the app to apply changes

Important: SSE Only mode maintains a persistent HTTP connection, which may increase battery consumption and shows a persistent notification in the status bar.

How to Use 🛠️

1. Activate Cloud Mode
   Launch app → Toggle "Cloud Server"

2. Go Online
   Tap the "Offline" button to initiate connection and registration process → Button will change to "Online" when connected

3. Get Credentials
   Credentials will be automatically generated and appear in the Cloud Server section after successful connection:
   

   

No manual registration step is required. Username and password are generated automatically on the first successful connection to the server.

You can also log in at **`https://dashboard.sms-gate.app`** with these credentials to manage messages, devices, webhooks, and settings through a graphical web interface. See the [Web Dashboard](../services/web-dashboard.md) guide for details.

1. Send Message

   cURLPythonJavaScript

   curl -X POST -u "username:password" \
    --json '{"textMessage":{"text":"Hello World"},"phoneNumbers":["+19162255887"]}' \
    https://api.sms-gate.app/3rdparty/v1/messages
   

   import requests
   
   response = requests.post(
       "https://api.sms-gate.app/3rdparty/v1/messages",
       auth=("username", "password"),
       json={
           "textMessage": { "text": "Hello World"},
           "phoneNumbers": ["+19162255887"]
       }
   )
   

   fetch('https://api.sms-gate.app/3rdparty/v1/messages', {
     method: 'POST',
     headers: {
       'Authorization': 'Basic ' + btoa('username:password'),
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       textMessage: { text: "Hello World" },
       phoneNumbers: ["+79990001234"]
     })
   });
   

Full API Documentation