Click or drag to resize
Non-Personalised Messaging

Non-personalised message is a single message that is sent to a list of recipients. Each recipient receives the same message as received by other recipients. Thus, the message is not crafted to be different for any destination.

As an example, consider that we need to deliver a message to customers on suspension of service within some given hours. We could compose a message as follows:

Dear valued customer, you are being informed that our services will be temporarily suspended from 8:00PM to 10:00PM for a short maintenance. We are sorry for any inconveniences caused.

When the message is submitted, each mobile number added to the destinations list will receive the same message as composed. Thus the message is not personalised for any particular destination.

To send non-personalised messages, an object of type ZenophSMS need to be created and authentication performed:

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

// authentication must be performed for settings to be loaded.
sms.authenticate();

Authentication is required for personal and server settings to be loaded. When authentication fails SMSException will be thrown. If authentication is successful, message parameters can be set for submission.

// the message to be sent.
string msg = "Dear valued customer, you are being informed that our services will be " +
             "temporarily suspended from 8:00PM to 10:00PM for a short maintenance. " +
             "We are sorry for any inconveniences caused.";

sms.setMessage(msg);
sms.setSenderId("SMSTEST");
sms.setMessageType(MSGTYPE.TEXT);

The phone numbers that the message will be submitted to can now be added to the destinations list by calling addRecipient(String) or addRecipient(String, Boolean) methods. The phone numbers can be specified in either international or local format.

// add phone numbers
sms.addRecipient("0202541445");              // if invalid, exception will be thrown.
sms.addRecipient("2335812752375", false);    // if invalid, exception will be thrown.
sms.addRecipient("0538873421", true);        // if invalid, exception will not be thrown (number will be ignored.)

Sometimes, phone numbers may exist with other non-numeric contents or data that are not phone numbers. In such cases, the phone numbers can easily be extracted to be added to the destinations list by calling extractPhoneNumbers(String) or extractPhoneNumbers(String, ListString). The phone numbers that are returned by the methods are those that are valid and allowed on user routes. Thus, a value may be a valid phone number but if it is not enabled on user routes, it will be rejected. The following code demonstrates the extraction of phone numbers from a String object.

// example source containing phone numbers
string str = "Mr. ABC, XYZ Street, Kumasi, Tel: 233280111111;  Mr. EFG, AY Avenue, Kumasi, Tel: 0208999999;";

// extract only the phone numbers.
List<string> nums = sms.extractPhoneNumbers(str);

// add the phone numbers.
foreach (string phonenum in nums)
    sms.addRecipient(phonenum, true);

When interested in knowing phone numbers that were rejected during extraction, the overloaded method extractPhoneNumbers(String, ListString) must be called while passing ListT of type String as the second argument. All rejected destinations will be saved in the object after the method call.

// example source containing phone numbers
string str = "Mr. ABC, XYZ Street, Kumasi, Tel: 233280111111;  Mr. EFG, AY Avenue, Kumasi, Tel: 0208999999;";

// extract and return the phone numbers as well as the rejected ones
List<string> rej;
List<string> nums = sms.extractPhoneNumbers(str, out rej);

// add the phone numbers.
foreach (string phonenum in nums)
    sms.addRecipient(phonenum, true);

// show the rejected values (numbers)
if (rej != null && rej.Count > 0)
{
    Console.WriteLine("Rejected destinations:");

    foreach (string s in rej)
        Console.WriteLine("destination: {0}", s);
}

When all phone numbers have been added to the destinations list, the message can be submitted by calling the submit method.

// submit the message.
sms.submit();

The submit actually returns a reference which is ListT of String[]. The data that is referenced by the object is variant. This depends on some conditions and will be discussed later. It is therefore necessary to know the kind of data that will be returned when submit is called. For instance, the submit status of the destinations may be immediately returned by the method. In some cases too, the submit status of the destinations will not be returned but rather a token that can be used to query the submit status of the destinations. A look at this is deferred until the discussion on Processing Submit Responses. If you need to have a look at this now, click on the link to view the page on how to process submit responses.