Sending Messages

Send SMS, MMS, Voice, or WhatsApp messages through Salami Gateway.

Send Message via App

Send a message through a specific SMS App.

POST /api/sms/apps/{sms_app}/send

Authentication

Requires Bearer token.

Path Parameters

Request Body

{
  "to": "254712345678",
  "message": "Hello! Your order #1234 has been confirmed."
}

Request Parameters

Response

{
  "data": {
    "id": 156,
    "to": "254712345678",
    "from": "+15551234567",
    "message": "Hello! Your order #1234 has been confirmed.",
    "sms_provider": "Twilio",
    "provider_id": "SM1234567890abcdef",
    "status": "pending",
    "folder": "outbox",
    "channel": "sms",
    "message_parts": 1,
    "cost": null,
    "app_id": 1,
    "created_at": "2026-03-15T14:30:00.000000Z",
    "updated_at": "2026-03-15T14:30:00.000000Z"
  }
}

Status Codes

Validation Rules

Send Message via Group

Send a message through an SMS App Group with automatic load balancing.

POST /api/sms/groups/{group}/send

Authentication

Requires Bearer token.

Path Parameters

Request Body

{
  "to": "254712345678",
  "message": "Your verification code is 4829."
}

Request Parameters

Response

{
  "data": {
    "id": 157,
    "to": "254712345678",
    "from": "+254700123456",
    "message": "Your verification code is 4829.",
    "sms_provider": "AfricasTalking",
    "status": "pending",
    "folder": "outbox",
    "channel": "sms",
    "message_parts": 1,
    "app_id": 3,
    "created_at": "2026-03-15T14:31:00.000000Z"
  }
}

How the Group Selects an App

1. All apps in the group are evaluated.
2. For each app, the count of pending/processing messages is computed.
3. Available capacity = sms_limit - pending_count (minimum 0).
4. A round-robin load balancer selects the app with the most capacity.
5. If no app has capacity, one is selected randomly.

Status Codes

Message Queuing

Messages are not sent synchronously. When you call the send endpoint:

1. A Message record is created with status: pending and folder: outbox.
2. The message is queued for the provider driver to process.
3. The driver sends the message to the provider API.
4. The status updates to sent when the provider accepts it.
5. When a delivery report (DLR) arrives, the status updates to delivered or failed.

Get Outbox (Sent Messages)

Retrieve paginated outbound messages for an app.

GET /api/sms/apps/{sms_app}/outbox

Authentication

Requires Bearer token.

Path Parameters

Response

{
  "data": [
    {
      "id": 1,
      "name": "My Twilio App",
      "type": "Twilio"
    },
    {
      "current_page": 1,
      "data": [
        {
          "id": 156,
          "to": "254712345678",
          "from": "+15551234567",
          "message": "Hello! Your order #1234 has been confirmed.",
          "sms_provider": "Twilio",
          "provider_id": "SM1234567890abcdef",
          "status": "delivered",
          "folder": "outbox",
          "channel": "sms",
          "message_parts": 1,
          "cost": "0.0075",
          "delivery_date": "2026-03-15T14:30:05.000000Z",
          "app_id": 1,
          "created_at": "2026-03-15T14:30:00.000000Z"
        }
      ],
      "per_page": 15,
      "total": 1
    }
  ]
}

Status Codes

Get Inbox (Received Messages)

Retrieve paginated inbound messages for an app.

GET /api/sms/apps/{sms_app}/inbox

Authentication

Requires Bearer token.

Path Parameters

Response

{
  "data": [
    {
      "id": 1,
      "name": "My Twilio App",
      "type": "Twilio"
    },
    {
      "current_page": 1,
      "data": [
        {
          "id": 200,
          "to": "+15551234567",
          "from": "254712345678",
          "message": "CONFIRM",
          "sms_provider": "Twilio",
          "status": "delivered",
          "folder": "inbox",
          "channel": "sms",
          "message_time": "2026-03-15T15:00:00.000000Z",
          "app_id": 1,
          "created_at": "2026-03-15T15:00:00.000000Z"
        }
      ],
      "per_page": 15,
      "total": 1
    }
  ]
}

Get Single Message

Retrieve a specific message by ID.

GET /api/sms/sms/{smsId}

Authentication

Requires Bearer token.

Path Parameters

Response

{
  "data": {
    "id": 156,
    "to": "254712345678",
    "from": "+15551234567",
    "message": "Hello! Your order #1234 has been confirmed.",
    "sms_provider": "Twilio",
    "provider_id": "SM1234567890abcdef",
    "message_time": "2026-03-15T14:30:00.000000Z",
    "telco_code": "63902",
    "telco_name": "Safaricom",
    "message_parts": 1,
    "retry_count": 0,
    "status": "delivered",
    "delivery_date": "2026-03-15T14:30:05.000000Z",
    "cost": "0.0075",
    "folder": "outbox",
    "channel": "sms",
    "app_id": 1,
    "created_at": "2026-03-15T14:30:00.000000Z",
    "updated_at": "2026-03-15T14:30:05.000000Z"
  }
}

Status Codes

Get Calls

Retrieve call records for a voice-enabled SMS App.

GET /api/sms/apps/{sms_app}/calls

Authentication

Requires Bearer token.

Response

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "from": "254712345678",
        "to": "+15551234567",
        "duration": 45,
        "status": "completed",
        "app_id": 5,
        "created_at": "2026-03-15T16:00:00.000000Z"
      }
    ],
    "per_page": 15,
    "total": 1
  }
}

Message Cost Calculation

Message cost is determined by the provider and recorded after the message is processed. Cost is stored in the cost field of the message record and is populated when the provider returns pricing information or when a DLR with cost data is received.

For multi-part messages (messages exceeding 160 characters for GSM-7 or 70 characters for UCS-2), the message_parts field indicates how many segments were sent.

Phone Number Formats

Phone numbers should be provided in international format without the + prefix for most providers:

Some providers accept the + prefix. Consult the specific provider's documentation.

Related Documentation

• SMS API Overview
• SMS Apps
• Receiving Messages
• Callbacks & DLRs
• Channels