Requesting Delivery Report

When an application submits a message, the messaging server replies with submit status of the destinations in a Message Response. The Message Response data includes information such as an reference that can be used to request for the delivery status of the message destinations.

Applications can request for the delivery status of the messages by submitting a delivery request using the reference that was assigned the message batch in returned in the Message Response.

Submitting Request

A message delivery status can be obtained by submitting a request to the following URL:

https://api.smsonlinegh.com/v5/report/message/delivery

When submitting the request, the account API Key and message reference must be provided. The API Key must be set the the parameter key whiles setting the message reference to the parameter name reference.

For requests using the HTTP GET, the parameters must be appended to the request URI separated by the character ?. That is,

https://api.smsonlinegh.com/v5/report/message/delivery?key=API_KEY&reference=MESSAGE_REFERENCE

Recall that when submitting requests, the Content-Type header must be set to application/x-www-form-urlencoded whiles the Accept header must be set to either application/json or application/xml depending on how the response data should be returned. For example,

GET https://api.smsonlinegh.com/v5/report/message/delivery?key=API_KEY&reference=MESSAGE_REFERENCE
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: api.smsonlinegh.com

For HTTP POST method, the API Key and message reference do not need to be appended to the request URI.

POST https://api.smsonlinegh.com/v5/report/message/delivery
Host: api.smsonlinegh.com 
Content-Type: application/x-www-form-urlencoded
Accept: application/json

key=API_KEY&reference=MESSAGE_REFERENCE

Delivery Response

After submitting a request message delivery status, a response will be returned like the following

JSON
XML

{
	"handshake" : {
		"id" : 0,
		"label" : "HSHK_OK"
	},
	"data": {
		"messages" : [
			{
				"batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
				"delivery": true,
				"category": 1,
				"text": "Hello world!",
				"type": 0,
				"sender": "Hello",
				"personalised": false,
				"destinationsCount": 2,
				"destinations: [
					{
						"to" : "233246314915",
						"messageId" : "093841e5-578a-41f4-5f5f-2f3910886c12",
						"country": "Ghana",
						"messageCount": 1,
						"submitDateTime":"2021-09-29 21:57:44",
						"reportDateTime":"2021-09-29 21:57:48",
						"status" : {
							"id" : 2110,
							"label" : "DS_DELIVERED"
						}
					},
					{
						"to" : "233242053072",
						"messageId" : "4abfa3bd-93f9-b8a1-4bbd-78725ca3e488",
						"country": "Ghana",
						"messageCount": 1,
						"submitDateTime":"2021-09-29 21:57:44",
						"reportDateTime":"2021-09-29 21:57:50",
						"status" : {
							"id" : 2110,
							"label" : "DS_DELIVERED"
						}
					}
				]
			}
		]
	}
}

<response>
    <handshake>
	    <id>key</id>
	    <label>HSHK_OK</label>
	</handshake>
	<data>
	    <messages>
		    <message>
			    <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
				<delivery>true</delivery>
				<category>1</category>
				<text>Hello world!</text>
				<type>0</type>
				<sender>Hello</sender>
				<personalised>false</personalised>,
				<destinationsCount>2</destinationsCount>
				<destinations>
				    <item>
					    <to>233241234567</to>
						<messageId>093841e5-578a-41f4-5f5f-2f3910886c12</messageId>
						<country>Ghana</country>
						<messageCount>1</messageCount>
						<submitDateTime>2021-09-29 21:57:44</submitDateTime>
						<reportDateTime>2021-09-29 21:57:48</reportDateTime>
						<status>
						    <id>2110</status>
							<label>DS_DELIVERED</label>
						</status>
					</item>
					<item>
					    <to>233501234567</to>
						<messageId>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</messageId>
						<country>Ghana</country>
						<messageCount>1</messageCount>
						<submitDateTime>2021-09-29 21:57:44</submitDateTime>
						<reportDateTime>2021-09-29 21:57:50</reportDateTime>
						<status>
						    <id>2110</status>
							<label>DS_DELIVERED</label>
						</status>
					</item>
				</destinations>
			</message>
		</messages>
	</data>
</response>

The structure of the response data to a message delivery request is similar to the response data that is returned after submitting a message as discussed under Message Response. A response to a message delivery request however excludes message validation information and includes new information such as message category, text, type, sender, personalised, etc. Additionally, each destination contains additional information such as country, messageCount, submitDateTime, reportDateTime.

For SMS messages that are personalised, each destination will have an additional property message in the delivery responses. In this case, message contains actual message text that was customised for each destination added to message.

JSON
XML

{
	"handshake" : {
		"id" : 0,
		"label" : "HSHK_OK"
	},
	"data: {
		"messages" : [
			{
				"reference" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
				"delivery": true,
				"category": 1,
				"text": "Hello {$name}. Your package is ready for collection.",
				"type": 0,
				"sender": "Hello",
				"personalised": true,
				"destinationsCount": 2,
				"destinations: [
					{
						"to" : "233246314915",
						"messageId" : "093841e5-578a-41f4-5f5f-2f3910886c12",
						"message": "Hello Daniel. Your package is ready for collection.",
						"country": "Ghana",
						"messageCount": 1,
						"submitDateTime":"2021-09-29 21:57:44",
						"reportDateTime":"2021-09-29 21:57:48",
						"status" : {
							"id" : 2110,
							"label" : "DS_DELIVERED"
						}
					},
					{
						"to" : "233242053072",
						"messageId" : "4abfa3bd-93f9-b8a1-4bbd-78725ca3e488",
						"message": "Hello Joseph. Your package is ready for collection.",
						"country": "Ghana",
						"messageCount": 1,
						"submitDateTime":"2021-09-29 21:57:44",
						"reportDateTime":"2021-09-29 21:57:50",
						"status" : {
							"id" : 2110,
							"label" : "DS_DELIVERED"
						}
					}
				]
			}
		]
	}
}

<response>
    <handshake>
	    <id>key</id>
	    <label>HSHK_OK</label>
	</handshake>
	<data>
	    <messages>
		    <message>
			    <reference>cfa19ba67f94fbd6b19c067b0c87ed4f</reference>
				<delivery>true</delivery>
				<category>1</category>
				<text>Hello {$name}. Your package is ready for collection.</text>
				<type>0</type>
				<sender>Hello</sender>
				<personalised>true</personalised>,
				<destinationsCount>2</destinationsCount>
				<destinations>
				    <item>
					    <to>233241234567</to>
						<messageId>093841e5-578a-41f4-5f5f-2f3910886c12</messageId>
						<message>Hello Daniel. Your package is ready for collection.</message>
						<country>Ghana</country>
						<messageCount>1</messageCount>
						<submitDateTime>2021-09-29 21:57:44</submitDateTime>
						<reportDateTime>2021-09-29 21:57:48</reportDateTime>
						<status>
						    <id>2110</status>
							<label>DS_DELIVERED</label>
						</status>
					</item>
					<item>
					    <to>233501234567</to>
						<messageId>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</messageId>
						<message>Hello Joseph. Your package is ready for collection.</message>
						<country>Ghana</country>
						<messageCount>1</messageCount>
						<submitDateTime>2021-09-29 21:57:44</submitDateTime>
						<reportDateTime>2021-09-29 21:57:50</reportDateTime>
						<status>
						    <id>2110</status>
							<label>DS_DELIVERED</label>
						</status>
					</item>
				</destinations>
			</message>
		</messages>
	</data>
</response>

Notice that the message property exists in a destination object only when the message was personalised. Applications can know this by checking the value set to personalised property in the delivery response.