Receiving Inbound Messages

Salami Gateway supports receiving inbound SMS messages through three mechanisms: provider push endpoints, the SmsSync protocol, and the MSync protocol.

Push Endpoint (Provider Webhook)

Most cloud-based SMS providers send inbound messages by pushing HTTP requests to a configured URL.

ANY /api/sms/apps/{sms_app}/receive

Authentication

No Bearer token required. This endpoint is called directly by SMS providers.

Path Parameters

How It Works

1. Configure the receive URL in your SMS provider's dashboard:

   https://your-domain.com/api/sms/apps/{app_id}/receive
   

2. When a message arrives at your phone number/shortcode, the provider sends a webhook to this URL.
3. Salami's driver parses the provider-specific payload into a normalized Message record.
4. The message is stored with folder: inbox.
5. An IpnCallReceived event fires, triggering webhooks and Slack notifications.

Provider Webhook Configuration Examples

Twilio: Set the "A Message Comes In" webhook URL in your Twilio phone number settings.

Africa's Talking: Configure the callback URL in the Africa's Talking dashboard under SMS > Callback URLs > Incoming Messages.

Vonage: Set the inbound SMS webhook URL in your Vonage application settings.

Response

The response format varies by provider. Salami returns the appropriate response expected by each provider (e.g., TwiML for Twilio, empty 200 for most others).

{
  "data": {
    "id": 200,
    "to": "+15551234567",
    "from": "254712345678",
    "message": "Hello from customer",
    "status": "delivered",
    "folder": "inbox",
    "channel": "sms",
    "app_id": 1,
    "created_at": "2026-03-15T15:00:00.000000Z"
  }
}

Status Codes

SmsSync Protocol

SMSSync is an open-source Android app that turns a phone into an SMS gateway. The phone sends received messages to your server and fetches outbound messages to send.

ANY /api/sms/smssync

Authentication

No Bearer token required. The SmsSync app authenticates via its own secret/key mechanism.

How It Works

1. Install the SMSSync app on an Android phone.
2. Configure the Sync URL:

   https://your-domain.com/api/sms/smssync
   

3. The phone periodically sends received SMS to this endpoint.
4. The phone also polls this endpoint for outbound messages to send.

Incoming Message (Phone to Server)

The SmsSync app POSTs received messages with these parameters:

Example request from SmsSync app:

POST /api/sms/smssync

from=254712345678&message=Hello&sent_timestamp=1710510600&sent_to=254700123456&message_id=abc123&device_id=device1&secret=mysecret

Response (Server to Phone)

The server responds with a JSON payload. To send outbound messages via the phone, include them in the response:

{
  "payload": {
    "success": true,
    "task": "send",
    "secret": "mysecret",
    "messages": [
      {
        "to": "254712345678",
        "message": "Reply from server",
        "uuid": "msg-uuid-123"
      }
    ]
  }
}

Polling for Outbound Messages

The SmsSync app can poll the endpoint to check for messages to send:

GET /api/sms/smssync?task=send&secret=mysecret

Response:

{
  "payload": {
    "task": "send",
    "secret": "mysecret",
    "messages": [
      {
        "to": "254712345678",
        "message": "Scheduled message",
        "uuid": "msg-uuid-456"
      }
    ]
  }
}

MSync Protocol

MSync is Salami's proprietary Android app for phone-based SMS gateway functionality. It provides richer features than SmsSync including device status monitoring, location tracking, and bidirectional sync.

ANY /api/sms/msync

Authentication

No Bearer token required. The MSync app authenticates via device credentials.

How It Works

1. Install the MSync app on an Android phone.
2. Configure the server URL:

   https://your-domain.com/api/sms/msync
   

3. The app synchronizes messages bidirectionally with the server.
4. The app reports device status (battery, signal, network) and location.

Incoming Message Sync

The MSync app sends received messages to the server:

POST /api/sms/msync

{
  "action": "incoming",
  "device_id": "device-uuid-123",
  "messages": [
    {
      "from": "254712345678",
      "message": "Hello",
      "timestamp": "2026-03-15T15:00:00Z",
      "sim_slot": 0
    }
  ]
}

Outbound Message Polling

The app polls for messages to send:

POST /api/sms/msync

{
  "action": "outgoing",
  "device_id": "device-uuid-123"
}

Response:

{
  "messages": [
    {
      "id": 157,
      "to": "254712345678",
      "message": "Your order is ready",
      "uuid": "msg-uuid-789"
    }
  ]
}

Device Status Reporting

The MSync app periodically reports device health:

POST /api/sms/msync

{
  "action": "status",
  "device_id": "device-uuid-123",
  "battery_level": 85,
  "signal_strength": -67,
  "network_type": "4G",
  "sim_state": "ready"
}

Device Location Reporting

POST /api/sms/msync

{
  "action": "location",
  "device_id": "device-uuid-123",
  "latitude": -1.2921,
  "longitude": 36.8219,
  "accuracy": 15.0
}

Delivery Report Sync

The MSync app reports delivery confirmations:

POST /api/sms/msync

{
  "action": "delivery",
  "device_id": "device-uuid-123",
  "reports": [
    {
      "uuid": "msg-uuid-789",
      "status": "delivered",
      "timestamp": "2026-03-15T15:00:05Z"
    }
  ]
}

Inbound Message Processing Pipeline

Regardless of the receiving mechanism, all inbound messages go through this pipeline:

1. Receive: Message arrives at the endpoint.
2. IPN Logging: Raw request is logged in the sms_ipn_requests table.
3. Parse: The driver parses provider-specific format into a normalized Message.
4. Store: Message is saved with folder: inbox.
5. Events: IpnCallReceived event fires.
6. Webhooks: Configured webhooks are dispatched.
7. Slack: Slack notifications are sent (if configured).
8. Payment Extraction: If the SMS App is linked to a Payment App, the message is checked for payment transaction data.

Related Documentation

• SMS API Overview
• Sending Messages
• Callbacks & DLRs
• SMS Apps