Click or drag to resize
Message Scheduling

In most cases, messages may be composed for submission to be immediately delivered to added destinations. But it is also possible to compose a message and define the date and time at which the message should be delivered to the destinations. This can be easily done using the SMS API. Both personalised and non-personalised messages can be scheduled.

Message scheduling is done by calling schedule(NullableDateTime) which sets the date and time at which the message should be delivered to the destinations. The method is overloaded but each overloaded method takes DateTime as the first argument. When the method is called, it only sets the date and time as well as the time zone offset from GMT but does not submit the message. Thus, submit must still be called when scheduling messages. The date and time must be in 24 hour format.

To demonstrate SMS scheduling, we can first initialise SMS object and set message parameters.

// Initialise SMS object and perform authentication.
ZenophSMS sms = new ZenophSMS();
sms.setUser("account_login");
sms.setPassword("account_password");
sms.authenticate();

// set message parameters.
sms.setSenderId("SMSTEST");
sms.setMessageType(MSGTYPE.UNICODE);
sms.setMessage("Hi there!");

// add destinations.
sms.addRecipient("233203881189");
sms.addRecipient("233506813454");

// The date and time to schedule the message. It must be in 24 hour format.
DateTime dt = new DateTime(2015, 07, 12, 15, 45, 0);

Firstly, a message can be scheduled by calling schedule(NullableDateTime) method. This method takes the date and time as the only argument. In this case, the time zone offset from GMT that is used is the default GMT offset that has been set for user account.

// Set the schedule date and time. 
// The default GMT offset for user account will be used in this case.
sms.schedule(dt);

// the message must be submitted. This does not deliver to destinations.
// The message will be sent to the destinations when the time is due.
List<string[]> resp = sms.submit();

// For scheduled messages, a token is always returned.
string token = resp[0][0];

Secondly, a message can be scheduled by calling the schedule(NullableDateTime, String) method. The method takes a String as the second argument which is the time zone offset from GMT that should be used. The default GMT offset set for user account will be ignored in this case.

// Set the schedule date and time as well as the GMT offset to be used.
sms.schedule(dt, "+02:30");

// the message must be submitted. This does not deliver to destinations.
// The message will be sent to the destinations when the time is due.
List<string[]> resp = sms.submit();

// For scheduled messages, a token is always returned.
string token = resp[0][0];

Lastly, a message can be scheduled by calling schedule(NullableDateTime, String, String) method. Like the other overloaded methods, this method takes the date and time as the first argument. But to determine the GMT offset to be used, a time zone region and city must be passed to the method. The time zone region and city that can be passed to the method are those that are provided by PHP. The method uses the specified time zone region and city to determine the GMT offset that should be used for the specified date and time. The advantage of this method call over the others is that you do not need to worry about daylight saving time changes. They are automatically determined once the time zone region and city are valid.

// Set the schedule date and time, time zone region and city.
sms.schedule(dt, "America/Indiana", "Petersburg");

// another example
sms.schedule(dt, "Africa", "Accra");

// the message must be submitted. This does not deliver to destinations.
// The message will be sent to the destinations when the time is due.
List<string[]> resp = sms.submit();

// For scheduled messages, a token is always returned.
string token = resp[0][0];

It is possible to cancel message scheduling by passing System.Null to schedule(NullableDateTime). When this is done, the message will be immediately sent to the destinations when submit is called.

// Set the schedule date and time as well as the GMT offset to be used.
sms.schedule(dt, "+02:30");

// set date and time to null to cancel scheduling.
sms.schedule(null);

// the message must be submitted. Since the scheduling was cancelled
// above, the message will be immediately sent to the added destinations.
List<string[]> resp = sms.submit();