Click or drag to resize
Personalised Messaging

Personalised messages are those messages in which each destination receives a message that has been personalised for the recipient. Each destination therefore receives a message that is different from those received by other recipients. Using the .NET SMS API, the differences are defined by variables that are inserted in the locations where values will be different for each recipient of the message.

As an example, suppose we manage the monetary contributions of clients recorded in an Excel spreadsheet and we would want to send messages to them on the balance in their account. The following image shows a sample of records for demonstration.

Table Data

From the above records, there are features that are specific to a client such as name, account number, and balance. We can send messages to each client notifying them of their current account balance. We could draft a message as below noting carefully the parts of the message where values will be different for each recipient.

Hello <NAME_OF_CLIENT>, the balance in your account <ACCOUNT_NUMBER> is $<BALANCE> as at 14th June, 2015.

From the above draft message, the parts that will be different for each recipient are shown in curly brackets. The .NET SMS API makes it easy to send such messages to as many destinations by composing a single message and defining variables in parts of the message where values will be different for each recipient.

Defining Variables

For personalised messages, a variable is defined by a name prepended by the dollar sign ($) and enclosing it in opening and closing braces. That is

{$VARIABLE_NAME}

The name of the variable must begin with a letter and can be followed by additional alphanumeric characters. The variable name must not contain any white spaces. The draft message above can therefore be set in code as follows:

Hello {$name}, the balance in your account {$acctnum} is ${$balance} as at 14th June, 2015.

A variable name must be unique in a message. If a variable name is defined more than once, Exception will be thrown when setMessage(String) is called to set the message. The message must be set before adding personalised destinations. When setMessage(String) is called to set a message containing variables, any destinations that had previously been added will be removed.

Adding Destinations

When the message containing variables has been set, phone numbers can be added to the destinations list by calling addRecipient(String, String) or addRecipient(String, String, Boolean). The total number of values passed to the methods must be equal to the total number of variables defined in the message.

This section takes a quick look at how to send personalised messages using the .NET SMS API. The API leverages most of the hurdles involved in sending personalised messages. Before messages can be sent using the API, some server and user settings need to be loaded. These values are loaded during authentication when user settings are identified. Therefore, it is necessary to perform authentication before setting message parameters. An object of type ZenophSMS is required for authentication and submission of message.

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

If authentication fails, SMSException will be thrown. Performing the authentication before setting message parameters is important and required. As indicated earlier, when authentication is successful, some personal and server settings are loaded from the server which are required to send SMS. Therefore, authentication must be performed before setting some message parameters. Exception will be thrown if authentication is not performed before setting most message parameters.

After successful authentication, message parameters can be set. With personalised messaging, the message body must be set before destinations are added since the variables defined in the message will be used to validate destinations and values to be added. Parameters like message type and sender ID may be set before or after setting the message body.

// set message parameters.
sms.setMessageType(MSGTYPE.TEXT);
sms.setSenderId("SMSTEST");

// the message body must be set before destinations are added. If there are
// any existing destinations, they will be cleared when the message is set.
sms.setMessage("Hello {$name}, the balance in your account {$acctnum} is ${$balance} as at 14th June, 2015.");

As was discussed under Non-Personalised Messaging, MSGTYPE is an enumeration that contains five message types which can be sent. The default that is set is the message type set in user account which is loaded during authentication. If no message type is explicitly set, the default for user account is used. However, the message type can be explicitly set by calling setMessageType(MSGTYPE) or setMessageType(String). The String argument to setMessageType(String) must be one of the String representations of MSGTYPE enumeration returned from getMessageTypes or messageTypeToString(MSGTYPE).

Personalised destinations can now be added to the destinations list once the message body has been set. The methods addRecipient(String, String, Boolean) and addRecipient(String, String) can be called to add personalised destinations. addRecipient(String, String) will always throw Exception if the destination or values are invalid. addRecipient(String, String, Boolean) may throw Exception when the destination or values are invalid but this depends on the value set for the first argument.

sms.addRecipient("233202988788", new string[] {"Sarah", "204.54"}, true);     // Throwing of Exception will be ignored if invalid.
sms.addRecipient("233202111199", new string[] {"Dennis", "308.00"}, false);   // Throwing of Exception will not be ignored if invalid.
sms.addRecipient("233501888874", new string[] {"Daniel", "575.35"});             // Throwing of Exception will not be ignored if invalid.

// phone numbers in local format. 
// Assume +233 is default international dial code to be used.
sms.addRecipient("0503898534", new string[] {"Emmanuel", "237.56"});          // destination will be 233503898534
sms.addRecipient("0269099989", new string[] {"Gideon", "780.43"}, true);      // destination will be 233269099989

// add destinations to different country, assume +234
sms.setDefaultDialCode("+234");
sms.addRecipient("0802908799", new string[] {"Ebenezer", "450.80"});          // destination will be 234802908799
sms.addRecipient("0809111198", new string[] {"Sheila", "350.90"}, true);      // destination will be 234809111198

The message can now be submitted with a call to submit method. For personalised messaging, a call to submit always returns a token which can be used to query the submit status of the destinations. A comprehensive discussion of querying submit status of destinations from returned token is provided in the page on Processing Submit Responses.