Message Scheduling

Sometimes, it becomes necessary to compose your message and instruct the messaging server to not dispatch the messages immediately but rather at your own specified dates and time. When the specified date and time is due, the messages will automatically be dispatched to the added recipients.

We can easily achieve this by setting actual date and time at which the messages should be dispatched to the destinations in the message data.

Setting Schedule Date and Time

To schedule a message, we need to set the actual date and time that the messages will have to be dispatched to the destinations. This is done by specifying the date and time as dateTime property, with an optional offset property for UTC timezone offset, to the message data.

The following message data includes the schedule property which is the container property for dateTime and offset properties. Observe that the date and time have been set to the dateTime property as a single value.

JSON
XML

{
    "text": "Hello World!",
    "type": 0,
    "sender": "TEST",
    "destinations": ["233242053072", "0246314915"],
    "schedule": {
        "dateTime": "2023-10-24 15:45",
        "offset": "+00:00"
    }
}

<request>
    <text>Hello world!</text>
    <type>0</type>
    <sender>TEST</sender>
    <destinations>
        <to>233242053072</to>
        <to>0246314915</to>
    </destinations>
    <schedule>
        <dateTime>2023-10-24 15:45</dateTime>
        <offset>+00:00</offset>
    </schedule>
</request>

As indicated earlier, the timezone offset from UTC is optional and can be omitted. When not specified, a default timzone offset from UTC will be used from client account.

The following message data specifies the schedule dateTime without the timezone offset from UTC.

JSON
XML

{
    "text": "Hello World!",
    "type": 0,
    "sender": "TEST",
    "destinations": ["233242053072", "0246314915"],
    "schedule": {
        "dateTime": "2023-10-24 15:45"
    }
}

<request>
    <text>Hello world!</text>
    <type>0</type>
    <sender>TEST</sender>
    <destinations>
        <to>233242053072</to>
        <to>0246314915</to>
    </destinations>
    <schedule>
        <dateTime>2023-10-24 15:45</dateTime>
    </schedule>
</request>

Example Schedule Request

The following is an example code that sends SMS by defining a specific date and time at which the message should be dispatched to the destinations.

<?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 the schedule date and time, as well as the UTC offset
    $messageData['schedule']['dateTime'] = '2023-10-24 15:45';
    $messageData['schedule']['offset'] = '+00:00';
	
    // 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 the schedule date and time, as well as UTC offset
	msgData = dict()
    msgData['schedule'] = {'dateTime': '2023-10-24 15:45', 'offset': '+00:00'}

    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 the schedule date and time, as well as UTC offset
    msgData.schedule = {
        dateTime: '2023-10-24 15:45',
        offset: '+00:00'
    };

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

After the above sample message is submitted, a message response data similar to non-scheduled message response data will be received. The only difference between the message response data for scheduled and non-scheduled messages is the status of the destinations.

The following is a sample message response data for a scheduled message.

JSON
XML

{
    "handshake" : {
        "id" : 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
        "category": 1,
        "delivery": false,
        "destinations": [
            {
                "id" : "093841e5-578a-41f4-5f5f-2f3910886c12",
                "to" : "233246314915",
                "status" : {
                    "id" : 2104,
                    "label" : "DS_SUBMIT_SCHEDULED"
                }
            },
            {
                "id" : "4abfa3bd-93f9-b8a1-4bbd-78725ca3e488",
                "to" : "233242053072",
                "status" : {
                    "id" : 2104,
                    "label" : "DS_SUBMIT_SCHEDULED"
                }
            }
        ]
    }
}

<response>
    <handshake>
        <id>key</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
        <category>1</category>
        <delivery>false</delivery>
        <destinations>
            <item>
                <id>093841e5-578a-41f4-5f5f-2f3910886c12</id>
                <to>233241234567</to>
                <status>
                    <id>2104</status>
                    <label>DS_SUBMIT_SCHEDULED</label>
                </status>
            </item>
            <item>
                <id>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</id>
                <to>233501234567</to>
                <status>
                    <id>2104</status>
                    <label>DS_SUBMIT_SCHEDULED</label>
                </status>
            </item>
        </destinations>
    </data>
</response>

Cancelling Scheduled Message

If the need arises to cancel the dispatch of a message that has been scheduled, then a request has to be made.

For every message request, the response data contains a batch identifier in the data section. This batch identifier can be used to reference the submitted message later. To cancel a message that was scheduled, the batch identifier will be needed in making request to cancel scheduled message.

The API endpoing for cancelling a scheduled message is given as follows:

https://api.smsonlinegh.com/v5/message/scheduled/cancel/[BATCH_ID]

Notice [BATCH_ID] at the end. This must be replaced with the batch identifier that was returned in the message response data when the message was submitted for scheduling.

For example, if the batch identifier for the submitted message is cfa19ba67f94fbd6b19c067b0c87ed4f, then the request to cancel the scheduled message will use the following API call:

https://api.smsonlinegh.com/v5/message/scheduled/cancel/cfa19ba67f94fbd6b19c067b0c87ed4f

Remember that the server needs to know the content type of the response that should be returned. Hence, the Accept header must be set to either application/json or application/xml. The following shows the request header for cancelling a scheduled message.

POST https://api.smsonlinegh.com/v5/message/scheduled/cancel/cfa19ba67f94fbd6b19c067b0c87ed4f

Host: api.smsonlinegh.comAccept: application/json
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

If the specified scheduled message has not already been dispatched to the destinations, then the dispatch operation will immediately be cancelled.