Using the SMS Gateway API, Automating Delivery Report Collection

Introduction

If you are using the API / Gateway to send bulk SMS you can collect your delivery reports from the server, which is a good way of removing bad numbers from your data.

Delivery Reports and the API

It is important to understand the difference between getting a “failure”  (or success) message at the API/Gateway and a delivery report. The HTTP GET response from the gateway only confirms that the number and message appear to be in the correct format this does not mean that the number exists.  Delivery reports confirm to you what has actually happened to the message, the following outcomes are possible: “DELIVERED”,”REJECTED”,”FAILED” and no report at all.

• “REJECTED” means that the message was rejected by the relevant operator and did not attempt to deliver it.
• “FAILED” probably means that the number does exist (or at least not anymore).
• “DELIVERED” message received on the handset.

Occasionally we don’t received a delivery report at all, this can be down to a failure at the operator end due to high load or other problems.

Delivery Reporting

It most cases we receive a delivery report from the operator, this gets appended to a file in your delivery report directory using a standardised filename for each day of the week. The naming format is as follows:

“GatewayAPI_DD-MM-YY.csv” where DD is the day in the month in 2 digit format, MM is the month and YY is the year, so for example:

GatewayAPI_04-01-09.csv     is correct

GatewapAPI_12-12-09.csv     is correct

GatewayAPI_1-1-9.csv        is incorrect

The contents of a typical file

20-05-09 10:50,447777777777,DELIVERED
20-05-09 15:15,447777777776,DELIVERED

The url for collecting the delivery report

http://www.textmarketer.biz/DeliveryReports/[dir]/[filename]

To find your  delivery report directory, log into your system click the menu heading “Reports” then select “Delivery Reporting”, you will see a green icon (see below), roll over this and you can find the directory name at the bottom. So an example url would like like:

http://www.textmarketer.biz/DeliveryReports/jdjd8447fj9fj94kv4/GatewayAPI_05-05-09.csv

Example PHP5 Code for handling delivery reporting

<?php

class ProcessDeliveryReport {
	private $dir;
	private static $REPORT_URL = "http://www.textmarketer.biz/DeliveryReports/";
	private $data;
	private $lines;

	function __construct($dir) {
		// Your delivery report url such as "jfjfij596tghg85" include no / slashes
		// You can find the directory in your system under delivery reports and the green ?

		$this->dir = self::$REPORT_URL . $dir;
	}

	public function setReportDate($the_date) {
		// Use this function first to set the reporting date you wish to examine
		// $the_Date in DD-MM-YY format "07-09-09" or "today"

		if ($the_date == "today")
			$filename = $this->dir . "/GatewayAPI_" . date ( "d-m-y", time () ) . ".csv";
		else {

			if (count ( explode ( "-", $the_date ) ) < 3)
				return false; // probably wrong fromat
			list ( $day, $month, $year ) = explode ( "-", $the_date );
			$filename = $this->dir . "/GatewayAPI_$day-$month-$year.csv";
		}

		if ($this->data = file_get_contents ( $filename )) {
			$this->lines = explode ( "\r\n", $this->data );
			return true;
		} else
			return false;

	}

	public function getWholeReport() {
		// returns the whole file
		return $this->data;
	}

	public function findNumber($number, $status = false) {
		// $number is mobile number in international format for example 44777777777
		// $status (optional)  status can be "d","f","r" for delivered, failed or rejected 

		if ($status) {
			switch (strtoupper ( $status )) {
				case "D" :
					$status = "DELIVERED";
					break;
				case "F" :
					$status = "FAILED";
					break;
				case "R" :
					$status = "REJECTED";
					break;
				default :
					$status = false;
			}
		}
		$found = false;

		foreach ( $this->lines as $line ) {
			if (! $status) {
				if (strstr ( $line, $number ) !== false)
					$found [] = $this->lineFormat ( $line );
				// dont break as there could be more than one instance of the number during the day
			} else if (strstr ( $line, $number ) !== false and strstr ( $line, $status ) !== false)
				$found [] = $this->lineFormat ( $line );
		}
		return $found; // return an array of the number keyed array
	}

	public function getNextLineArray() // returns a keyed array of each line in the report
        {
		$current_arr = each ( $this->lines );
		return $this->lineFormat ( $current_arr ['value'] );
	}

	private function lineFormat($line) {
		list ( $d, $m, $s ) = explode ( ",", $line );
		return array ("delivered" => $d, "mobile number" => $m, "message status" => $s );
	}

}

/// example of use

$reports = new ProcessDeliveryReport ( "Kt65CZMtxlIiEU328ilCBgC38" );
if ($reports->setReportDate ( "20-05-09" ))
	print_r ( $reports->findNumber ( "44777777777", "r" ) );

?>

Popularity: 9%