REST API

Overview

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

• 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:

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.

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.

Below are the relevant parameters associated with this API call:

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"
}
                    

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.

Below are the relevant parameters associated with this API call:

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"
}
                    

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:

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

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.

Query Parameters

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

GET /api/v1/messages?index=1&limit=3 HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

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:

Below are the relevant parameters associated with this API call:

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",
}

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:

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

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"
}

Check Balance

To check SMS credit balance, simply send a "POST" request to the following API resource:

POST /api/v1/account/balance
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

Date:Wed, 03 Nov 2021 21:40:43 GMT
Server: HTTP API Server
Content-Length: 31
Content-Type: application/json
{

"Status": "00",
"Message": "147"
}

 

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
• Python
• Ruby
• Java

<?php

/*
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");
$data = array("to" => $to, "from" => $from, "content" =>$content, "time" => $time);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $apiKey);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);

# 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();
		}
	}
}