SMS Apps

SMS Apps are the core configuration entities in the Salami SMS module. Each app binds a messaging provider driver to credentials and settings.

Get App Details

Retrieve details of a specific SMS app.

GET /api/sms/apps/{sms_app}

Authentication

Requires Bearer token.

Path Parameters

Response

{
  "data": {
    "id": 1,
    "name": "My Twilio App",
    "type": "Twilio",
    "channel": "sms",
    "sms_limit": 100,
    "phone_number": "+254712345678",
    "group_id": null,
    "payment_app_id": null,
    "created_by": 1,
    "updated_by": 1,
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-01-15T10:30:00.000000Z"
  }
}

Status Codes

Creating SMS Apps

SMS Apps are created through the Salami web dashboard. Navigate to SMS > Apps > Create New App.

Required Fields (All Providers)

Additional required fields depend on the selected provider. The form dynamically shows provider-specific fields.

Provider Configuration Fields

Each provider requires different credentials. Below are examples for popular providers.

Twilio -- Twilio

Africa's Talking -- AfricasTalking

MessageBird -- MessageBird

Vonage (Nexmo) -- Vonage

Plivo -- Plivo

Amazon SNS -- AmazonSNS

Infobip -- Infobip

MSync (Phone Gateway) -- MSync

MSync turns an Android phone into an SMS gateway. No API credentials needed -- the phone connects to Salami via the MSync protocol.

SmsSync (Phone Gateway) -- SmsSync

Similar to MSync but uses the SMSSync protocol.

Generic Provider Fields

Many providers use a common set of fields:

SMS App Groups

App Groups allow load distribution across multiple SMS Apps.

Get Group Details

POST /api/sms/groups/{group}

Authentication

Requires Bearer token.

Path Parameters

Response

{
  "data": {
    "id": 1,
    "name": "Production SMS Pool",
    "created_by": 1,
    "created_at": "2026-01-15T10:30:00.000000Z"
  }
}

How Load Balancing Works

When sending via a group (POST /api/sms/groups/{group}/send), Salami:

1. Retrieves all SMS Apps in the group.
2. Counts pending/processing messages for each app.
3. Calculates available capacity: sms_limit - pending_count.
4. Uses a round-robin load balancer weighted by available capacity.
5. Routes the message through the least-busy app.
6. If no app has capacity, one is selected randomly.

Creating Groups

Groups are managed through the web dashboard under SMS > App Groups.

After creating a group, assign SMS Apps to it by setting the group_id on each app.

Payment App Linking

SMS Apps can be linked to a Payment App via payment_app_id. When linked, incoming SMS messages are automatically parsed for payment transaction data using the Payment App's driver. This is used for SMS-based transaction extraction (e.g., M-Pesa confirmation SMS parsing).

Channel Selection

When creating an app, the channel field determines the messaging channel:

Not all providers support all channels. See the Providers documentation for the capabilities matrix.

Status Codes

Related Documentation

• SMS API Overview
• Sending Messages
• Receiving Messages
• Channels
• Providers