MSpace Bulk SMS Service API Documentation

This page illustrates how you, a developer, a technical personnel or any form of our esteemed client can use our bulk SMS services with ease without necessarily logging into our web application. After this illustration you will be able to send texts, query SMS account balance and list your sub- account users in the system. This documentation assumes that you have subscribed for our bulk SMS services. If not please visit our website ‘www.mspace.co.ke’ or contact our offices to be assisted and be able to enjoy our services.

How to generate api key

In order to use the sms api, one MUST have an api key to be included in all requests sent. If you don't have an api key, please sign up here. Below are the steps to follow to generate the key.

Login to the Bulk SMS system.
Click on the API tab, SMS and then Generate keys sub menu.
Input the name and select the user, then click on generate key. Once the Key has been generated you can copy it.

Send SMS

Request

Sending SMS can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/sendtext

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<sms>
    <username>Your_Username</username>
    <senderId>Your_Sender_Id</senderId>
    <recipient>0722XXXXXX,254733XXXXXX</recipient>
    <message>Your message.</message>
</sms>

GET Request:

The message should be UTF-8 URL-Encoded:

https://api.mspace.co.ke/smsapi/v2/sendtext/apikey=<your_api_key>/username=your_username/senderId=your_sender_id/recipient=0722XXXXXX,254733XXXXXX/message=Your message.

Response

The below response applies to both POST and GET requests.

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

Delivery Report

Request

Checking delivery report can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/deliveryreport

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<dlr>
    <username></username>
    <messageId>49032372</messageId>
</dlr>

GET Request:

https://api.mspace.co.ke/smsapi/v2/deliveryreport/apikey=<your_api_key>/username=/messageId=49032372

Response

The below response applies to both POST and GET requests.

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

SMS Balance

Request

Checking SMS balance can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/balance

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<user>
    <username>your_username</username>
</user>

GET Request:

https://api.mspace.co.ke/smsapi/v2/balance/apikey=<your_api_key>/username=your_username

Response

The below response applies to both POST and GET requests.

The response is an integer value that shows the sms balance.

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

Sub Users

Request

Quering sub users can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/subusers

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<user>
    <username>your_username</username>
</user>

GET Request:

https://api.mspace.co.ke/smsapi/v2/subusers/apikey=<your_api_key>/username=your_username

Response

The below response applies to both POST and GET requests.

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

Reseller Clients

Request

Quering reseller clients can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/resellerclients

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<user>
    <username>your_username</username>
</user>

GET Request:

https://api.mspace.co.ke/smsapi/v2/resellerclients/apikey=<your_api_key>/username=your_username

Response

The below response applies to both POST and GET requests.

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

Sub-Account Top Up

Request

Sub-Account top ups can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/subacctopup

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<subAccTopups>
    <username>Your_Username</username>
    <subaccname>Sub_Acc_Name</subaccname>
    <noOfSms>9000</noOfSms>
</subAccTopups>

GET Request:

https://api.mspace.co.ke/smsapi/v2/subacctopup/apikey=<your_api_key>/username=Your_Username/subaccname=Sub_Acc_Name/noofsms=9000

Response

The below response applies to both POST and GET requests.

The response is a plain string with a success message as below:


                            Successful Top up of 9000 SMS to <Sub_Acc_Name>

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

Reseller-Client Top Up

Request

Reseller-Client top ups can be done by doing either a POST or a GET Request. Both methods are shown below.

Endpoint: https://api.mspace.co.ke/smsapi/v2/resellerclienttopup

Header: apikey: <Your_api_key>

If you don't have the api key check the API Overview menu and follow the procedure to generate one.

POST Request:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/json"

"Accept": "application/json"

Body:

You can also do a POST request using xml body instead of json. Below is the how to:

Headers:

"apikey": "your_api_key"

"Content-Type": "application/xml"

"Accept": "application/xml"

Body:

<resellerClientTopups>
    <username>Your_Username</username>
    <clientname>Client_Name</clientname>
    <noOfSms>1000</noOfSms>
</resellerClientTopups>

GET Request:

https://api.mspace.co.ke/smsapi/v2/resellerclienttopup/apikey=<your_api_key>/username=your_username/clientname=Client_Name/noofsms=1000

Response

The below response applies to both POST and GET requests.

The response is a plain string with a success message as below:


                            Successful Top up of 9000 SMS to <Client_Name>

Errors:

To any errors encountered such as status 400, 404 etc;

Ensure endpoint url is correct
Ensure the endpoint type is correct: ie Get or POST
Ensure apikey is spelled correctly not ApiKey. Same for all parameters if any.

Sample Codes:

MSpace Bulk SMS Service API Documentation

This page illustrates how you, a developer, a technical personnel or any form of our esteemed client can use our bulk SMS services with ease without necessarily logging into our web application. After this illustration you will be able to send texts, query SMS account balance and list your sub- account users in the system. This documentation assumes that you have subscribed for our bulk SMS services. If not please visit our website âwww.mspace.co.keâ or contact our offices to be assisted and be able to enjoy our services.

OverView of the API

Content

Query SMS balance
Send Text
Query sub-account users
Query Re-seller users
System Login
Re-seller client Top up
sub-account users Top up

Overview

This is the get balance url = â http://main_url/mspaceservice/wr/sms/balance /username={username}/password={password}â, where username is the value of your username and password the value of your password.

To get the IP to replace the main_url example kindly contact us.

Example:

http://main_url/mspaceservice/wr/sms/balance /username=myusername/password=mypassword

You can test this by pasting in your browser and press enter.

Response:

âyour sms balance e.g. â50ââ if you are a subscribed user or âError 100: Authentication Failureâ if your credentials are wrong.

NOTE that your URL format should support URL encoding UTF- 8 . Messages that are not properly formatted may be delivered with incorrectly encoded text or not delivered at all.

The request methods are summarized in the table below:

main_url = http://main_url/mspaceservice/wr/sms

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.

Java Client

Object type to be returned

Helper Methods

public String encodeMessage(String message) {
    try {
        return URLEncoder.encode(message, "UTF-8").replaceAll("\\+", "%20");
    } catch (UnsupportedEncodingException ex) {
        Logger.getLogger("logger").log(Level.SEVERE, (String) null, ex);
        return message;
    }
}

public Response sendRequest(String link) {
        Response response = new Response(0, "Request could not be completed. Anonimous Error occured.");
        try {
            String formatUrl = String.format("%s%s", "http://api.mspace.co.ke/mspaceservice/wr/sms/", link);
            URL url = new URL(formatUrl);
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            con.setRequestMethod("GET");
            int status = con.getResponseCode();
            response = new Response(status, "Request could not be completed. Anonimous Error occured.");
            if (status == 200) {
                StringBuilder content;
                try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
                    content = new StringBuilder();
                    String inputLine;
                    while ((inputLine = in.readLine()) != null) {
                        content.append(inputLine);
                }
            }
            response = new Response(status, content.toString());
        }
    } catch (IOException ex) {
        Logger.getLogger(Test.class.getName()).log(Level.SEVERE, (String) null, ex);
    }
    return response;
}

Sending one message

Sending many messages

Sub-user Topup

Reseller Topup

Query Clients

Query Sub-Users

Query Balance

Old Library

Java developers can be emailed or obtain the java client API jar file bundled with dependencies here and add into the class-path of their project. Having this jar file, your work will be made easier. The API contains all the request methods:

sendMessage_JSON
sendMessage_XML
subUsers_XML
subUsers_JSON
System Login
Re-Seller Top-Up
Sub-Account Top-Up
Re-SellerClients_XML
Re-SellerClients_JSON
getBalance
close

sendMessage_ JSON

 subUsers_JSON(Class responseType, String username, String password, String senderid, String recipient,
                                                String message);

Returns JSON object of the returned value by this method, example:

sendMessage_XML

 subUsers_XML(Class responseType, String username, String password, String senderid, String recipient,
                                                String message);

Returns XML object of the returned value by this method, example:

subUsers_XML

subUsers_XML(Class responseType, String username, String password);

Returns XML object of the returned value by this method, example:

subUsers_JSON

  subUsers_JSON(Class responseType, String username, String password);

Returns JSON object of the returned value by this method,

example:

System Login

 login_TEXT(this.username, this.password);

Returns PLAIN_TEXT object of the returned value by this method, example:

Re-Seller Top-Up

 resellerClientTopup_XML(Class responseType, this.reselerUsername, this.resellerPassword, this.clientName, this.noOfsms);

Returns XML object of the returned value by this method,

example:

Sub-Account Top-Up

 subAccTopup_JSON(Class responseType, this.mainAccname, this.mainAccPassword, this.subAccname, this.noOfsms);

Returns JSON object of the returned value by this method,

example:

resellerClients_XML

resellerClients_XML(Class responseType, String username, String password);

Returns XML object of the returned value by this method, example:

resellerClients_JSON

resellerClients_JSON(Class responseType, String username, String password);

Returns JSON object of the returned value by this method,

example:

getBalance

getBalance(String username, String password);

Returns PLAIN_TEXT object of the returned value by this method, example:

Closes the client instance.

To view your full request url, method type and request status by the API methods use Response class as the response type. Example:

Output: InboundJaxrsResponse{ ClientResponse{method=GET, uri=http://main_url/mspaceservice/ wr/sms/subusers/username= myusername/password=mypassword, status=200, reason=OK}}

Python Client

To get the IP to replace the main_url example kindly contact us.

The following methods are for python users.
main_api = "http://main_url/mspaceservice/wr/sms/"

#For Python 3.x

#get sub-account users

#get user balance

#send message

PHP Client

To get the IP to replace the main_url example kindly contact us.

All methods Captured

<?php
$curl = curl_init();
$main_url = "http://api.mspace.co.ke/mspaceservice/wr/sms/";

$data = array(
    'username' => 'myusername',
    'password' => 'mypassword'
);
$my_message = 'this is some test message';
$data2 = array(
    'username' => 'myusername',
    'password' => 'mypassword',
    'senderid' => 'mysenderid',
    'recipient' => 'myrecipient',//should be a valid contact number
    'message' => urlencode($my_message)
);

$subuserUrl = "subusers/" . str_replace("&","/",http_build_query($data)); //use this to get subusers
$balanceUrl = "balance/" . str_replace("&","/",http_build_query($data)); //use this to get balance
$sendtextUrl = "sendtext/" . str_replace("+","%20",(str_replace("&","/",http_build_query($data2)));

//use this to send text and get response
curl_setopt_array($curl, array(
    CURLOPT_URL => $main_url . $subuserUrl, //returns full http url for sub-account method. Replace
    $subuserUrl with $balanceUrl or $sendtextUrl variable to complete main url with subuser or
    balance url parts respectively.
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
    "accept: application/json" //can change to application/xml for sub-account and sendtext methods or plain_text for balance method as per this documentation
    ),
));

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response.â\nâ;
}
?>

C# Client

To get the IP to replace the main_url example kindly contact us.

Send Message

using System.Net;

public class WebRequestGetExample{
    public static void Main(){

string mainUrl = "http://api.mspace.co.ke/mspaceservice/wr/sms/";
        string sendData = "sendtext/username={username}/password={password}/senderid={senderid}/recipient={receipientphone}/message={message}";
        string url=mainUrl+sendData;
        // Create a request for the URL.
        WebRequest request = WebRequest.Create(url);
        //http://main_url/mspaceservice/wr/sms/sendtext/username=myusername/password=mypassword/senderid=mysenderid/recipient=myrecipient/message=mymessage
        //http://main_url/mspaceservice/wr/sms/subusers/username=myusername/password=mypassword
        //http://main_url/mspaceservice/wr/sms/login/username=myusername/password=mypassword
        //http://main_url/mspaceservice/wr/sms/resellerclienttopup/username=myusername/password=mypassword/clientname=myclientname/noofsms=noofsms
        //http://main_url/mspaceservice/wr/sms/subacctopup/username=myusername/password=mypassword/subaccname=mysubaccname/noofsms=noofsms
        // If required by the server, set the credentials.
        // request.Credentials = CredentialCache.DefCredentials;

// Get the response.
        WebResponse response = request.GetResponse();
        // Display the status.
        Console.WriteLine(((HttpWebResponse)response).StatusDescription);

// Get the stream containing content returned by the server.
        // The using block ensures the stream is automatically closed.
        using (Stream dataStream = response.GetResponseStream())
        {
        // Open the stream using a StreamReader for easy access.
        StreamReader reader = new StreamReader(dataStream);
        // Read the content.
        string responseFromServer = reader.ReadToEnd();
        // Display the content.
        Console.WriteLine(responseFromServer);
        }

// Close the response.
        response.Close();
    }
}

Bulk SMS Wordpress Plugin Installation

Many website are designed on top of wordpress CRM. MSpace has developed a plugin to enable customers easily integrate their wordpress with Bulk SMS. This plugin supports below:

Woocommerce
Contact Form 7
Custom PHP code
Widget

Installation

Method 1

Download the zipped plugin here
Open your wordpress plugin page -> Click Add New -> Upload Plugin -> Browse. Select the wp-sms.zip you downloaded above and then click on Install Now
After successfull install, visit the plugins page and activate it then refresh your page. Your will get a new menu namely SMS

Method 2

Download the zipped plugin here
Copy the zip into {PATH_TO_WORDPRESS}/wordpress/plugins/ folder and unzip it
Visit the plugins poage and activate it then refresh your page. Your will get a new menu namely SMS

Enabling Gateway

Click on on the plugin menu (SMS) in your wordpress admin -> Select Settings -> Click on Gateway

Select mspace.co.ke on Gateway Name Drop-down
Enter your Mspace Bulk SMS account username in API username field
Enter your Mspace Bulk SMS account password in API password field
Enter your Mspace Bulk SMS sender id in Sender number field
Leave API key field empty
Scroll Down and click on Save Changes button. Ignore any warnings

Activate Bulk SMS Api on Contact Form 7 and WooCommerce

On the plugin setting page above, select Integration.

To activate the plugin on Contact Form 7, ensure the SMS meta box radio is ticked
To activate the plugin on woocommerce, ensure radio button for New order is ticked. Create the message body as per the instructions. This will automatically send sms to clients when the make new orders on the e-commerce site

The widget for the plugin is available on all your widgets areas.

To use the plugin in your PHP code, see below example:

Other Features

Send SMS

You can send sms from your wordpress by selecting the plugin menu Send SMS. Select either subscribers -users who have filled in their details from your website forms. or your wordpress users and also to your custom mobile numbers.

SMS Newsletter

Send Newsletter via SMS

Wordpress SMS Notification

Notify your subcribers when you have a new post etc.

Send Activation Codes

You can enable sending activation codes to your subscribers. This will ensure that all your subscribers are genuine.

Use Actions

Below actions are available. Send emails when sending SMS Send welcome SMS to users when they are registered.

Wordpress Hooks

Modify Numbers Add New Numbers Modify text messages

Export Your Subscribers

Export your subscribers to csv.

Rest API

Rest API is available so that you can integrate your wordpress SMS with other systems. Currently supports only one endpoint as below. This is for adding new subscribers to SMS newsletters

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

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

Kenya offices

+254722962934

info@mspace.co.ke

Uganda offices

0414-672051.

info@mspacesolutions.com

Elysee(Ntashart) Plaza, Kilimani Road, 2nd Floor Suite 4A

Kampala, Makerere Hill Road, Ham Towers, 3rd floor, Suite No HT 25

Our Vision

Become the premier mobile solutions provider in East Africa.

Our Mission

To offer innovative, cutting edge, value adding mobile solutions, offering superior products and outstanding services through the use of modern, reliable and cost effective ICT technologies.

Core values

Innovation
Reliability
Excellent and friendly Support
Trustworthy and Honesty
Quality
Integrity
Teamwork
Efficiency

Our Pillars

We are committed to the three pillars that form the foundation of MSpace Solutions.

Offering competitive pricing
Ensuring innovative ideas
Ensuring value added services