REST API

Overview

The REST API enables developers to interface with our SMS platform, making it easy to send messages to one or many destinations.

• 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 SMS account Username and Password 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

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/v2/messages HTTP/1.1
Host: sms.dtechghana.com
Accept: application/json
Authorization: Basic cm9sbGluczpmOTgwYxYzYyODg4NWFlNDQ1Y2Y5MA==

{
    "from": "DT SMS",
    "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"
}                    

Check Balance

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

POST /api/v2/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": "150.45"
}

 

Receiving Delivery Reports (DLR)

When requested through dlr-* fields when Sending messages, a delivery receipt (DLR) will be sent back to the application url (set in dlr-url) through HTTP POST method

The following parameters will be included in the request returned to the specified DLR URL:

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}";
$password = "{Password}";

$from = "John Doe";
$to = "233241234567";
$content = "Hello Jane! how are you?";

$url = "https://sms.dtechghana.com/api/v2/messages";
$headers = array("Content-Type" => "application/x-www-form-urlencoded");
$data = array("to" => $to, "from" => $from, "content" =>$content);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);
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}"
password = "{Password}"

from = "John Doe"
to = "233241234567"
content = "Hello Jane! how are you?"

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

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

# Sending a message using REST API in Ruby

require 'net/http'
require 'uri'

username = "{username}"
password = "{Password}"

from = "John Doe"
to = "233241234567"
content = "Hello Jane! how are you?"

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

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

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/v2/messages";
			URL obj = new URL(url);
			HttpsURLConnection connection = (HttpsURLConnection) obj.openConnection();
			connection.setRequestMethod("POST");

			String username = "{username}";
			String password = "{Password}";
			String userCredentials = username + " : " + password;
			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();
		}
	}
}