REST API

Overview

The REST API offers a number of useful methods that provide for a more extensive interaction with our SMS gateway.

Few notes regarding the REST API:
  • Each API request has to be authenticated (See below)
  • API requests are time bound -- every request to the API has a timeout of 10 seconds bound to it.
  • All requests are made via HTTPS protocol. Requests made via unsecure connections will be forced to HTTPS.

 

Authentication

Requests to the API require authentication using Basic Access Authentication. Before you can access an API Resource, you'd be required to authenticate using your Username and API Key combination. We've provided a few examples below that show how this can be done programatically. However, most HTTP clients, including the cURL library typically offer ways to do this internally.

 

Request Response

Each time you send a request to the REST API, the API issues a response containing information related to your request. The API response generally includes the following:

Response Header:

Standard HTTP code indicating the success or otherwise of the request. A 200 status code indicates a successful request, whereas 4xx or 5xx indicate a failed request.

Response Body

A JSON formatted object containing the following:

  • "Status" - indicates the status of the API request. "00" indicates a successful request, while "01" indicates an unsuccessful request.
  • "Id" - internal (Gateway) message ID for the sent message
  • "Rate" - the SMS rate for the sent message.
  • "Reference" - the unique reference provided during the API call. Defaults to NULL if no reference was provided.
  • "MessageStatus" - indicates the current status of the message i.e. "Sent" or "Scheduled"
  • "Message" - error message associated with a failed request. This will only be provided if the request wasn't successful.

 

 

Send Message

This is the defacto method for sending SMS using the API, and is recommended when sending large volumes. To send SMS, simply send a POST request to the API resource below, including the relevant parameters.

Resource Path:
https://sms.dtechghana.com/api/v1/messages
HTTP Verb: POST
Request Data Formats:

  • Form URL Encoded (application/x-www-form-urlencoded)
  • Json (application/json)
  • Multipart Form (multipart/form-data)

Response Data Format:

  • Json (application/json)

 

Request Parameters:

Below are the relevant parameters associated with this API call:

Parameter Description Presence
to
Recipient phone number
  • Must be a valid MSIDSN
  • Must be in the international telephone number format without the '+' symbol. e.g. 233241234567
Required
from
Sender ID (3-11 characters, alphanumeric)
Required
content The message to be sent. Must be URL encoded. Required
time
To schedule the message to be sent sometime or date in the future
  • Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP
  • Scheduled time must be at least 10 minutes ahead of current time in UTC
Optional
type
Type of message to be sent
  • 0 - Regular Text Message
  • 1 - Binary Message
  • 2 - Unicode Message
Optional
reference A unique reference number to identify your transaction for your records Optional
dlr
To request a delivery report
  • Type: Boolean
  • Possible values: yes or no
Optional
Example request:
POST /api/v1/messages HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

{
    "from": "D-Tech", 
    "to": "233236517727", 
    "content": "hello, world!",
    "reference": "890768"
}
                    

 

Example response:
HTTP/1.1 200 OK
Date: Thu, 10 Mar 2016 02:48:46 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "Status":"00",
   "Id":"1b28b4cd6fd30b0de8d7fa771a45f6eb",
   "Rate":1,
   "Reference":null,
   "MessageStatus":"Sent"
}                    

 

 

Schedule Message

To schedule the message to be sent sometime or date in the future, you only need to pass the "time" parameter in your send message API request. Scheduled messages are handled like sent messages and are billed immediately. Credit billed for the message will be reversed if the message is cancelled before the specified time.

Resource Path:
https://sms.dtechghana.com/api/v1/messages
HTTP Verb: POST
Request Data Formats:

  • Form URL Encoded (application/x-www-form-urlencoded)
  • Json (application/json)

Response Data Format:

  • Json (application/json)

 

Request Parameters:

Below are the relevant parameters associated with this API call:

Parameter Description Presence
to
Recipient phone number
  • Must be a valid MSIDSN
  • Must be in the international telephone number format without the '+' symbol. e.g. 233241234567
Required
from
Sender ID or MSIDSN (Do not use +before the country code)
Required
content The message to be sent. Must be URL encoded. Required
time
To schedule the message to be sent sometime or date in the future
  • Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP
  • Scheduled time must be at least 10 minutes ahead of current time in UTC
Required
type
Type of message to be sent
  • 0 - Regular Text Message
  • 1 - Binary Message
  • 2 - Unicode Message
Optional
reference A unique reference number to identify your transaction for your records Optional
dlr
To request a delivery report
  • Type: Boolean
  • Possible values: yes or no
Optional

 

Example request:
POST /api/v1/messages HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

{
    "from": "D-Tech", 
    "to": "233236517727", 
    "content": "hello, world!",
    "reference": "890768",
    "time": "2016-03-25 10:15:00"
}
                    

 

Example response:
HTTP/1.1 200 OK
Date: Thu, 10 Mar 2016 02:48:46 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "Status":"00",
   "Id":"1b28b4cd6fd30b0de8d7fa771a45f6eb",
   "Rate":1,
   "Reference":null,
   "MessageStatus":"Scheduled"
}                    

 

 

Get Message Details

This method enables you retreive the details of a sent or scheduled message by simply sending a GET request to the API message resource with the message id appended to the URL as shown in the resource path below:

Resource Path:
https://sms.dtechghana.com/api/v1/messages/{MessageID}
HTTP Verb: GET

Response Data Format:

  • Json (application/json)

 

Example request:
GET /api/v1/messages/1b28b4cd6fd30b0de8d7fa771a45f6eb HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

 

Example response:
HTTP/1.1 200 OK
Date: Thu, 10 Mar 2016 02:48:46 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "MessageId":"1b28b4cd6fd30b0de8d7fa771a45f6eb",
   "From":"ROLLO",
   "To":"233244528251",
   "Time":"2016-03-06 02:48:46",
   "Rate":"1",
   "Status":"Sent",
   "Content":"Whats up doc"
}                    

 

 

Query Messages

This method enables you query messages that have been sent through your SMS Messaging account. You can query messages by sending a GET request to the resource path given below. You may query messages within 10 second intervals.

Resource Path:
https://sms.dtechghana.com/api/v1/messages
HTTP Verb: GET

Response Data Format:

  • Json (application/json)

 

Query Parameters

You can filter the query result by passing the following query string parameters with your request. All query string parameters are optional.

Parameter Type Description
start
DateTime (YYYY-MM-DD HH:MM:SS)
The date to start querying from.
end
DateTime (YYYY-MM-DD HH:MM:SS)
Last possible date to include in query
index Integer The number of messages to skip from the beginning of the query results. Defaults to 0
limit Integer The maximum number of messages to include in the query results. Cannot exceed 100
pending Boolean Indicates whether scheduled messages should be included in the query results. This is set to false by default, and only sent messages included.
Example request:
GET /api/v1/messages?index=1&limit=3 HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

 

Example response:
HTTP/1.1 200 OK
Date: Tue, 19 Jan 2016 21:24:16 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "count":3,
   "messages":[  
      {  
         "MessageId":"40f85449248649f53737a4c588368eac",
         "From":"John",
         "To":"233236517727",
         "Time":"2016-01-13 00:06:23",
         "Rate":"1",
         "Status":"Sent",
         "Content":"Hungry rabbit jumps"
      },
      {  
         "MessageId":"901e2c28d9237308377759d8a14c954c",
         "From":"John",
         "To":"233236517727",
         "Time":"2016-01-13 00:04:52",
         "Rate":"1",
         "Status":"Sent",
         "Content":"Much ado about nothing"
      },
      {  
         "MessageId":"7d810f2b8c6e142e07ad71253efaa0dc",
         "From":"John",
         "To":"233236517727",
         "Time":"2016-01-12 23:14:37",
         "Rate":"1",
         "Status":"Sent",
         "Content":"Hello,World"
      }
   ]
}

 

 

Reschedule Message

This API method enables you reschedule a message that was previously scheduled, provided the message hasn't been sent. To reschedule a message, simply send a PUT request to the messages API resource with the message id appended to the URL as shown in the resource path below:

Resource Path:
https://sms.dtechghana.com/api/v1/messages/{MessageID}
HTTP Verb: PUT
Request Data Formats:

  • Form URL Encoded (application/x-www-form-urlencoded)
  • Json (application/json)

Response Data Format:

  • Json (application/json)

 

Request Parameters:

Below are the relevant parameters associated with this API call:

Parameter Description Presence
time
Date/time to schedule the message to be sent ahead of the currently scheduled date/time
  • Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP
  • Scheduled time must be at least 10 minutes ahead of current time in UTC
Required

 

Example request:
PUT /api/v1/messages/1b28b4cd6fd30b0de8d7fa771a45f6eb HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==
Content-Type: application/json

{
    "time": "2016-02-14 03:00:00", 
}

 

Example response:
HTTP/1.1 200 OK
Date: Sat, 13 Feb 2016 03:48:46 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "Status":"00",
   "Id":"1b28b4cd6fd30b0de8d7fa771a45f6eb",
   "Rate":1,
   "Reference":null,
   "MessageStatus":"Scheduled"
}                    

 

 

Cancel Scheduled Message

This API method enables you cancel a scheduled message provided the message hasn't been sent. This is accomplished by sending a DELETE request to the messages resource with the message id of the message you want to cancel appended to the URL as shown in the resource path below:

Resource Path:
https://sms.dtechghana.com/api/v1/messages/{MessageID}
HTTP Verb: DELETE
Response Data Format:

  • Json (application/json)

 

Example request:
DELETE /api/v1/messages/1b28b4cd6fd30b0de8d7fa771a45f6eb HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==
Content-Type: application/json

 

Example response:
HTTP/1.1 200 OK
Date: Sat, 13 Feb 2016 03:48:46 GMT
Server: HTTP API Server
Content-Length: 102
Content-Type: application/json; charset=utf-8

{  
   "Status":"00"
}                    

 

 

Programming Examples Using The REST API

The following code snippets demonstrate how to call the various REST API methods in a number of different programming languages.

 


<?php

// The following examples make use the excellent Requests class by Ryan McCue for making HTTP requests to the API resource path
// Github repository: https://github.com/rmccue/Requests

require_once "/path/to/Requests/library/Requests.php";

Requests::register_autoloader();
	
/*
EXAMPLE SEND MESSAGE API REQUEST

*/
$username = "{username}";
$apiKey = "{API Key}";

$from = "John Doe";
$to = "233241234567";
$content = "Hello Jane! how are you?";
	
// Optionally provided if we need to schedule the SMS instead
$time = strtotime("+ 1 day");


$url = "https://sms.dtechghana.com/api/v1/messages";
$headers = array("Content-Type" => "application/x-www-form-urlencoded");	
$options = array(
			"auth" => new Requests_Auth_Basic(array($username, $apiKey))
		);

$data = http_build_query(array("to" => $to, "from" => $from, "content" =>$content, "time" => $time));

$response = Requests::post($url, $headers, $data, $options);

# Sending a message using REST API in Python

import requests, time, datetime, json 

username = "{username}"
apiKey = "{API Key}"

from = "John Doe"
to = "233241234567"
content = "Hello Jane! how are you?"
	
# Optionally provided if we need to schedule the SMS instead
dateTime = datetime.date(2015,1,5)
unixtime = time.mktime(dateTime.timetuple())

url = "https://sms.dtechghana.com/api/v1/messages";
headers = {'Content-Type' : 'application/json)'}
data = json.dumps({'to' : to , 'from' : from , 'content' : content , 'time' : unixtime })

response = requests.post(url, data, headers=headers, auth=(username, apiKey))

# Sending a message using REST API in Ruby

require 'net/http'
require 'uri'

username = "{username}"
apiKey = "{API Key}"

from = "John Doe"
to = "233241234567"
content = "Hello Jane! how are you?"
	
# Optionally provided if we need to schedule the SMS instead
unixtime = Date.new(2015,1,5).to_time.to_i

url = "https://sms.dtechghana.com/api/v1/messages";
uri = URI.parse(@url)
http = Net::HTTP.new(uri.host, uri.port)
data = {'to' : to , 'from' : from , 'content' : content , 'time' : unixtime }

request = Net::HTTP::Post.new(uri.request_uri,initheader = {'Content-Type' =>'application/json'})
request.body = data.to_json
request.basic_auth @username, @apiKey

response = http.request(request)


// Sending a message using REST API in Java
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.apache.commons.codec.binary.Base64;
import org.json.JSONObject;

public class CallApi {
	public static void main(String[] args) {
		try{
			String url = "https://sms.dtechghana.com/api/v1/messages";
			URL obj = new URL(url);
			HttpsURLConnection connection = (HttpsURLConnection) obj.openConnection();
			connection.setRequestMethod("POST");
   
			String username = "{username}";
			String apiKey = "{API Key}";
			String userCredentials = username + " : " + apiKey;
			String basicAuth = "Basic " + new String(new Base64().encode(userCredentials.getBytes()));
			
			String from = "John Doe";
			String to = "233241234567";
			String content = "Hello Jane! how are you?";
			
			connection.setRequestProperty ("Authorization", basicAuth);
			connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
			String data = "to="+to+"&from="+from+"&content="+content;
			
			connection.setDoOutput(true);
			DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
			wr.writeBytes(data);
			wr.flush();
			wr.close();
			int responseCode = connection.getResponseCode();
			BufferedReader in = new BufferedReader(
				new InputStreamReader(connection.getInputStream())
			);
			String inputLine;
			StringBuffer response = new StringBuffer();
			while ((inputLine = in.readLine()) != null) {
				response.append(inputLine);
			}
			in.close();			
		}
		catch(Exception e){
			e.printStackTrace();
		}
	}
}