254SMS Documentation version 2.0


Introduction

Welcome to 254SMS . You will get guides and documentation to help you get familiar with our Products and services and learn how to integrate them

This document provides a reference for all features available to you via the HTTP interface for sending SMS.

The API allows you to integrate your application (client) to 254SMS using the HTTP protocol to send SMS. HTTPS is also supported for secure transactions using SSL encryption.

The Client issues a POST request to the our API interface supplying a list of required parameters. 254SMS issues back a JSON response to your end.

The API is used for one-way messaging only. Therefore, you need to provide a valid Shortcode number as the Sender ID of the message to enable the recipient to respond.

Getting Started #back to top

Registration - #back to top

To use our APIs or invoke an API endpoint, you will need to register for an account. You will receive an SMS with sender ID 254SMS with verification code. Upon successful registration you will be able to login using the credntials you used.

Register here

Here is a screenshot of our registration page

254SMS registration page

Authentication - #back to top

Upon successful registration and accoun activation, Get our HTTP API from the section below. Get your HTTP API username and ApiKey.

To be able to send you SMS through our HTTP API, Here are the required requirements.

Parameter Description
Username
String
Required
254SMS username
ApiKey
String
Required
Generated from 254SMS interface e.g YTQzN2YzZGQ3NzRiZjc2YWE3NGJiMW
Recipients
numbers
Required
List of recipients valid phone numbers or single number e.g 254722123123,254723999888
Message
String
Required
SMS text to be sent to the recipients
Senderid
String
Required
SenderId allocated Default senderid is254sms
API Endpoint
URL
Required
254SMS Http API Endpoint. Our Bulk SMS endpoint is http://api.254sms.com/version1/send_sms

Request Headers - #back to top

These are the standard request headers that are needed when authenticating with the API

Parameter Description
apiKey
String
Required
254SMS application apiKey.
Content-Type
String
Required
The requests content type. Can be application/x-www-form-urlencoded or application/json
Accept
String
Optional
The requests response type. Can be application/json or application/xml. Defaults to application/xml

Bulk SMS Sending Overview - #back to top

Send SMS through your application by making a HTTP POST to our endpoints

PHP code to send Bulk SMS

                                                                                                                                          
    $message ='Hello world';
    $sender_id = '254sms'; //Default senderId
    $phone = '25472256565,254722998999'; //for multiple concatinate with comma(,)
    $apikey = '254SMS APIKEY'; // Check under HTTP API in 254sms.com
    $username= '254SMS USERNAME'; // Your 254sms.com Username
    $url = 'http://api.254sms.com/version1/sendsms';
    $data = array(
        'username' => $username,
        'api_key' => $apikey,
        'sender_id' => $sender_id,
        'phone' => $phone,
        'message' => $message  
    );
    $payload = json_encode($data);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);
    echo $result;
    if (!$result) {
        
        die("ERROR on URL[$url] | error[" . curl_error($ch) . "] | error code[" . curl_errno($ch) . "]\n");
    }
                                                                             
                                                                

Java #back to top

Java code

                                                
                           
                                                 
                                        

Curl #back to top

Curl code

                                                
    curl -X POST \
    http://api.254sms.com/version1/send_sms/ \
    -H 'api_key: OWJhYWQwMzhmZIyN2FkNjcwMWNlMj' \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=brian&sender_id=254sms&phone=254700123456&msg=This%20is%20my%20first%20message%20with%20SMSGatewayCenter'                                                                               
                                                
                                        

C# #back to top

C# code

                                            

                                            
                                    

.NET #back to top

.NET code

                                                
    main {

        string url = "http://api.254sms.com/version1/send_sms/";
        string username = "254SMS username";
        string apiKey = "254SMS API KEY";
        string senderId = "254sms"
        
        Url url = new Url (url);
        
        string data = "username =" + username + "& api_key =" + apiKey + "& sender_id ="senderId + "& message = "+Hello world!!+ ";
        
        byte [] Buffer = System.Text.Encoding.UTF8.GetBytes (data);
        
        HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create (uri);
        request.Method = WebRequestMethods.Http.Post;
        request.ContentLength = Buffer.Length;
        request.ContentType = "application / x-www-form-urlencoded";
        
        using (Stream writer = request.GetRequestStream ())
        {
            writer.Write (Buffer, 0, Buffer.Length);
            writer.Flush ();
            writer.Close ();
        }
        
        HttpWebResponse response = (HttpWebResponse) request.GetResponse ();
        StreamReader reader = new StreamReader (response.GetResponseStream ());
        string tmp = reader.ReadToEnd ();
        response.Close ();
        Response.Write (tmp);
            
        }
                                                
                                        

NodeJs #back to top

NodeJs code

                                                    
    var qs = require("querystring");
    var http = require("https");
    
    var options = {
        "method": "POST",
        "hostname": "www.api.254sms.com",
        "port": null,
        "path": "/version1/send_sms",
        "headers": {
        "content-type": "application/x-www-form-urlencoded"
        }
    };
    
    var req = http.request(options, function (res) {
        var chunks = [];
    
        res.on("data", function (chunk) {
        chunks.push(chunk);
        });
    
        res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
        });
    });
    
    req.write(qs.stringify({ 
        api_key: 'Your 254SMS APIKEY',
        username: 'YourUsername',
        sender_id: '254sms',
        phone: '254722999888, 254723898989',
        message: 'Hello world!!'
        }));
    req.end();
                                                            
                                                    
                                            

Python #back to top

Python code

                                                
    >>> x = int(input("
    import http.client

    conn = http.client.HTTPSConnection("www.api.254sms.com")

    payload = "username=brian&sender_id=254sms&phone=254722565656&message=Hello%20World"

    headers = {
        'api_key': "apikey",
        'content-type': "application/x-www-form-urlencoded",
        'cache-control': "no-cache"
        }

    conn.request("POST", "/version1/send_sms", payload, headers)

    res = conn.getresponse()
    data = res.read()

    print(data.decode("utf-8"))
                                                
                                        

Ruby #back to top

Ruby code

                                                
    require 'uri'
    require 'net/http'
    
    url = URI("http://api.254sms.com/version1/send_sms")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Post.new(url)
    request["content-type"] = 'application/x-www-form-urlencoded'
    request.body = "username=john&api_key=apikey&sender_Id=254sms&phone=254722565656&message=Hello%20World"
    
    response = http.request(request)
    puts response.read_body
                                                
                                        

Check SMS Credits #back to top

Here is a Code Snippet in PHP to check for Bulk SMS Credits

                                                
    $apikey = '254SMS_APIKEY'; // Check under HTTP API  in 254sms.com
    $username= '254SMS_USERNAME'; // Your 254sms.com Username
    $url = 'http://api.254sms.com/version1/credits';
    $data = array(
        'username' => $username,
        'api_key' => $apikey 
    );
    $payload = json_encode($data);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);
    echo $result; 
    if (!$result) {
        
        die("ERROR on URL[$url] | error[" . curl_error($ch) . "] | error code[" . curl_errno($ch) . "]\n");
    }   
                     
                                                 
                                             

SMS Credits Response #back to top

Here is a JSON outpu that you get when you request to know your Bulk SMS Credits

                                                    
    [
        {
            credits: "6",
            statusCode: 101
        }
    ]    
                                                     
                                                 

SMS Sending Response #back to top

This is the HTTP API Response you get upon executing our APIs

                                        
    [
        {
            recipientsCount: 2,
            statusMessage: "Success",
            statusCode: 101, 
            Balance: 8823,  //Remaining Account SMS Credits
            messageDetails: [
                {
                    recipient: "254728369514",
                    message: "Hello world",
                    statusCode: "Successfully Sent",
                    statusMessage: 2 
                },
                {
                    recipient: "254704544362",
                    message: "Hello world",
                    statusCode: "Successfully Sent",
                    statusMessage: 2
                }
            ]
        }
    ]                           
                                         
                                     

Error Codes #back to top

Here are a list of Error codes and their descriptions

101 - Success
102 - Queued
103 - Failed - Insufficient SMS Credits
104 - Wrong Credentials provided
105 - Invalid SenderId
106 - SenderId not Assigned to User
107 - Please supply both phonenumber and message parameters
108 - Ensure senderId is less than 11 characters
109 - SenderId does not exist
110 - SMS Credits not Enough to send all Messages