SMS API Overview

Salami Gateway provides a unified SMS API that integrates with 128+ messaging providers worldwide. The module supports multiple channels including SMS, MMS, Voice, and WhatsApp, using a driver-based architecture that allows seamless provider switching.

Base URL

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

Authentication

Authenticated endpoints require Laravel Sanctum bearer tokens.

Authorization: Bearer {your-api-token}

Unauthenticated endpoints (no token required):

Phone sync protocols (/api/sms/msync, /api/sms/smssync)
Inbound message receiving (/api/sms/apps/{app}/receive)
Provider callbacks (/api/sms/apps/{app}/callback)

Supported Channels

Channel	Description
`sms`	Standard text messaging (plain SMS)
`mms`	Multimedia messaging (images, video, audio)
`voice`	Voice calls and text-to-speech
`whatsapp`	WhatsApp messaging

Provider Count by Channel

Channel	Provider Count
SMS	120+
MMS	15+
Voice	5
WhatsApp	10+

Architecture

SMS Apps

An SMS App is the central configuration entity. Each app binds a messaging provider driver to credentials and settings. You can create multiple apps per provider (e.g., different Twilio accounts for different sender IDs).

Key properties:

Field	Type	Description
`id`	integer	Unique identifier, used in API endpoint paths
`name`	string	Human-readable name
`type`	string	Driver/provider identifier (e.g., `Twilio`, `AfricasTalking`)
`channel`	string	Messaging channel: `sms`, `mms`, `voice`, `whatsapp`
`sms_limit`	integer	Maximum pending messages before load balancing kicks in
`group_id`	integer/null	App group for load distribution
`payment_app_id`	integer/null	Linked Payment App for SMS-to-payment extraction

Driver System

Each provider has a driver that implements messaging operations. Drivers handle:

Sending: Queue and dispatch outbound messages
Receiving: Parse inbound messages from provider webhooks
Callbacks: Process delivery reports (DLRs) and status updates
Phone Sync: Support for MSync and SmsSync protocols for phone-based gateways

SMS App Groups

App Groups enable load distribution across multiple SMS Apps. When sending to a group, Salami uses a round-robin load balancer that selects the least-busy app (fewest pending messages). If all apps are idle, one is selected randomly.

Message Model

Every SMS, MMS, Voice, or WhatsApp message creates a Message record.

Field	Type	Description
`id`	integer	Unique message ID
`to`	string	Recipient phone number
`from`	string	Sender phone number or ID
`message`	string	Message body text
`sms_provider`	string	Driver that handled this message
`provider_id`	string	Provider's message ID
`message_time`	datetime	When the message was sent/received
`telco_code`	string	Telco/carrier code
`telco_name`	string	Telco/carrier name
`message_parts`	integer	Number of SMS parts (for long messages)
`retry_count`	integer	Number of send retry attempts
`status`	string	Message status
`delivery_date`	datetime	When delivery was confirmed
`cost`	decimal	Message cost
`folder`	string	`inbox` (received) or `outbox` (sent)
`channel`	string	Channel: `sms`, `mms`, `voice`, `whatsapp`
`app_id`	integer	Associated SMS App ID
`created_at`	datetime	Record creation timestamp

Message Statuses

Status	Description
`pending`	Message queued, waiting to be sent
`processing`	Message being sent to provider
`sent`	Message accepted by provider
`delivered`	Delivery confirmed by recipient's carrier
`failed`	Send attempt failed
`rejected`	Rejected by provider

Message Folders

Folder	Description
`inbox`	Received/inbound messages
`outbox`	Sent/outbound messages

Standard API Response Format

{
  "data": { },
  "status": "success",
  "message": "Operation completed"
}

Error response:

{
  "data": null,
  "status": "error",
  "message": "Description of the error"
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Resource created
`401`	Unauthenticated -- missing or invalid bearer token
`403`	Forbidden -- you do not own this SMS App
`404`	SMS App or Message not found
`422`	Validation error -- check request body
`500`	Server error or provider error

API Endpoints Summary

Method	Path	Auth	Description
`GET`	`/api/sms/apps/{app}`	Yes	Get app details
`POST`	`/api/sms/apps/{app}/send`	Yes	Send a message
`GET`	`/api/sms/apps/{app}/inbox`	Yes	List received messages
`GET`	`/api/sms/apps/{app}/outbox`	Yes	List sent messages
`GET`	`/api/sms/apps/{app}/calls`	Yes	List call records
`GET`	`/api/sms/sms/{smsId}`	Yes	Get single message
`POST`	`/api/sms/groups/{group}/send`	Yes	Send via app group
`POST`	`/api/sms/groups/{group}`	Yes	Get group details
`ANY`	`/api/sms/apps/{app}/receive`	No	Receive inbound message
`ANY`	`/api/sms/apps/{app}/callback`	No	Provider callback/DLR
`ANY`	`/api/sms/msync`	No	MSync protocol endpoint
`ANY`	`/api/sms/smssync`	No	SmsSync protocol endpoint

Salami Gateway