Personalised Messaging

Personalised messaging is as the name goes. It involves customising messages for individual destinations added to a message. In this case, each destination receives a message different from what others receive. This section covers our simplified approaches to sending personalised messages for destinations.

Personalised messaging is ideal when there are two or more message destinations each with data that is different from others. It is not necessary for situations where there is only one message destination.

With our approach, we will compose a single message template based on which customisations will be done. Within the message template, variables will be introduced in the parts of the message where each destination's values will be different from others. The customisation is done by the variables in the message template with each destination's values.

Drafting the Message

Suppose we want to send messages to clients informing them of the balance on their accounts. We can draft a simple message as follows:

Hello <NAME>, your balance is $<BALANCE>.

Our draft message does not apply to any specific message destination. It is a generic message template based on which we customise messages for destinations. Since each destination will have its own data distinct from others, it implies that some parts of the message will be different for each destination. We can introduce variables in those parts of the message where values will be different for each destination.

Defining Variables in Message

A variable is defined in a message by preceding the name of the variable with the dollar sign ($) all enclosed in curly brackets ({ and }). That is, {$VARIABLE_NAME}.

A variable name must begin with a letter or underscore (_) followed by other characters (alpha numeric). For example, the following are all valid variable names:

{$balance}, {$_amount}, {$grade2}, {$_var_2}.

However, the following are not considered to be variable names in a message:

{name}, {$2var}.

The variables should be defined in parts of the message where values will be different for each destination.

Composing Message Template

As said ealier, suppose we want to send messages to clients informing them of their balance on their accounts. We can compose a message template with the variables as follows:

// the message template with variables
string msgTpl = "Hello {$name}, your balance is ${$balance}.";

Notice that in the case of PHP, the message template is in single quote (') but not double quote ("). This is very important when composing message template for personalised messages. If the message template is double quoted, the PHP interpreter will consider it as a script variable and try to parse it and this will generate a PHP error. Since we do not want the PHP interpreter to parse the variables, the message template must be single quoted.

As can be seen, two variables have been defined in the message template. These are:

{$name}, and {$balance}

The presence of the variables in the message indicates that values will be substituted in those parts of the message where the variables have been defined before delivering to the destinations.

Warning

When using PHP, message templates for personalised messaging must be composed in single quotes as with double quotes, your PHP interpreter will attempt to parse the defined variables in the message. This may generate an error.

Setting Message Template

Once a message template has been composed, it can be set in code by calling setMessage(String, Boolean). In VB/VBA integration however, setMessageEx(String, [Object = Nothing]) must be called.

// compose the message template
string msgTpl = "Hello {$name}, your balance is ${$balance}.";
	
// set the message
request.setMessage(msgTpl);

With the presence of the variables in the message, setMessage() or setMessageEx() concludes that the message will be personalised to any added destinations. But what if our intention is not to personalise the message but rather send it as it is so that all destinations receive the same message as we have composed? We can achieve this with a second argument to setMessage() or setMessageEx() with a false value.

// compose the message template
string msgTpl = "Hello {$name}, your balance is ${$balance}.";
	
// set the message. We do not want it to be personalised
request.setMessage(msgTpl, false);

The second argument to setMessage() or setMessageEx() tells whether we want the message to be personalised or not. By setting it to false, we instruct that the message should not be personalised albeit having variables defined in the message template. If the second argument is not set, it is by default considered to be true and the messages will be personalised for each destination. Thus, explicitly setting the second argument to true has the same effect as ignoring it.

For personalised messaging, it is very important to set the message template before adding any destinations. When setMessage() or setMessageEx() is called and the message needs to be personalised, it resets the destinations list by clearing it. Thus, any destinations added previously will be removed.

Warning

For personalised messaging, setMessage() or setMessageEx() must be called before adding message destinations. This is because when called, the destinations list is reset and thus any destinations that were previously added before the call to setMessage() or setMessageEx() will be removed.

Adding Destinations

After setting the message template, phone numbers with their personalised values can be added to the destinations list. This is done by calling addDestination(String) or addPersonalisedDestination(). In the case of VB/VBA applications, addPersonalisedDestinationEx() must rather be called for adding personalised values.

Recall our discussions on Message Destinations. We emphasised that addDestination() is overloaded and accepts other arguments such as the Exception Control Specifier (ECS). The ECS is an indicator that tells whether Exception should be thrown or not when a phone number to be added to the destinations list fails validation.

With personalised text messaging, addDestination(), addPersonalisedDestination(), or addPersonalisedDestinationEx() accepts another argument which is the values to be substituted for variables defined in a message template for each destination. We can provide the personalised values as a third argument to addDestination() or addPersonalisedDestinationEx() as an array of String.

// compose message template
string msgTpl = "Hello {$name}, your balance is ${$balance}.";
	
// set message properties
request.setMessage(msgTpl);
request.setSender("TEST");
request.setSMSType(SMSType.GSM_DEFAULT);
	
// Some sample data for testing. You may obtain your data from database or file
List<string[]> clientsList = new List<string[]>();
clientsList.Add(new string[] {"0241111111", "Daniel", "954.87"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "732.91"});
clientsList.Add(new string[] {"233208888888", "Rebecca", "643.32"});
	
// add the data
foreach (string[] strArr in clientsList){
    // add to destinations list
    request.addDestination(strArr[0], false, new string[] {strArr[1], strArr[2]});
}
	
// submit the message.
MessageResponse response = request.submit() as MessageResonse;

In this code sample, we have created our own clients' data only for demonstration purpose. In production integration code, the data may be read from a database, file, or from user inputs. Notice that in VB/VBA, addPersonalisedDestinationEx() is rather called in stead of addDestination().

For each destination, we pass the personalised values as an array to addDestination() or addPersonalisedDestinationEx() as the third argument to the call. The order of the values in the array is very important. The order of the values must match the order in which the variables have been defined in the message template. Additionally, the number of variables must be the same as the number of items in the values array passed to addDestination() or addPersonalisedDestinationEx().

Warning

Always ensure that the order of the variables defined in the message template matches the order of the personalised values for substitution. If this is not so, values may be substituted for the wrong variable and the personalised message wouldn't be what was actually expected.

Now let's consider the following extract from the code:

// add the data
foreach (string[] strArr in clientsList){
    // add to destinations list
    request.addDestination(strArr[0], false, new string[] {strArr[1], strArr[2]});
}

As can be observed, we have passed false as the second argument to addDestination() or addPersonalisedDestinationEx(). This implies that if validation fails for the call, Exception should not be thrown but only ignore the specified destination. But during our discussions on Message Destinations, we understood that the Exception Control Specifier (ECS) is optional and defaults to true. Hence in non-personalised messaging, the following is a valid way of adding message destination.

// add destination
request.addDestination("233249999999");

Since the second argument (ECS) can be ignored, we can, in most cases, specify personalised values as the second argument to addDestination(). The only exceptional cases are when integrating in PHP, Python, and VB/VBA applications. With PHP, Python, and VB/VBA, the ECS must always be specified when adding personalised values.

// compose message template
string msgTpl = "Hello {$name}, your balance is ${$balance}.";
	
// set message properties
request.setMessage(msgTpl);
request.setSender("TEST");
request.setSMSType(SMSType.GSM_DEFAULT);
	
// some sample data
List<string[]> clientsList = new List<string[]>();
clientsList.Add(new string[] {"0241111111", "Daniel", "954.87"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "732.91"});
clientsList.Add(new string[] {"233208888888", "Rebecca", "643.32"});
	
// add the data
foreach (string[] strArr in clientsList){
    // add to destinations list
    request.addDestination(strArr[0], new string[] {strArr[1], strArr[2]});
}
	
// submit the message.
MessageResponse response = request.submit() as MessageResonse;

Observe that with the exception of PHP, Python, and VB/VBA, the personalised values have been passed to addDestination() as the second argument. This is because the Exception Control Specifier (ECS) defaults to true and therefore can be ignored if the default serves right. In this case, when adding destinations in an iteration and destination validation fails, the iteration will be terminated and Exception thrown. If we do not want the iteration to be terminated when validation fails for a destination, the ECS must be explicitly specified with false as the second argument and the personalised values specified as the third argument to addDestination().

Warning

PHP, Python, VB/VBA: When using PHP, the Exception Control Specifier (ECS) must always be specified when adding destinations for personalised messages. This means that with PHP, Python, and VB/VBA, personalised values must always be supplied as the third argument to addDestination() or addPersonalisedDestinationEx().

Multiple Values for Single Destination

With personalised messaging, multiple set of values can be added for a single destination. In this case, the same destination will receive multiple messages each with different personalised values. Consider the following code:

// compose message template
string msgTpl = "Hello {$name}, your balance for account {$accountNum} is ${$balance}.";
	
// set message properties
request.setMessage(msgTpl);
request.setSender("TEST");
request.setSMSType(SMSType.GSM_DEFAULT);
	
// Some sample data for testing. You may obtain your data from database or file
List<string[]> clientsList = new List<string[]>();
clientsList.Add(new string[] {"0241111111", "Daniel", "6024321", "954.87"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "6025121", "732.91"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "6025221", "643.32"});
	
// add the data
foreach (string[] strArr in clientsList){
    // add to destinations list
    request.addDestination(strArr[0], false, new string[] {strArr[1], strArr[2]});
}

By carefully observing clients' data, it can be seen that Emmanuel has two accounts each with its own balance. Additionally, Emmanuel's phone number is the same for both accounts.

After adding the destinations, Emmanuel will have two sets of values for the same destination (0242999999). This is because the values are not unique and so two separate messages will be composed for the destination from the template. In this case there are two destinations but three messages will be sent with Emmanuel receiving two messages.

When adding personalised destination, addDestination() or addPersonalisedDestinationEx() checks to see if the destination exists or not. Whether the values will be added or not depends on the result after checking if the destination already exists or not.

If the destination exists, it also checks whether the same values have been added or not. If the values are not the same as pre-existing values, it adds to the collection of values for the destination. If the same values exist, it will be ignored and addDestination() or addPersonalisedDestinationEx() will return NumberAddInfo.NAI_REJ_VALUES_EXIST enumerator constant to indicate that the request to add the destination was rejected.

If the destination does not exist, addDestination() or addPersonalisedDestinationEx() adds the phone number to the destinations list and also adds the values to that destination's collection of values.

The analogy here is that a destination can have multiple sets of values as long values are not the same for the destination.

Updating Personalised Values

Sometimes, there may be the need to update personalised values for a message destination. This is done by calling updatePersonalisedValues(). This method is overloaded and can be called in three ways. The required method in VB/VBA integration is updatePersonalisedValuesEx().

Update of values is done by replacing existing values with new values. But we now know that with personalised messaging, each destination can have multiple sets of personalised values. Therefore, we can replace specific set of values with new values or replace the entire collection of existing values with new values.

In order to clarify these cases, we make reference to the previous sample code for updating personalised values.

// We want to make a change in amount 
// Let's specify previous values
string[] prevValues = clientsList[1];
	
// phone number
string phoneNumber = prevValues[0];
	
// First, set newValues to prevValues and change the amount 
string[] newValues = prevValues;
newValues[3] = "423.53";
	
// We now have two distinct values sets
// prevValues:	{"0242999999", "Emmanuel", "6025121", "732.91"}
// newValues:	{"0242999999", "Emmanuel", "6025121", "423.53"}
	
// now perform update
request.updatePersonalisedValues(phoneNumber, newValues, prevValues);

As can be seen, Emmanuel has multiple sets of personalised values. We can replace all sets of values with new values or replace only specific values of the collection with new values.

Replacing All Values

Suppose we want to discard all personalised values that have been added and then set new personalised values. We can achieve this in two different ways in terms of the search for the destination. The search for the destination can be done by using the phone number or it can be done by using a unique identifier assigned to personalised values of a destination.

Replacing All Values By Phone Number

To replace all exising personalised values with new values, we only need to call updatePersonalisedValues() or updatePersonalisedValuesEx() with the new values we want to set whiles specifying the phone number that will be affected as the first argument.

// new values to be set
string[] clientInfo = new string[] {"0242999999", "Emmanuel", "6025121", "1,458.53"};

// update the values. discard any existing values
string phoneNumber = clientInfo[0];
string[] newValues = new string[] {clientInfo[1], clientInfo[2], clientInfo[3]};
request.updatePersonalisedValues(phoneNumber, newValues);

Since the call to updatePersonalisedValues() or updatePersonalisedValuesEx() does not specify which values in the existing collection to update, the collection of the existing personalised values will be emptied and newValues will be added to the collection as the only set. To update only a specific set in the collection without losing all values, the personalised values to be updated must be specified as the third argument to updatePersonalisedValues() or updatePersonalisedValuesEx().

Warning

When updating personalised values for a destination, the specific set of values to be updated must be supplied to updatePersonalisedValues() or updatePersonalisedValuesEx() as the third argument otherwise all sets of values already added will be discarded and replaced with the new values provided to the method.

Just as client applications can generate and assign unique identifiers when adding destinations, it is also possible to generate and assign a unique identifier to destination when replacing personalised values.

As this is a replacement, the existing values and unique identifiers will all be cleared and the newly specified unique identifier will be assigned to the new personalised values for the destination. In this case, the search for destination is by the use of a phone number and the unique identifier is only assigned to the new values for the destination. A sample code is provided as follows.

// new values to be set
string[] clientInfo = new string[] {"0242999999", "Emmanuel", "6025121", "1,458.53"};

// update the values. discard any existing values
string phoneNumber = clientInfo[0];
string[] newValues = new string[] {clientInfo[1], clientInfo[2], clientInfo[3]};
request.updatePersonalisedValues(phoneNumber, newValues, "b3115ee-4cf5-40b0-bcfe-3ea9f346e118");

Remember in the case of values replacement for a destination, the method updatePersonalisedValuesEx() is called in the case of VB/VBA. In this case of replacement and assignment of unique identifier at the same time, updatePersonalisedValuesExWithId() is rather called.

Another difference is the method call in PHP sample code. In the case of replacing personalised values without assigning unique destination identifier, updatePersonalisedValues() was called. However, when replacing personalised values and also assigning unique identifier to the new values, updatePersonalisedValuesEx() was rather called.

Replacing All Values By Destination Id

Replacing all existing personalised values with new values using unique destination identifier requires a method call to updatePersonalisedValuesById. In this case, the search for the destination is done by using the specified unique destination identifier. If found, existing personalised values will be replaced with the new values passed as argument to the method call. If the specified unique destination identifier does not exist, Exception will be thrown.

// new values to be set
string[] clientInfo = new string[] {"0242999999", "Emmanuel", "6025121", "1,458.53"};

// update the values. discard any existing values
string phoneNumber = clientInfo[0];
string[] newValues = new string[] {clientInfo[1], clientInfo[2], clientInfo[3]};
request.updatePersonalisedValuesById("b3115ee-4cf5-40b0-bcfe-3ea9f346e118", newValues);

Replacing Specific Values

Recall that Emmanuel has multiple sets of personalised values with $732.91 as the balance for account 6025121 and $643.32 as the balance for account 6025221. Suppose we want to update the balance of account 6025121 to $423.53. We will need to specify the set of personalised values that we want to update and also provide the new personalised values that we want to set.

// We want to make a change in amount
// Let's specify previous values
string[] prevValues = clientsList[1];

// phone number
string phoneNumber = prevValues[0];

// First, set newValues to prevValues and change the amount
string[] newValues = prevValues;
newValues[3] = "423.53";

// We now have two distinct values sets
// prevValues:	{"0242999999", "Emmanuel", "6025121", "732.91"}
// newValues:	{"0242999999", "Emmanuel", "6025121", "423.53"}

// now perform update
request.updatePersonalisedValues(phoneNumber, newValues, prevValues);

From the code sample, the call to updatePersonalisedValues() or updatePersonalisedValuesEx() will look in the values collection for destination 0242999999, check for values with the same data as prevValues and then replace it with newValues. In this case, other sets of values for the destination will be preserved.

The method returns true if prevValues is found and successfully replaced with newValues. Otherwise it returns false.

Getting Personalised Values

The personalised values added for any destination can be obtained either for display or for any other reasons. As with values update, personalised values can be obtained in two ways. They can be obtained either by using a phone number for the search or by using a unique destination identifier if assigned. The return value will differ in each case though both return values enable client applications to obtain an array of String of the values.

Using Phone Number

To get personalised values for a destination, a phone number can be used for the search for the values. Recall that it is possible for a single phone number to have multiple values as long as the values for the destination are not the same. This means that it is possible for multiple sets of values to exist for a destination. As a result of this, a List of an array of String will be returned. The list object returned is a custom List object of PersonalisedValuesList. PersonalisedValuesList exists in the Zenoph.Notify.Collections namespace. Iterating through the PersonalisedValuesList returns an array of String which are the values added.

To get the collection of values for a destination, getPersonalisedValues() must be called by passing the phone number as an argument to the method call. We will take a previously encountered sample code and extend it by getting the personalised values for display.

// compose message template
string tpl = "Hello {$name}, your balance for account {$accountNum} is ${$balance}.";

// set message properties
request.setMessage(tpl);
request.setSender("TEST");
request.setSMSType(SMSType.GSM_DEFAULT);

// some sample data
List<string[]> clientsList = new List<string[]>();
clientsList.Add(new string[] {"0241111111", "Daniel", "6024321", "954.87"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "6025121", "732.91"});
clientsList.Add(new string[] {"0242999999", "Emmanuel", "6025221", "643.32"});

// add the data
foreach (string[] strArr in clientsList){
    // add to destinations list
    request.addDestination(strArr[0], false, new string[] {strArr[1], strArr[2], strArr[3]});
}

// We want the values for the phone number 0242999999
string phoneNumber = "0242999999";
PersonalisedValuesList valsList = request.getPersonalisedValues(phoneNumber);

// Iterate to display. Each Iteration returns string[]
foreach (string[] vals in valsList){
    // an array of String so join them for single String
    Console.WriteLine(string.join(", ", vals));
}

As earlier indicated, a call to getPersonalisedValues() returns an object of PersonalisedValuesList which is a List object containing an array of String as the set of values for the destination. If the specified phone number is not found in the destinations list, the method returns null.

Removing Personalised Values

Personalised values already added to the collection of values for a destination can be removed. This can done by calling removePersonalisedDestination(). There is however a restriction with this method call. The destination for which values are to be removed must have multiple sets of values and the specific set of values to be removed must be supplied to the method.

From our sample code, Emmanuel has multiple sets of personalised values so we can remove one set of the values. Suppose we want to remove values for account 6025221:

// We want to remove values. Get the values
string[] clientInfo = clientsList[1];

// phone number and values
string phoneNumber = clientInfo[0];
string[] values = new string[] {clientInfo[1], clientInfo[2], clientInfo[3]};

// delete the values
request.removePersonalisedValues(phoneNumber, values);

If the set of values passed to removePersonalisedValues() exists in the destinations list, it will be removed for that destination and true is returned. If it does not exist, the method does nothing to the destinations list and returns false.

As said earlier, the destination must have multiple sets of values before calling removePersonalisedValues() on that destination. This is because if there is only one set of values and it is being removed, that destination will have no personalised values to be used for variables substitution. If the motive is to remove the destination, then removeDestination() must rather be called.

Warning

Do not call removePersonalisedValues() on a destination with single set of personalised values as this will throw Exception. This is not allowed because if the values are removed, there will be no personalised values for the destination for variables substitution.