Bulk SMS KENYA | Free SMS API | MSpace Solutions Ltd

Method	Query SMS Balance
Url Structure	main_url/balance/username={username}/password={password}
Url example	`http://main_url/balance/username=myusername/password=mypassword`
Response on success	Your current SMS balance e.g. â50â.
Response on failure	Authentication failure for wrong user credentials or non-existing user.

Method	Send Text
Url Structure	main_url/sendtext/username={username}/password={password}/senderid={senderId}/recipient={recipient}/message={message}
Url example	`http://main_url/sendtext/username=myusername/password=mypassword/senderid=mysenderid/recipient=myrecipient/message=mymessage`
Response on success	Send action status and the sent message id i.e.â[{"messageId": "12345", "responseTime": "2018-06-2511:12:19:793", "status": "successful"}]â
Response on failure	Athentication failure,Insufficient Balance, Invalid sender ID or internal service error.

Method	Query sub-account users
Url Structure	main_url/subusers/username={username}/password={password}
Url example	`http://main_url/subusers/username=myusername/password=mypassword`
Response on success	The username of your sub-account users and their SMS balances respectively i.e. â[{"smsBalance": "20", "subUserName": "subuser1"},{"smsBalance": "18", "subUserName": "subuser2"}]ââ[]â if no subuser exists.
Response on failure	Authentication failure.

Method	Query Re-Seller users
Url Structure	main_url/resellerclients/username={username}/password={password}
Url example	`http://main_url/resellerclients/username=myusername/password=mypassword`
Response on success	The username of your clients and their SMS balances respectively i.e. â[{"smsBalance": "20", "clientname": "client1"}, {"smsBalance": "18", "clientname": "client2"}]â
Response on failure	Authentication failure.

Method	Re-Seller users Top-up
Url Structure	main_url/resellerclienttopup/username={username}/password={password} /clientname={clientname}/noofsms={noofsms}
Url example	`http://main_url/resellerclienttopup/username=myusername/password=mypassword/clientname={myclientname}/noofsms={noofsms}`
Response on success	Successful Top up of noOfSms SMS to clientname.
Response on failure	Athentication failure, Insufficient Balance, You are not Authorized to make this transaction, indly Contact Providers for help, Failed to top up clientname account, Top up not Successful, Failed to deduct your account, or internal service error.

Method	Sub-Account users Top-up
Url Structure	main_url/subacctopup/username={username}/password={password}/subaccname={subaccname}/noofsms={noofsms}
Url example	`http://main_url/subacctopup/username=myusername/password=mypassword/subaccname={mysubaccname}/noofsms={noofsms}`
Response on success	Successful Top up of noOfSms SMS to subAccName.
Response on failure	Athentication failure, Insufficient Balance,You are not Authorized to make this transaction,Kindly Contact Providers for help, Failed to top up subAccName account, Top up not Successful, failed to deduct your account, or internal service error.

Method	System Login
Url Structure	main_url/login/username={username}/password={password}
Url example	`http://main_url/login/username=myusername/password=mypassword`
Response on success	User exists.
Response on failure	Authentication failure.

NAME	DESCRIPTION
system _ id	Provided for each client
password	Provided for each client
IP address	To be provided
port	2775
timeout (keep alive)	50 sec

MSpace USSD API Documentation

This page illustrates how you, a developer, a technical personnel or any form of our esteemed customers can access the MSPace USSD API with ease

Content

For a user to process any USSD request with MSpace Solutions, one needs to setup an account with us. Once that is done, the following follows.

Registration of a service code that will explicitly represent the company at hand offered products or services. This service code is used at hand with MSpace’s service code 702 in our servers. For example if your service code is 75, the new USSD string becomes *702*75#.
Provide a callback URL. This URL will be invoked whenever a request hits our servers to provide the given menu’s for a user to access the given information therein

The callback URL will be triggered by http POST request. The response being sent will be the menus created, for example

Deposit
Withdraw
Buy Airtime
Unsunbscibe
Terms and Conditions

Sending a Request

A USSD mobile request must have the MSSDN,SESSION_ID,CALLBACK_URL, USER_DATA information appended to it. This request will be sent to the third party ia the endpoint URL provide by the client. This data is JSON formatted

ELEMENT NAME	DESCRIPTION
MSISDN	This is the mobile number that sends the POST request.
SESSION_ID	This is the session id. It’s unique to every request send. It represents a single USSD session.
CALLBACK_URL	Provided by the client. It will be triggered any time a request is sent.
USSD_STRING	This is the information a user enters as he interacts with the USSD menus. This data is stored in a database
SERVICE_CODE	This is the code provided by the client that will be used in the API parameters

Sending a Response

USSD is session driven. Generated response represents menus that will be shown to the person dialing the USSD code. USSD uses CON keyword to initiate a connection and END keyword to end a session. In the case of an error, a malformed response will be sent and the USSD session will terminate immediately and the USSD application flow will break.

Creating Menu Strings in Java

@WebServlet(name = "JavaSSD", urlPatterns = {"/ssd"})
public class JavaSSD extends HttpServlet {

private final String mainMenu = "1. Check Balance\n2. Top Up\n3. Exit";
    private final String ASSIGNED_CODE = "90"; //Assuming your assigned code is 90

@Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        String ussdString = request.getParameter("USSD_STRING");
        String servletResponse = "";

if (ASSIGNED_CODE.equals(ussdString)) {
            servletResponse = "CON Welcome to our MSpace USSD service. \n" + mainMenu;
        } else if (!ASSIGNED_CODE.equals(ussdString)) {
            switch (ussdString) {
                case ASSIGNED_CODE+"*1":
                    servletResponse = "END Your current balance is KES100.";
                    break;
                case ASSIGNED_CODE+"*2":
                    servletResponse = "CON Enter the amount you would like to top up:";
                    break;
                case ASSIGNED_CODE+"*3":
                    servletResponse = "END Thank you for using our service. Goodbye.";
                    break;
                default:
                    servletResponse = "END "+mainMenu;
                    servletResponse += " Invalid option. Please try again.";
                    break;
            }
        } 
        response.getWriter().println(servletResponse);
    }

}

Creating Menu Strings in PHP

<?php
    $main_menu = "1. Check Balance\n2. Top Up\n3. Exit";

if($_SERVER['REQUEST_METHOD'] == "GET") {

$var=$_GET['USSD_STRING']; //gets the assigned code passed
    $myAsssignedCode="90";//Assuming your assigned code is 90.
        $menu = "";

if ($var == $myAsssignedCode) {

$menu = "CON Welcome to our MSpace USSD service.\n";
            $menu .= $main_menu;

}
        elseif ($var !== $myAsssignedCode) {
            if ($var == "1") {

$menu = "END Your current balance is KES100.";
            } elseif ($var == "2") {
                $menu = "CON Enter the amount you would like to top up:";

} elseif ($var == "3") {

$menu = "END Thank you for using our service. Goodbye.";
            } else {
                $menu ="END " . $main_menu;
                $menu .= " Invalid option. Please try again.";
            }
        } else {

$menu = "CON An error has occurred.";
        }

echo $menu;
    }
?>

Creating Menu Strings in Python

import http.server
import socketserver

MAIN_MENU = "1. Check Balance\n2. Top Up\n3. Exit"
MY_ASSIGNED_CODE = "90" #Assuming your assigned code is 90

class USSDRequestHandler(http.server.BaseHTTPRequestHandler):

def do_GET(self):
        query = self.path[2:]
        query_dict = dict(q.split("=") for q in query.split("&"))

ussd_string = query_dict.get("USSD_STRING") #Gets the assigned code passed

menu = ""
        if ussd_string == MY_ASSIGNED_CODE:
            menu = "CON Welcome to our MSpace USSD service.\n"
            menu += MAIN_MENU
        elif ussd_string != MY_ASSIGNED_CODE:
            if ussd_string == MY_ASSIGNED_CODE+"*1":
                menu = "END Your current balance is KES100."
            elif ussd_string == MY_ASSIGNED_CODE+"*2":
                menu = "CON Enter the amount you would like to top up:"
            elif ussd_string == MY_ASSIGNED_CODE+"*3":
                menu = "END Thank you for using our service. Goodbye."
            else:
                menu = "END " + MAIN_MENU
                menu += " Invalid option. Please try again."
        else:
            menu = "CON An error has occurred."

self.send_response(200)
        self.send_header("Content-type", "text/plain")
        self.end_headers()
        self.wfile.write(bytes(menu, "utf-8"))

httpd = socketserver.TCPServer(("", 8080), USSDRequestHandler)
httpd.serve_forever()

Creating Menu Strings in Javascript(Expressjs)

const express = require('express');
const app = express();

const MAIN_MENU = "1. Check Balance\n2. Top Up\n3. Exit";
const MY_ASSIGNED_CODE = "90"; //Assuming your assigned code is 90

app.get('/', (req, res) => {
  const ussd_string = req.query.USSD_STRING; //Gets the assigned code passed
  let menu = "";

if (ussd_string === MY_ASSIGNED_CODE) {
    menu = "CON Welcome to our MSpace USSD service.\n";
    menu += MAIN_MENU;
  } else if (ussd_string.startsWith(MY_ASSIGNED_CODE+"*")) {
    switch (ussd_string) {
      case MY_ASSIGNED_CODE + "*1":
        menu = "END Your current balance is KES100.";
        break;
      case MY_ASSIGNED_CODE + "*2":
        menu = "CON Enter the amount you would like to top up:";
        break;
      case MY_ASSIGNED_CODE + "*3":
        menu = "END Thank you for using our service. Goodbye.";
        break;
      default:
        menu = "END " + MAIN_MENU;
        menu += " Invalid option. Please try again.";
    }
  } else {
    menu = "CON An error has occurred.";
  }

res.set('Content-Type', 'text/plain');
  res.send(menu);
});

const server = app.listen(8081, () => {
  console.log(`Server running on port `);
});

MSpace Bulk SMS Service API Documentation

How to generate api key

Send SMS

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

Delivery Report

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

SMS Balance

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

Sub Users

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

Reseller Clients

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

Sub-Account Top Up

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

Reseller-Client Top Up

Request

POST Request:

Headers:

Body:

Headers:

Body:

GET Request:

Response

Errors:

Sample Codes:

MSpace Bulk SMS Service API Documentation