XML SMS API – EgoSms Documentation

Tutorials

Introduction

Authentication

SENDING SMS

BALANCE INQUIRY

SENDING SMS

Using XML

Overview

This method provides a way to send the message (SMS) via XML using account details.

Send SMS through your application by making an HTTP POST request to the following endpoints:

LIVE URL:https://www.egosms.co/api/v1/xml/

SANDBOX URL:http://sandbox.egosms.co/api/v1/xml/

XML Request Parameters

These are the standard request parameters that are needed when using the EgoSms XML Api

userdataString Required

Contains the user information.

msgdataString Required

Contains the message information.

usernameString Required

The account username.

passwordString Required

The account password.

numberString Required

The phone number the message is being sent to.

messageString Required

This represents the message you are sending out. The message source must have a maximum of 160 characters.

senderidString Required

This represents who the message is coming from. Sender can have a maximum of 11 characters.

Example

Example for sending a single message.

				
					<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <method>SendSms</method>
   <userdata>
      <username>Egotest</username>
      <password>xxxxx</password>
   </userdata>
   <msgdata>
      <number>256788200915</number>
      <message>welcome to Egosms</message>
      <senderid>Egosms</senderid>
   </msgdata>
</Request>

Example for sending multiple messages.

				
					<?xml version="1.0" encoding="UTF-8"?>
<Request>
   <method>SendSms</method>
   <userdata>
      <username>Egotest</username>
      <password>xxxxx</password>
   </userdata>
   <msgdata>
      <number>256788200915</number>
      <message>First message</message>
      <senderid>test</senderid>
   </msgdata>
   <msgdata>
      <number>256788200915</number>
      <message>Second message</message>
      <senderid>test</senderid>
   </msgdata>
   <msgdata>
      <number>256707811116</number>
      <message>Third message</message>
      <senderid>test</senderid>
   </msgdata>
   <msgdata>
      <number>256702662127</number>
      <message>Forth message</message>
      <senderid>test</senderid>
   </msgdata>
</Request>

System Feedback

On Success

Once your message has been successfully submitted to the EgoSms system, it will return xml in the format shown below:

				
					<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Status>OK</Status>
   <Cost>---</Cost>
   <MsgFollowUpUniqueCode>---</MsgFollowUpUniqueCode>
</Response>

On Failure

Once your message fails to be submitted to the EgoSms system, it will return xml in the format shown below:

				
					<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Status>Failed</Status>
   <Message>---</Message>
</Response>

Possible Error messages

Wrong XML passed.

Occurs when there is a syntax error in your XML code.

Money Not Enough To Send This Batch of Msgs.

Occurs if there are insuffient funds of your Egosms Account.

Wrong Username or Password.

Occurs if either your username or password is wrong.

That user does not exist or user not active

Occurs if the account being used does not exist or is inactive

Either Username or Password Not Set

Occurs if either the password or username is empty.

Programming Example

				
					<?php $xml_builder = '
    <?xml version="1.0" encoding="UTF-8"?>
    <Request> 
        <method>SendSms</method>
        <userdata> 
            <username>Egotest</username>
            <password>xxxxx</password>
        </userdata>
        <msgdata>
             <number>256702662127</number> 
             <message>test mtn</message> 
             <senderid>test</senderid>
        </msgdata> 
    </Request>';
    
    //use curl to post the xml information
    
    $ch = curl_init('https://www.egosms.co/api/v1/xml/');
    
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: text/xml'
    ));
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $xml_builder);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $ch_result = curl_exec($ch);
    curl_close($ch);
    echo $ch_result;
?>

				
					/**
 * Java API for Egosms Balance inquiry using JSON
 */
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLConnection;
import java.nio.charset.StandardCharsets;

public class CheckBalanceJSON {
	public static void main(String args[]) {
		try {
			/**
			 * Egosms url for Balance inquiry using JSON
			 */
			URL url = new URL("https://www.egosms.co/api/v1/json/");

			/**
			 * Opening the connection to the egosms JSON url
			 */
			URLConnection con = url.openConnection();
			HttpURLConnection http = (HttpURLConnection) con;

			/**
			 * Setting the request method to POST
			 */
			http.setRequestMethod("POST");
			http.setDoOutput(true);

			/**
			 * User name and password for a registered Egosms user
			 */
			String username = "Egosmstest";
			String password = "egotest";

			/**
			 * Passing the method(Balance), username and password in JSON format The method,
			 * username and password are appended to the url as parameters when sending the
			 * data
			 */
			byte[] out = ("{\"method\":\"Balance\"," + "\"userdata\":" + "{" + "\"username\":\"" + username + "\","
					+ "\"password\":\"" + password + "\"" + "}" + "}").getBytes(StandardCharsets.UTF_8);

			int length = out.length;

			//For Testing purposes
			String outString = new String(out);
			System.out.println("Content to send : " + outString);

			http.setFixedLengthStreamingMode(length);
			http.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
			http.connect();
			
			try (OutputStream os = http.getOutputStream()) {
				os.write(out);
			}

			/**
			 * Setting the input stream to read the response data
			 */
			BufferedReader in = new BufferedReader(new InputStreamReader(http.getInputStream()));
			String line = null;

			/**
			 * Printing the response data
			 */
			while ((line = in.readLine()) != null) {
				System.out.println(line);
			}

		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}