Sending SMS Using JSON
Overview
This method provides a way to send the message (SMS) via JSON 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/json/
SANDBOX URL: http://sandbox.egosms.co/api/v1/json/
JSON Request Parameters
These are the standard request parameters that are needed when using the EgoSms JSON API
username String Required
The API callers username used to login to Egosms.
password String Required
The URL encoded password to your Ego Sms Account
number String Required
The phone number the message is being sent to.
message String Required
This represents the URL encoded SMS you are sending out. The message source must have a maximum of 160 characters.
sender String Required
This represents who the message is coming from. Sender can have a maximum of 11 characters and needs to be URL encoded too.
PriorityString Optional
This represents level of priority. Priority can have values from (0-4) with 0: highest, 1: high, 2: Medium, 3: Low, 4: Lowest
Request format
Request for sending one message.
{
"method":"SendSms",
"userdata":{
"username":"xxxxxx",
"password":"xxxxxx"
},
"msgdata":[
{
"number":"2567xxxxxxxx",
"message":"xxxxxx",
"senderid":"xxxxxx",
"priority":"0"
}
]
}
Request for sending multiple messages.
{
"method":"SendSms",
"userdata":{
"username":"xxxxxxxx",
"password":"xxxxxxxx"
},
"msgdata":[
{
"number":"2567xxxxxxxxx",
"message":"First Message",
"senderid":"Egosms",
"priority":"0"
},
{
"number":"2567xxxxxxxxx",
"message":"Second Message",
"senderid":"Egosms",
"priority":"0"
},
{
"number":"2567xxxxxxxxx",
"message":"Third Message",
"senderid":"Egosms",
"priority":"0"
},
{
"number":"2567xxxxxxxxx",
"message":"Fourth message",
"senderid":"Egosms",
"priority":"0"
}
]
}
System Feedback
A Successful Request
Once your message has been successfully submitted to the Egosms system, it will return Json in the format shown below.
{
"Status":"OK",
"Cost":"xxxx",
"MsgFollowUpUniqueCode":"xxxxx"
}
A Failed Request
Once the request fails, JSON in the format below will be returned.
{
"Status":"Failed",
"Message":"xxxxxx"
}
Example
Submitted JSON
{
"method":"SendSms",
"userdata":{
"username":"Egotest",
"password":"xxxxxxxx"
},
"msgdata":[
{
"number":"256707811113",
"message":"Welcome to Egosms",
"senderid":"Egosms",
"priority":"0"
}
]
}
Returned JSON for a Successful Request
{
"Status":"OK",
"Cost":"35",
"MsgFollowUpUniqueCode":"ApiJsonSubmit53b5155c1a3f90.65989312"
}
Returned JSON for a Failed Request
{
"Status":"Failed",
"Message":" Error Response message"
}
Possible Errors
Error
Meaning
Wrong JSON Passed
Occurs if there is a syntax error in your json code.
Money Not Enough To Send This Batch of Msgs
Occurs if there are insufficient funds on the sender’s account.
Wrong Username or Password
Occurs if either the password or username is wrong.
That user does not exist or user not active
Occurs if the user account does not exist or is inactive.
Either Username or Password Not Set
Occurs if either the username or password is empty.
Programming Example
PHP
PYTHON
JAVA
RUBY
Curl
C#
PHP
$data = array(
'method' => 'SendSms',
'userdata' => array(
'username' => 'Egotest', // Egosms Username
'password' => 'xxxxxxx', // Egosms Password
'msgdata' => array(
array(
'number' => 256707811113,
'message' => 'elias',
'senderid' => 'Good'
) ,
array(
'number' => 256788200915,
'message' => 'marvin',
'senderid' => 'Bad'
)
)
);
//encode the array into json
$json_builder = json_encode($data);
//use curl to post the the json encoded information
$ch = curl_init('https://www.egosms.co/api/v1/json/');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json'
));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_builder);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$ch_result = curl_exec($ch);
curl_close($ch);
//print an array that is json decoded
print_r(json_decode($ch_result, true));
PYTHON
# importing the requests library
import json
import requests
import html
# The api url
url = "https://www.egosms.co/api/v1/json/"
# The parameters to be sent to the ego sms api
password = "xxxxx"
username = "egotest"
senderid = "Egosms"
number = "256707811113"
message = "This is a message to be sent using the python programming language"
# data to be sent to api
data = {"method": "SendSms",
"userdata":
{
"username": html.escape(username),
"password": html.escape(password)
},
"msgdata":
[{
"message": html.escape(message),
"number": html.escape(number),
"senderid": html.escape(senderid),
}]
}
data_in_json = json.dumps(data)
timeout = 5
# Check whether there is an internet connection and make the request
try:
# sending post request and saving response as response object
r = requests.post(url=url, data=data_in_json, timeout=timeout)
# extracting response text
response = r.text
print(response)
except(requests.ConnectionError, requests.Timeout) as exception:
print("Check your internet connection")
JAVA
package 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 SendJson {
public static void main(String[] args) {
try {
//Setting up the connection
URL url = new URL("https://www.egosms.co/api/v1/json/");
URLConnection con = url.openConnection();
HttpURLConnection http = (HttpURLConnection)con;
http.setRequestMethod("POST");
http.setDoOutput(true);
//Details to be sent
String username = "EgosmsTest";
String password = "egotest";
String message = "My first message through Egosms";
String number = "256788200915";
String senderid = "Egosms";
//Creating JSON format of the details above
byte[] out = ("{\"method\":\"SendSms\"," +
"\"userdata\":" +
"{" +
"\"username\":\""+username+"\"," +
"\"password\":\""+password+"\"" +
"}," +
"\"msgdata\":[" +
"{" +
"\"number\":\""+number+"\"," +
"\"message\":\""+message+"\"," +
"\"senderid\":\""+senderid+"\"" +
"}" +
"]" +
"}").getBytes(StandardCharsets.UTF_8);
int length = out.length;
//Sending the details through established connection
http.setFixedLengthStreamingMode(length);
http.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
http.connect();
try(OutputStream os = http.getOutputStream()) {
os.write(out);
}
//Receiving response
BufferedReader in = new BufferedReader(new InputStreamReader(http.getInputStream()));
String line = null;
while((line = in.readLine()) != null) {
System.out.println(line);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
RUBY
require 'net/http'
require 'uri'
require 'json'
# The API URL
url = URI.parse("https://www.egosms.co/api/v1/json/")
# The parameters to be sent to the ego sms API
password = "xxxxx"
username = "egotest"
senderid = "Egosms"
number = "256707811113"
message = "This is a message to be sent using the python programming language"
# Create the request data
data = {
"method": "SendSms",
"userdata": {
"username": URI.escape(username),
"password": URI.escape(password)
},
"msgdata": [{
"message": URI.escape(message),
"number": URI.escape(number),
"senderid": URI.escape(senderid)
}]
}
# Convert the data to JSON
data_in_json = JSON.generate(data)
timeout = 5
# Check whether there is an internet connection and make the request
begin
# Create the HTTP request
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
# Set the request timeout
http.read_timeout = timeout
http.open_timeout = timeout
# Create the POST request
request = Net::HTTP::Post.new(url.path, {'Content-Type' => 'application/json'})
request.body = data_in_json
# Send the request
response = http.request(request)
# Extract the response text
response_text = response.body
puts response_text
rescue Errno::ECONNREFUSED, Net::ReadTimeout => e
puts "Check your internet connection"
end
Curl
#!/bin/bash
# The API URL
url="https://www.egosms.co/api/v1/json/"
# The parameters to be sent to the ego sms API
password="xxxxx"
username="egotest"
senderid="Egosms"
number="256707811113"
message="This is a message to be sent using the python programming language"
# Create the request data
data="{\"method\": \"SendSms\",
\"userdata\": {
\"username\": \"$username\",
\"password\": \"$password\"
},
\"msgdata\": [{
\"message\": \"$message\",
\"number\": \"$number\",
\"senderid\": \"$senderid\"
}]
}"
timeout=5
# Check whether there is an internet connection and make the request
if curl -sS --connect-timeout $timeout --max-time $timeout -X POST -H "Content-Type: application/json" -d "$data" "$url"; then
echo "Request successful."
else
echo "Check your internet connection."
fi
C#
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
class Program
{
static async System.Threading.Tasks.Task Main(string[] args)
{
var data = new
{
method = "SendSms",
userdata = new
{
username = "Egotest", // Egosms Username
password = "xxxxxxx" // Egosms Password
},
msgdata = new[]
{
new
{
number = 256707811113,
message = "elias",
senderid = "Good"
},
new
{
number = 256788200915,
message = "marvin",
senderid = "Bad"
}
}
};
// Encode the data into JSON
string json = JsonConvert.SerializeObject(data);
using (HttpClient httpClient = new HttpClient())
{
// Set the request headers
httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
// Send the POST request
HttpResponseMessage response = await httpClient.PostAsync("https://www.egosms.co/api/v1/json/", new StringContent(json, Encoding.UTF8, "application/json"));
// Read the response
string responseContent = await response.Content.ReadAsStringAsync();
// Decode the JSON response
dynamic result = JsonConvert.DeserializeObject(responseContent);
// Print the decoded response
Console.WriteLine(result);
}
}
}