Delivery Push Notifications

When a message is intially submitted, the messaging server immediately returns a response data which we have covered so far. This response data includes the identifier assigned to the submitted batch as well as identifiers for each added destination and their status. However, this information does not indicate that the message has been delivered to added destinations. The mobile operator returns the delivery status of each added destination as and when they are delivered to the mobile phones.

Applications can request that when mobile operators return the delivery status of each destination, the messaging server also pushes the delivery status to applications's callback URL so that the client application processes the response.

In this section, we will look at how applications can set a delivery callback URL in the message data on which delivery status received from the mobile operators will be pushed to.

Setting Delivery Callback

To be notified of message delivery status received from mobile operators, applications will need to set a callback URL and the content type to be received in the message data before sending the request:

The following is an example SMS data with delivery callback information set:

JSON
XML

{
    "text": "Hello World!",
    "type": 0,
    "sender": "TEST",
    "destinations": ["233242053072", "0246314915"],
    "callback": {
        "url": "https://message_callback_url/handler",
        "accept": "application/json"
    }
}

<request>
    <text>Hello world!</text>
    <type>0</type>
    <sender>TEST</sender>
    <destinations>
        <to>233242053072</to>
        <to>0246314915</to>
    </destinations>
    <callback>
        <url>https://message_callback_url/handler</url>
        <accept>application/json</accept>
    </callback>
</request>

Notice the inclusion of the callback property in the message data. The callback property contains an object consisting of url and accept properties. When delivery status is received from mobile operator, the status will be pushed to the specified URL in the content type format set to the accept property. The value for the accept property must either be application/json or application/xml.

The following is a sample application code that sets the delivery callback information in SMS message data:

<?php 
    // set up the request headers
    $headers = [
        'Host: api.smsonlinegh.com',
        'Content-Type: application/json',
        'Accept: application/json',
        'Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
    ];
	
    // set up the message data
    $messageData = [
        'text'=>'This is a test message',
        'type'=> 0,	// GSM default
        'sender'=> 'TEST',
        'destinations'=> ['0246314915', '0242053072']
    ];
	
    // set delivery callback information
    $messageData['callback']['url'] = 'https://delivery_callback_domain/handler';
    $messageData['callback']['accept'] = 'application/json';
	
    // initialise cURL
    $ch = curl_init('https://api.smsonlinegh.com/v5/sms/send');
    
    // set cURL optionS
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($messageData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Execute for response
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // close curl
    curl_close($ch);

if ($httpCode == 200){
    var_dump($response);
}

import json
import http.client as httpClient

try: 
    host = 'api.smsonlinegh.com'
    requestURI = 'http://api.smsonlinegh.com/v5/message/sms/send'
    apiKey = 'd5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'

    headers = dict()
    headers['Host'] = host
    headers['Content-Type'] = 'application/json'
    headers['Accept'] = 'application/json'
    headers['Authorization'] = f'key {apiKey}'

    # message data
    msgData = dict()
    msgData['text'] = 'This is a test message'
    msgData['type'] = 0
    msgData['sender'] = 'TEST'
    msgData['destinations'] = ['0246314915', '0242053072']
	
    # set delivery callback information
    msgData = dict()
    msgData['callback'] = {'url': 'https://delivery_callback_domain/handler', 'accept': 'application/json'}

    httpConn = httpClient.HTTPConnection(host)
    httpConn.request('POST', requestURI, json.dumps(msgData), headers)

    # get the reponse
    response = httpConn.getresponse()

    # check the status
    status = response.status

    if status == 200:
        responseData = response.read()
        print(responseData)
    else:
        print('Request was unsuccessful')

except Exception as e:
    print(str(e))

const axios = require('axios');

try {
    let host = 'api.smsonlinegh.com';
    let endPoint = `http://${host}/v5/message/sms/send`;

    // the message data
    let msgData = {
        text: 'This is a test message',
        type: 0,    // GSM default
        sender: 'TEST',
        destinations: ['0246314915', '0242053072']
    };
	
    // set delivery callback information
    msgData.callback = {
        url: 'https://delivery_callback_domain/handler',
        accept: 'application/json'
    };

    axios.request({
        method: 'POST',
        url: endPoint,
        data: msgData,
        headers: {
            'Host': `${host}`,
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
        }
    })
    .then(function (response) {
        console.log(response);

        let httpStatus = response.status;

        if (response.status == 200) {
            let handshake = response.data.handshake;
            let respData  = response.data.data;
			
            console.log(respData);
        }
    })
    .catch(function (error) {
        console.log(error.stack);
    });
}

Note

The value set as sender must exist in the list of user message sender names. If the name has not been added in user message sender names, then the message will not be submitted. The sender name must be requested from the user account under SMS Messaging menu option.

Delivery Callback Response

A delivery callback response is similar to the response data in a Message Delivery Report. The only difference is that the response data for a delivery push notification applies to a single message destination. As a result, a delivery push response data will have a single phone number information in the destinations section.

The following data shows an example of a response data for a delivery push notification for SMS submitted:

JSON
XML

{
    "handshake" : {
        "id" : 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
        "delivery": true,
        "category": "sms",
        "text": "Hello world!",
        "type": 0,
        "sender": "Hello",
        "personalised": false,
        "destinationsCount": 2,
        "destinations: [
            {
                "to" : "233246314915",
                "id" : "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"
                }
            }
        ]
    }
}

<response>
    <handshake>
        <id>key</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
        <category>sms</category>
        <delivery>true</delivery>
        <text>Hello world!</text>
        <type>0</type>
        <sender>Hello</sender>
        <personalised>false</personalised>,
        <destinationsCount>2</destinationsCount>
        <destinations>
            <item>
                <to>233246314915</to>
                <id>093841e5-578a-41f4-5f5f-2f3910886c12</id>
                <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>
        </destinations>
    </data>
</response>