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={pass word}”, 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	Url Structure	Url example	Response on success	Response on failure
Query SMS Balance	main_url + balance/username= {username}/password= {password}	`http://main_url/balance/ username=myusername/ password=mypassword`	Your current SMS balance e.g. “50”.	Authentication failure for wrong user credentials or non-existing user. Internal service error if there’s any.
Send Text	main_url +sendtext/username= {username}/password ={password}/senderid ={senderId}/recipient ={recipient}/message ={message}	`http://main_url/sendtext/username =myusername/password =mypassword/senderid =mysenderid/recipient =myrecipient/message =mymessage`>	Send action status and the sent message id i.e. “[{"messageId":"12345","responseTime":"2018-06-25 11:12:19:793","status":"successful"}]”	Athentication failure, Insufficient Balance, Invalid sender ID or internal service error.
Query sub-account users	main_url + subusers/username ={username}/password ={password}	`http://main_url/subusers/username =myusername/password =mypassword`	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.	Authentication failure.
Query Re-Seller users	main_url + resellerclients/username ={username}/password ={password}	`http://main_url/resellerclients/username =myusername/password =mypassword`	The username of your clients and their SMS balances respectively i.e. “[{"smsBalance":"20","clientname":"client1"}, {"smsBalance":"18","clientname":"client2"}]” “[]” if no user exists.	Authentication failure.
Re-Seller users Top-up	main_url + resellerclienttopup/username ={username}/password ={password} /clientname ={clientname}/noofsms ={noofsms}	`http://main_url/resellerclienttopup/username =myusername/password =mypassword /clientname ={myclientname}/noofsms ={noofsms}`	Successful Top up of noOfSms SMS to clientname.	Athentication failure, Insufficient Balance,You are not Authorized to make this transaction,Kindly Contact Providers for help, Failed to top up clientname account, Top up not Successful, failed to deduct your account, or internal service error.
Sub-Account users Top-up	main_url + subacctopup/username ={username}/password ={password} /subaccname ={subaccname}/noofsms ={noofsms}	`http://main_url/subacctopup/username =myusername/password =mypassword /subaccname ={mysubaccname}/noofsms ={noofsms}`	Successful Top up of noOfSms SMS to subAccName.	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.
System Login	main_url + login/username ={username}/password ={password}	`http://main_url/login/username =myusername/password =mypassword`	user exists.	Authentication failure.

Java Client

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

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/pas sword=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/"

#get sub-account users

#get user balance

#send message

def sendMessage(username, password, senderid, recipient, message):
                                                url = main_api + "sendtext/" + urllib.parse.urlencode({"username": username}) \
                                                + "/" + urllib.parse.urlencode({"password": password}) \
                                                + "/" + urllib.parse.urlencode({"senderid": senderid})\
                                                + "/" + urllib.parse.urlencode({"recipient": recipient})\
                                                + "/" + urllib.parse.urlencode({"message": message},
                                                quote_via=urllib.parse.quote)
                                                json_data = requests.get(url, headers).json()
                                                return json_data
                                                #test response
                                                print(sendMessage("myusername", "mypassword", "mysenderId", "07XXXXXXXX", "Test Message"))

PHP Client

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

All methods Captured

<?php
// Your code here!
  $curl = curl_init();
                                            $main_url = "http://main_url/mspaceservice/wr/sms/";
                                            $data = array(
                                            'username' => 'yourUsername',
                                            'password' => 'yourPassword'
                                            );
                                            $my_message = 'Dear Someone,This is Mspace test php api integration.
                                            112233445566778899 Saturn V rocket’s first stage carries 203,400 gallons (770,000 liters) of kerosene fuel and 318,000 gallons (1.2 million liters) of liquid oxygen needed for combustion.
                                            At liftoff, the stage’s five F-1 rocket engines ignite and produce 7.5 million pounds of thrust.';
                                            $data2 = array(
                                            'username' => 'yourUsername',
                                            'password' => 'yourPassword',
                                            'senderid' => 'yourSendeId',
                                            'recipient' => '2547XXXXXXXX',//should be a valid contact number
                                            'message' => myUrlEncode($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("%2B","%20",(str_replace("&","/",http_build_query($data2))));
                                           $sendtextUrl = "sendtext/" . str_replace("%2B","%20",(str_replace("&","/", http_build_query($data2))));
                                            echo($sendtextUrl);
                                            //use this to send text and get response
                                            curl_setopt_array($curl, array(
                                            CURLOPT_URL => $main_url . $sendtextUrl, //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";
                                            }

function myUrlEncode($string) {
    $entities = array('%21', '%2A', '%E2%80%99s', '%28', '%29', '%3B', '%3A', '%40', '%26', '%3D', '%2B', '%24', '%2C', '%2F', '%3F', '%25', '%23', '%5B', '%5D','%0A', '%27');
    $replacements = array('!', '*', "'", "(", ")", ";", ":", "@", "&", "=", "+", "$", ",", "/", "?", "%", "#", "[", "]","", "'");
    return str_replace($entities, $replacements, urlencode($string));
}
                                            ?>

VB.NET Client

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

Send Message

Imports System.IO
Imports System.Net
Imports System
Public Module Module1
	Public Sub Main()
        ' Create a request for the URL.
        Dim request As WebRequest =
		WebRequest.Create("http://main_url/mspaceservice/wr/sms/sendtext/username=myUsername/password=myPassword/senderid=mySenderID/recipient=2547XXXXXXXXXX/message=mymessageTest")
		'WebRequest.Create("http://main_url/mspaceservice/wr/sms/sendtext/username=myUsername/password=myPassword/senderid=mySenderID/recipient=2547XXXXXXXXXX/message=mymessageTest")
		' WebRequest.Create("http://main_url/mspaceservice/wr/sms/subusers/username=myUsername/password=myPassword")
		' WebRequest.Create("http://main_url/mspaceservice/wr/sms/balance/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.DefaultCredentials
        ' Get the response.
        Dim response As WebResponse = request.GetResponse()
        ' Display the status.
        Console.WriteLine(CType(response, HttpWebResponse).StatusDescription)
        ' Get the stream containing content returned by the server.
        Dim dataStream As Stream = response.GetResponseStream()
        ' Open the stream using a StreamReader for easy access.
        Dim reader As New StreamReader(dataStream)
        ' Read the content.
        Dim responseFromServer As String = reader.ReadToEnd()
        ' Display the content.
        Console.WriteLine(responseFromServer)
        ' Clean up the streams and the response.
        reader.Close()
        response.Close()
	End Sub
End Module

C# Client

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

Send Message

using System;
using System.IO;
using System.Net;

namespace Examples.System.Net
{
    public class WebRequestGetExample
    {
        public static void Main()
        {
            // Create a request for the URL.
            WebRequest request = WebRequest.Create("http://main_url/mspaceservice/wr/sms/balance/username=myUsername/password=myPassword");
			//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();
        }
    }
}