Introduction

Welcome to the SMS Automation API documentation. This API allows you to send SMS messages through Safaricom's SMS gateway using your shortcode, Paybill, or Buy Goods Till Number.

The API is designed to be simple and easy to integrate with your existing systems. It supports single and bulk messaging, as well as scheduled messaging.

Base URL

All URLs referenced in the documentation have the following base:

https://yourdomain.com/api

Authentication

The API uses API keys for authentication. You can find your API key in your dashboard.

To authenticate your requests, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Creating an API Key

You can create an API key by registering for an account. Once registered, you'll be able to view and manage your API keys from your dashboard.

Sending SMS

This endpoint allows you to send an SMS message immediately.

curl -X POST \
  https://yourdomain.com/api/send-sms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "254712345678",
    "message": "Hello from SMS Automation API!"
}'

$apiKey = 'YOUR_API_KEY';
$url = 'https://yourdomain.com/api/send-sms';

$data = [
    'recipient' => '254712345678',
    'message' => 'Hello from SMS Automation API!'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'https://yourdomain.com/api/send-sms';

const data = {
    recipient: '254712345678',
    message: 'Hello from SMS Automation API!'
};

axios.post(url, data, {
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error('Error:', error.response.data);
});

{
    "success": true,
    "message_id": 12345,
    "safaricom_message_id": "SMS1234567890"
}

Scheduling SMS

This endpoint allows you to schedule an SMS message for later delivery.

curl -X POST \
  https://yourdomain.com/api/schedule-sms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "254712345678",
    "message": "Your scheduled message content",
    "scheduled_time": "2023-06-15 14:30:00"
}'

{
    "success": true,
    "message_id": 12346,
    "scheduled_time": "2023-06-15 14:30:00"
}

Bulk SMS

This endpoint allows you to send the same SMS message to multiple recipients at once.

curl -X POST \
  https://yourdomain.com/api/send-bulk-sms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": ["254712345678", "254723456789", "254734567890"],
    "message": "Bulk message to multiple recipients"
}'

{
    "success": true,
    "total": 3,
    "successful": 3,
    "failed": 0,
    "details": [
        {
            "recipient": "254712345678",
            "success": true,
            "message_id": 12347
        },
        {
            "recipient": "254723456789",
            "success": true,
            "message_id": 12348
        },
        {
            "recipient": "254734567890",
            "success": true,
            "message_id": 12349
        }
    ]
}

Delivery Status

This endpoint allows you to check the delivery status of a sent message.

curl -X POST \
  https://yourdomain.com/api/delivery-status \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message_id": 12345
}'

{
    "success": true,
    "message": {
        "id": 12345,
        "recipient": "254712345678",
        "message": "Hello from SMS Automation API!",
        "status": "delivered",
        "message_id": "SMS1234567890",
        "scheduled_time": null,
        "sent_time": "2023-06-14 10:30:45",
        "delivery_time": "2023-06-14 10:31:02"
    }
}

Webhook Integration

You can receive delivery reports and other notifications via webhooks.

Delivery Reports

When a message status changes (e.g., from "sent" to "delivered"), a webhook notification will be sent to your specified URL.

Webhook Payload

{
    "messageId": "SMS1234567890",
    "status": "delivered",
    "recipient": "254712345678",
    "timestamp": "2023-06-14 10:31:02"
}

Webhook Security

To secure your webhook endpoint, a secret parameter is added to the webhook URL:

https://your-webhook-url.com/callback?secret=YOUR_WEBHOOK_SECRET

You should validate this secret in your webhook handler to ensure the requests are coming from our system.

PHP SDK

We provide a PHP SDK to make integration easier. You can download the SDK from your dashboard.

Installation

Include the SDK file in your project:

require_once 'path/to/SmsApiClient.php';

Usage

use SmsApi\SmsApiClient;

// Initialize the client
$smsClient = new SmsApiClient('YOUR_API_KEY', 'https://yourdomain.com/api');

// Send an SMS
$result = $smsClient->sendSms('254712345678', 'Hello from SMS API!');
print_r($result);

// Schedule an SMS
$scheduledTime = '2023-06-15 14:30:00';
$result = $smsClient->scheduleSms('254712345678', 'Scheduled message', $scheduledTime);
print_r($result);

// Send bulk SMS
$recipients = ['254712345678', '254723456789', '254734567890'];
$result = $smsClient->sendBulkSms($recipients, 'Bulk message');
print_r($result);

// Check delivery status
$result = $smsClient->getDeliveryStatus(12345);
print_r($result);

Error Codes

The API returns standard HTTP status codes along with JSON error responses.

Error Response Format

{
    "success": false,
    "error": "Error message description"
}